ai

One model step over the conversation + tool schemas — THE provider seam. A provider module serves this request for the extent of a continuation (use gemini.provider(...)), so the loop stays provider-agnostic and providers stay loop-agnostic.

Infer a single reply with no tools (the common chat case).

Tool: load an image file into your visual context. Pass the file's handle object — a bare {"$katari_ref": "<id>"} suffices (copy the id from the conversation); the image content arrives with this tool's result, so you can see it on your next step.

Run the tool-using model loop, generic over the tools' shared effect E: derive each tool's schema with reflection.get_metadata, then up to max_steps times perform infer_step against the ambient provider; on a batch of tool calls, dispatch them all CONCURRENTLY with parallel for (each resolves its tool by name and invokes it by value via reflection.call_agent, validating the model's args against the tool's schema), then feed every result back as a new turn; on a final answer, return it.

Find the tool whose metadata name is the model's pick and invoke it by value via reflection.call_agent (the model's args ride as a plain value, and the delegation boundary validates them against the tool's schema — the compiled signature of a Katari agent, or the server-declared schema of an MCP tool — while the boundary's unconditional wire→value conversion turns any replayed $katari_ref into the file it denotes). A hallucinated name or a panicking tool is fed back as an error result so the model corrects on the next step; genuinely malformed args are a reflection.call_error that escalates to the app root (loop_error). The result's file values are collected off the result tree so the provider can show them to the model (their $katari_ref handles are already visible in the result text).

Collect every file value out of a tool result's value tree: reflection.call_agent returns the tool's result as a plain value, so a file the tool produced (a generated image, an MCP tool's screenshot) is an actual file leaf — found wherever it sits (a bare return, the MCP bridge's { text, files } record, or nested structure).

The infer_with_region nursery scope: a nullary phantom marker carried by every monitor fiber, minted and discharged by the loop's region.provide so no fiber outlives the loop.

THE monitor→model channel: a background monitor reports content (plus any files attached to it) from source and receives the model's answer back. It is the only effect a monitor raises besides io, which pins the nursery's ceiling to one row so a single region.watch covers every monitor. A source fiber or a started monitor performs it; the loop's own handler answers it by running a model turn over the injected report. files ride the injection turn's files slot — the same text + files split as types.turn — so the provider's existing inline policy shows the model any attached image.

The loop's durable state, threaded across every observation: the running conversation and the registry of started monitors (a stable id → the fiber handle region.cancel needs). The id is what the model holds and passes back to stop a monitor.

One model turn's outcome: the reply handed back to the reporting fiber, plus the advanced session the loop persists for the next observation.

One routed tool call: the model-facing result plus the possibly-grown monitor registry (a started monitor adds its id → fiber; a stop or a synchronous tool leaves it be).

One routed batch: the registry after the whole batch plus the results in call order — one var so the batch fold threads both at once.

Tool: STOP a background monitor you started earlier. Pass the monitor id you were given when it started. The region loop INTERCEPTS this call (only the loop holds the nursery region.cancel needs), so this body is the schema seam and never runs; it returns a note so a stray direct call stays total.

