Model Caller Types
Share typed prompts, tool results, and completed responses between a harness
and the model bridge. link_model_contract::chat gives callers one message
representation while its optional client maps that representation to providers.
Choose the Boundary
The model action interface
owns HTTP routes, grants, and command output. A library caller uses the types
below to construct or read those requests without duplicating their fields.
The client feature additionally exposes provider request and stream mapping.
Borrowed Prompts
Prompt borrows the system text, messages, tools, price jumps,
and prompt-section spans for a call. The caller supplies its answer and window
limits, thinking settings, and whether tools may be called. chat and parent
identify the work for context reporting rather than authorizing execution.
Owned Requests
Chat owns the corresponding values for a serialized request and has an
optional model name. Chat::prompt borrows those values without rebuilding
history or changing the requested limits. Deserialization refuses unknown
request fields, while Chat::check performs the semantic checks below.
Validate a Chat
Validation belongs at the request boundary before a provider sees the data.
Chat::check checks limits, offered tools, message roles, and media. It does
not execute tools or enforce a harness’s conversation-persistence policy.
Answer and Window
The answer limit must be positive and fit within the requested window. Those numbers describe this request. Model selection, known model limits, and a caller’s budget remain responsibilities of the model bridge and harness.
Tool Definitions
A Tool has a name, description, and object-valued JSON schema. Validation
requires a name of 1 to 128 ASCII letters, digits, underscores, or hyphens.
An offered definition tells the model what it may request. Permission to
execute that request still comes from the tool’s own grant.
Message Roles and Parts
A Message has a user or assistant role, text, calls, answers, provider
thinking blocks, and media parts. Fields omitted from its serialized form
use their declared defaults. The checker reconstructs each media part through
Media::new and refuses a kind that disagrees with its MIME type.
Preserve Tool Continuation
A model’s Call names the requested tool and arguments with a call ID.
An Answer names the call it answers, its text, failure flag, and any media.
Keeping both structured records lets the next model request associate the
result with its request rather than treating it as an unrelated user message.
Provider Continuation
Message::thinking and Answered::thinking retain provider-owned JSON blocks.
The caller preserves those blocks alongside visible text. Their meaning and
wire representation belong to the provider mapping; the shared message type
does not replace them with a summary or infer an execution effect from them.
Persistence and Recovery
The message representation contains enough structure to retain calls and results, but storing it is the harness’s responsibility. For example, Mini checks for unanswered calls before another turn. The model client supplies neither a conversation store nor a policy for replaying interrupted tools.
Read a Completed Response
Answered holds visible text, requested calls, thinking, optional model and
response identifiers, token counts, latency, optional cost, and an interrupted
flag. A caller keeps the completed response separately from the text pieces
it displayed while the provider was still answering.
Stream Events
Stream is tagged by event. A text event contributes displayed text;
an answer event contains the completed Answered; an error event contains
a failure kind and message. A client cannot infer a completed answer from
having received text alone.
Failure Kinds
The shared failure vocabulary is unreached, too_long, overloaded, and
refused. These distinguish connection or initial-response failure, a prompt
outside the window, provider capacity failure, and other refusals. The caller
decides whether a fallback or another user action is appropriate.
Use the Provider Client
With client enabled, chat::client exposes the shared
provider mapping used by the bridge and standalone callers. Its Model
holds the caller-supplied provider, model name, base address, and credential.
Those backend values are separate from the serialized Chat request.
Request and Response Mapping
The client builds Anthropic or OpenAI-compatible request bodies and reads
their streaming responses into Answered. Provider-specific request helpers
and reply decoders stay beside that client, so a harness can reuse them
without maintaining another provider protocol implementation.
Cancellation and Initial Wait
answer accepts the caller’s cancellation receiver and a channel for text
pieces. answer_within additionally bounds the initial response wait when
the caller supplies one. Cancellation and timeouts concern that model call;
the caller still owns its saved turn, tool cleanup, and subsequent policy.
Other Model Actions
api defines closed request and answer shapes for embeddings,
transcription, token counting, status, usage, and context reporting. Embed
contains texts and an optional model; Transcribe names a model and audio;
Count contains text and an optional model. Their answers carry vectors,
transcribed text, or a token count without provider-specific response fields.
Read Operations
Status reports readiness and loaded model names. Usage reports request,
unmetered-request, and token totals. ContextOf optionally selects a chat;
Context returns retained chat metadata and an optional report. The bridge
owns authorization, operation availability, and the meaning of unavailable
results, as the action interface explains.