cosmonic:agent interfaces

cosmonic:agent is the WIT package an agent harness and its tools are built against. This page covers version 0.4.2. The .wit files in agent-sdk are the contract; this page summarizes them.

Package

Property	Value
Package	cosmonic:agent@0.4.2
Published	ghcr.io/cosmonic-labs/cosmonic/agent (an OCI artifact)
Source	wit/cosmonic-agent/*.wit in cosmonic-labs/agent-sdk
Fetch	wash wit fetch with WKG_CONFIG_FILE set to wit/wkg-registries.toml
WASI	WASI 0.3 (wasi:clocks@0.3.0 types in run-types)

The registry mapping in wit/wkg-registries.toml tells wash and wkg that the cosmonic namespace is published under ghcr.io/cosmonic-labs/.

Versioning

• A breaking change bumps the minor version (0.4 to 0.5). Adding a case to a variant, a field to a record, or a function to an interface a guest exports (tools, run) is breaking.
• An additive change bumps the patch version (0.4.0 to 0.4.1) and carries @since on the new items. A component built against 0.4.2 links to a host entry that names 0.4.0.
• Published versions never change.

Unstable items

Items marked @unstable(feature = agent-run) may still change. A component sees them only when it enables the feature, for example in Rust:

wit_bindgen::generate!({
    path: "wit",
    world: "minimal-agent",
    features: ["agent-run"],
    generate_all,
});

In 0.4.2 the unstable items are the run, run-types and compact interfaces and the worlds that use them.

Worlds

World	Stability	Imports	Exports	For
agent	stable	inference-types, models, chat, tools, session		A harness's reach: models by alias, tools, its conversation
runnable-agent	unstable	everything in agent	run	A harness a host can drive. minimal-agent targets this world.
compactable-agent	unstable	everything in agent	run, compact	A harness that also summarizes its context on request
run-client	unstable	run		A component that drives runs, such as a protocol adapter or a test double
compact-client	unstable	run, compact		A driver for a compactable-agent
tool-provider	stable		tools	A tool that lists its own definitions and parses JSON itself, such as an MCP bridge
inference-provider	stable		inference-types, model-admin, chat, embeddings	A trusted model provider
inference-client	stable	inference-types, model-admin, chat, embeddings		A trusted serving component, such as an OpenAI-compatible server
chat-provider	stable		inference-types, model-admin, chat	A provider that serves chat only
embeddings-provider	stable		inference-types, model-admin, embeddings	A provider that serves embeddings only

A typed tool targets no cosmonic:agent world. It exports its own interface, and the host builds tool definitions from it. See Write a typed tool.

Interfaces

Interface	Since	Stability	Used by a harness as	Purpose
inference-types	0.4.0	stable	import (types)	Messages, model handles, options, usage and errors
models	0.3.0	stable	import	Open a model by alias
chat	0.3.0	stable	import	Stream a reply from a model
embeddings	0.3.0	stable	not in agent	Text embeddings from a model
tools	0.4.0	stable	import	List and call tools
tool-types	0.4.0	stable	import (types)	Tool definitions, responses and errors
session	0.3.0	stable	import	The conversation journal and the harness's working state
run		unstable	export	Take one message and work until a reply
run-types		unstable	import (types)	Run options, events, outcomes and errors
compact		unstable	export	Summarize older context between runs
model-admin	0.3.0	stable	not in agent	Trusted catalog and model preparation, for providers
model-residency	0.3.0	stable	not in agent	Trusted controls for keeping local models loaded

Type-only interfaces (inference-types, tool-types, run-types) have no functions. Importing one grants nothing.

models

Opens a model by a workload-scoped alias, such as default. The host decides what the alias means; see Choose the model an agent uses.

Function	Signature
open	async func(alias: string) -> result<model, open-error>
describe	async func(alias: string) -> result<model-description, open-error>

open-error cases: unknown-alias, denied, unavailable, too-large (the alias is over the host's byte limit), other.

model-description reports what the host knows: model (the provider's model name), supported-operations, context-length, max-output-tokens, tools, reasoning, accepts (media types), response-formats and supported-options. Each field is optional.

chat

Function	Signature
chat	async func(model: borrow<model>, messages: stream<message>, messages-done: future<result<_, string>>, options: chat-options) -> result<reply, request-error>

reply is tuple<stream<chunk>, future<result<completion, generation-error>>>. Write the messages while the call is pending, close the stream, then resolve messages-done. Drain the chunks before awaiting the outcome. Dropping the chunk stream asks the provider to cancel.

Errors before acceptance are request-error (for example context-length-exceeded, not-authenticated, rate-limited, quota-exhausted). Errors after acceptance arrive on the outcome future as generation-error.

chat-options fields include max-tokens, temperature, top-p, stop, response-format, tools (the tool definitions offered to the model), tool-choice, parallel-tool-calls, thinking, effort, meta and on-unrepresentable. Unset fields take the provider's defaults.

tools

The same interface is imported by a harness and exported by a tool provider.

Function	Signature
list	async func() -> result<list<tool-def>, list-error>
call	async func(request: tool-call) -> result<tool-response, call-error>

• list fails with list-error (unavailable, denied, other) rather than returning an empty list when tools cannot be described.
• call takes the model's tool-call (id, name, arguments) as it came. arguments is json(json) or text(string).
• A retry reuses the same id and arguments.

find_tools and load_tools are not functions in this interface. They are tool names a host reserves for its own discovery tools, offered in list next to the session's other tools. A provider never uses those names.

tool-types

Type	Fields or cases
tool-def	name, title, description, input (tool-input), output-schema, annotations, version
tool-input	json-schema(json), grammar(grammar), text (defined in inference-types)
tool-annotations	read-only, destructive, idempotent, open-world. Display hints only; they authorize nothing.
tool-response	output (list of text or attachment), structured (JSON matching output-schema), is-error (the tool ran and failed)
call-error	not-dispatched(dispatch-error): this attempt had no effect. outcome-unknown(outcome-error): it may have.
dispatch-error	unknown-tool, invalid-arguments, upstream, denied (a person or policy refused), cancelled, timed-out, other
outcome-error	upstream, cancelled, timed-out, other

A host may cap a tool's output. When it does, it appends a text part that says so and states the original size.

session

A host-owned, append-only journal plus opaque working state. The host chooses the session and binds it; a caller never names one.

Function	Signature
current	async func() -> result<snapshot, error>
commit	async func(entries: list<new-entry>, state: option<list<u8>>, options: commit-options) -> result<commit-result, error>
read	async func(start: u64, max: u32) -> result<list<entry>, error>
follow	async func(start: u64) -> result<stream<entry>, error>
clear	async func() -> result<_, error>

Type	Fields or cases
entry	seq, author (stamped by the host), at-ms (stamped by the host), kind, data
new-entry	kind, data
state	value, version, through (the journal end the state covers)
snapshot	state (none before the first write or after clear), end
commit-options	require-state (absent or version), require-end, commit-id (retained for at least the latest 1024 commits)
commit-result	committed (end, version) or stale(snapshot): a condition failed and nothing was written
error	too-large (scope: entry, session or host; limit; entry), invalid-argument, unavailable, other

A commit that writes state must set both require-state and require-end. Read with read until it returns an empty page; a short page does not mean the end.

Reserved entry kinds

All agent.* kinds are reserved. Each data is JSON. Readers skip kinds and fields they do not understand.

Kind	Holds
agent.step.v1	A message: role (user, assistant, tool, error), text, blocks, tools, and run when written by a run
agent.op.v1	A model or tool call before it starts: op, target (model or tool), name, tool arguments
agent.op-result.v1	The call's end: op and outcome (succeeded, failed, cancelled or unresolved)
agent.run.v1	run, the run id, in the commit that opens a run (commit id run:<run-id>)
agent.run-result.v1	run and outcome (done, failed or cancelled) with finish or the error, in the commit that ends the run
agent.compact.v1	compact and optional focus, in the commit that accepts a requested compaction (commit id compact:<id>)
agent.compact-result.v1	compact, outcome, and compacted
agent.compaction.v1	summary, model, trigger (threshold, overflow or requested), through, kept, tokensBefore, tokensAfter, focus
agent.plan.v1	entries, the whole current plan as {content, status}; the latest one replaces earlier ones
agent.context-reset.v1	{}, when unreadable saved state requires a fresh context

run (unstable)

Exported by a harness and called by its driver. A run is one message and everything the harness does to answer it.

Function	Signature
run	async func(message: user-message, options: run-options) -> result<started-run, start-error>

started-run is tuple<stream<run-event>, future<result<run-outcome, run-error>>>. run resolves once the harness has committed the message and agent.run.v1, not when the run ends. Dropping the event stream asks the harness to cancel.

run-types (unstable)

Type	Fields or cases
run-options	run-id (unique per session), instructions, schema (JSON Schema for the final reply), max-steps, max-total-tokens, max-duration, effort, trace-parent
run-event	text-delta, reasoning-delta, step, counts, compacted, plan, other
step	content (assistant, tool, user, error, other) and seq of its journal entry
run-counts	steps (model calls), tool-calls, usage
run-outcome	reply (list of reply-part), structured, counts, finish, model (alias, model)
finish	done, input-required, max-steps, max-total-tokens, max-duration, refusal, content-filter, other
start-error	busy, duplicate, invalid-input, unavailable, other. Nothing is written.
run-error	cancelled, no-model, model-refused, model-failed, not-recorded, superseded, output-rejected, failed, other

max-steps, max-total-tokens and max-duration are advisory: the harness counts and enforces them so it can end with a reply.

compact (unstable)

Exported by a harness that can summarize its context when its driver asks, between runs. A driver that finds no compact export leaves compaction to the harness.

Function	Signature
compact	async func(focus: option<string>, options: run-options) -> result<started-run, start-error>

focus is the person's text saying what the summary should keep. It shares the lock and cancellation rules of run.

Related

• Anatomy of an agent explains the parts these interfaces connect.
• Sessions explains the journal, conditional commits and compaction.
• Agent workload reference lists the host entries that serve these interfaces.