Route one tool call inside the region loop: STOP a monitor (cancel_monitor — cancel the fiber the model's id names), START a monitor (a name in monitors — region.fork it detached and hand the model its id), or run a SYNCHRONOUS tool (anything else — dispatch_one, exactly as infer_with_tools). Returns the model-facing result with the possibly-grown registry.

One model turn-loop over conversation WITH region powers — the region-aware twin of the infer_with_tools loop. Up to max_steps times: ask the provider for a step; on a tool batch, route every call (route_region_call: a synchronous tool feeds its result back, a monitor tool forks a detached fiber whose id feeds back, cancel_monitor stops one), record the call + result turns, and continue; on a final answer, stop. Budget spent, force one tool-less close (as infer_with_tools). Returns the reply plus the advanced session (conversation + monitor registry).

Run the tool-using model loop over a region nursery, so the model can START background monitors and STOP them — the long-lived sibling of infer_with_tools. tools are synchronous (called and awaited, exactly as infer_with_tools); monitors are startable background fibers the model launches as tools (each forks detached and notifies the model through observation) and stops with cancel_monitor; sources are always-on input fibers forked at startup (e.g. a chat watcher that turns each user message into an observation) and are NOT shown as tools. context seeds the conversation the model always sees, and region_instructions (overridable) teaches the model the start / stop protocol, since a model is trained on tool calls but not on this fork / cancel discipline.

Returns never: structured concurrency cancels every fiber when the nursery closes, so to keep monitors alive the loop never returns — the model's replies leave through the observation channel (each is the answer handed to the fiber that reported), and the loop runs until the run is cancelled. The provider (use gemini.provider(...) …) and any E handlers are installed by the caller, exactly as for infer_with_tools.

A deterministic two-way mapping between a tool's real (qualified) name and the shortened name a provider sends on the wire. real_to_wire is keyed by the qualified name (used when encoding a tool declaration or replaying a call turn), wire_to_real by the wire name (used to reverse the model's pick); both are total over one step's tools — see build_name_map.

Fold a wire name onto a qualified name: every character outside a provider's [a-zA-Z0-9_-] name alphabet (the dot of a qualified name, above all) folds to _, then the result is capped at the providers' 64-character limit.

Disambiguate a colliding wire name with an ordinal suffix (_2, _3, …), reserving room so the result still fits the 64-character cap.

Choose a free wire name for real given the wire names already taken: its sanitized form, or — when sanitizing collapsed two distinct qualified names onto one token, or truncation shared a prefix — the first free ordinal-suffixed form. The suffix is decided by taken's size (processing order), so the choice is deterministic.

Build the deterministic wire-name name_map for one step's tools. Walking tool_metas in order, each tool's qualified name is assigned a free wire name against the names already placed, so the same tool list always yields the same map — which is why the map needs no durable state (see the section note). A provider whose wire vocabulary admits the qualified name (Gemini) never calls this.

The wire name for a qualified tool name — used to encode a tool declaration and to re-encode a replayed call turn. Falls back to the qualified name for a tool absent from the map (never happens for a map built from the same step's tools).

The qualified tool name for a wire name — used to reverse the model's pick so the loop dispatches by the real name. Falls back to the wire name itself for an unknown name (a hallucinated tool), which the loop then reports as an unknown tool.

An Anthropic connection: the model id, the API key, an optional system prompt, and the output-token cap the Messages API requires on every request. Provider handler state — built once per use anthropic.provider(...).

Serve ai.infer_step over Anthropic for the extent of the continuation: use anthropic.provider(api_key = env.get_secret(key = "ANTHROPIC_API_KEY")). A step's provider failure (ai.step_error) is raised here, at the provider's use site.

Map the vocabulary role onto the Messages API role: our "model" speaks as "assistant".

Every file of a turn as a handle note, joined for the turn's text. The $katari_ref handle is the exact object the model replays into a tool call (view_image to re-see it, send_files to post it), so the note is the replay affordance — kept for an image too, alongside the image block that lets the model SEE it (see anthropic_turn_content).

The file's recorded content type, or "" when the handle is gone (freed, or never named a live blob). A gone file cannot inline — its handle note still rides — so gone folds to the same "not an image" signal as an unrecorded type, and never fails a whole step over one stale attachment.

Whether a file inlines as an Anthropic image block: its recorded content type begins "image/" (the Messages API image block takes only image media types). A file with another or no recorded type stays a handle note.

A text content block — { "type": "text", "text": @text@ }, built as a raw value tree.

An image content block: a base64 source whose media_type is the file's recorded type and whose data slot holds the file VALUE placed DIRECTLY into the tree. http.json materialises that slot — reading the bytes and base64-ing them in place — only at the send boundary, so the image content never rides the value plane, the durable call record or the trace.

A turn's content: the plain string (text + every file's handle note) when the turn carries no image, or an array of one text block plus one image block per image file when it does. An image file inlines so the model can SEE it; a non-image file stays a handle note (the image block takes only images). The text block still carries every file's handle note, so the model can replay any of them into a tool.

One Anthropic model step over the history + tool schemas (the body built as a value tree and the reply parsed by post_json in Katari; only the POST leaves the runtime, and each image file in the body base64s at that send boundary via the http.json slot contract).

A Gemini connection: the model id, the API key, and an optional system instruction. Provider handler state — built once per use gemini.provider(...).

Serve ai.infer_step over Gemini for the extent of the continuation: use gemini.provider(model = "gemini-3.5-flash", api_key = env.get_secret(key = "GEMINI_API_KEY")). A step's provider failure (malformed JSON, a non-2xx status, a transport failure — ai.step_error) is raised here, at the provider's use site.

The file's recorded content type, or "" when the handle is gone (freed, or never named a live blob). A gone file cannot inline — its handle note still rides — so gone folds to the same "cannot inline" signal as an unrecorded type, and never fails a whole step over one stale attachment.

A file's content as an inlineData part — what lets the model actually SEE an image. The data slot holds the file VALUE placed DIRECTLY into the tree; http.json reads its bytes and base64s them in place only at the send boundary, so the content never rides the value plane. Only the freshest history element inlines, which keeps the WIRE request small (see gemini_content's inline).

A file as its $katari_ref handle note — the resting representation. The handle is the exact object the model replays into a tool call (view_image to re-see it, send_files to post it), so the note IS the affordance, not just a description.

Render a turn's / result's files: inlined (content + handle note, so the model both sees the image and learns the handle to replay) while fresh, the handle note alone once older — the model re-reads an old image on demand with view_image. A file with no recorded MIME type cannot inline.

One history element as a Gemini content. inline marks the freshest element — the only one whose files inline their content (older elements show handles only, keeping the request small; the model re-reads any old image with view_image).

Whether a response part is the model's internal thinking: Gemini interleaves thought summaries (marked thought: true) with the answer parts — never user-facing text.

One Gemini model step over the history + tool schemas (the body built as a value tree and the reply parsed by post_json in Katari; only the POST leaves the runtime, and each inlined image file in the body base64s at that send boundary via the http.json slot contract).

An OpenAI connection: the model id, the API key, and an optional system prompt. Provider handler state — built once per use openai.provider(...).

Serve ai.infer_step over OpenAI for the extent of the continuation: use openai.provider(model = "gpt-4o-mini", api_key = env.get_secret(key = "OPENAI_API_KEY")). A step's provider failure (ai.step_error) is raised here, at the provider's use site.

A turn's files as text notes appended to its content. This provider keeps files handle-only (no image inlining — the Gemini and Anthropic providers are the multimodal ones); the handle note still lets the model replay a file into a tool call (view_image / send_files).

One OpenAI model step over the history + tool schemas (the body built as a value tree and the reply parsed by post_json, in Katari; only the POST leaves the runtime).

One turn in a conversation: who spoke ("user" / "model"), what they said, and any files attached to it (a Discord attachment, a generated image). Files ride as blob handles; each provider decides when to inline their content for the model (see the providers' inline policy).

One tool the model wants to invoke this step — name is its function name (the dispatch key and the model-facing call/response record), opaque is any provider token that must be replayed verbatim on the call turn (Gemini's thought signature, OpenAI's call id), args is the model's argument object as a parsed value (replayed verbatim into the call turn, and dispatched straight through reflection.call_agent, whose delegation boundary unconditionally turns any $katari_ref the model replayed into the file it denotes).

A tool's output for the model, keyed by the tool name / call_id so it round-trips as a function response. files are the file values found in the result (a screenshot an MCP tool returned, an edited image): text already shows their $katari_ref handles (the result's wire form), and the provider additionally inlines their content for the model while the result is fresh.

A conversation turn recording the model's tool-call batch — replayed so the next step shows the model what it already asked for.

A conversation turn carrying the results of a tool-call batch.

One inference step's decision: a final reply text for the user.

One inference step's decision: invoke a batch of tools (dispatched in parallel, results fed back together).