Harnesses, events and channels

The harness's name, as agents refer to it.

The command that starts one session, resolved like a tool's mcp command. It speaks the harness protocol in JSON lines over stdin and stdout.

The harness asks before each tool call, so the job's hooks and approvals decide it. See Write a harness for another tool.

The tools a session gets when its agent lists no harness.tools. For an ACP harness, ACP tool kinds; its default is every kind but switch_mode.

The model APIs a JSON-lines harness's sessions speak, preferred first: anthropic-messages, openai-chat, openai-responses, google-generate-content. Its agents may then ask for an alias (model.use): the edge resolves it only to a provider record that takes one of them, whatever the provider is called, and the session request carries the record's format in formats. An ACP harness lists them under acp.formats instead; a remote harness has none. harness-claude declares [anthropic-messages].

The JSON-lines harness honours the session request's effort: the reasoning effort the job's resolution decided for the session's model, one of low, medium, high, xhigh and max, or empty for the model's own. Without it, plugin lint warns that an agent's model.effort does nothing on the harness. An ACP harness needs no flag: the runtime sets an agent's thought-level option when it offers one. harness-claude sets it and passes the level to the Agent SDK's effort option.

acp for an agent that speaks the Agent Client Protocol, with the node runtime as its client, or remote for a remote agent's provider adapter, which agents use with runtime: remote:<name>. Empty means the JSON lines of the harness protocol.

An existing program the harness runs, pinned to one version: npm:<name>@<x.y.z> or pypi:<name>==<version>. command then names its bin and arguments.

A program's archive for each platform, such as linux/amd64: {url: https://..., sha256: ...}: .tar.gz, .tgz, .tar.bz2 or .zip, checked against its SHA-256 when the node installs the plugin. command[0] is the program's path inside the archive.

Settings for an ACP harness's sessions:

• formats: the model APIs the agent speaks. Required.
• env: variables with ${model}, ${base_url}, ${api_key} and the other placeholders filled in.
• auth: the authentication method to select.
• mode: the session mode to set.
• needs: client capabilities the agent cannot work without, fs and terminal. These are offered only in sandbox tier 1.
• asks: tool kinds the agent asks about before running them with these settings, or *. A routine's fire or shadow run needs every kind its session may use listed here.
• cannot_ask: why the agent cannot promise to ask about more. A refused fire or shadow run quotes this reason.
• skills: the folder its tool loads skills from, under the session's ${home} or ${state}, such as ${home}/.agents/skills. The runtime links a read-only copy of the agent's skills there. Without it, the session gets oz.skill through its MCP server.

env cannot set OZ0_* or loader variables (LD_*, DYLD_*).

The source's name in the tenant, in its URL: lowercase letters, digits and dashes, starting with a letter, at most 31.

What the source delivers, for people reading oz0 event sources.

The function that normalises a delivery, <tool>.<function>, of one of this plugin's tools.

The tenant secret deliveries are signed with or carry. The edge reads it; with scheme plugin, list it in requires.secrets too.

scheme (hmac-sha256, ed25519, jwt, token or plugin), header, prefix and, for hmac-sha256 and ed25519, encoding (hex or base64), message (what is signed, of {body} and {timestamp}), timestamp (the header with the signing time) and max_age_s (300). For jwt: openid_url or jwks_url (HTTPS), key_hosts, issuers, algorithms (RS256 unless set), max_age_s (the clock skew on exp and nbf, at most 600), claims and key_fields (what the function gets in delivery.verified); the source's secret holds the audience. See Bearer tokens.

The header with the sender's ID for one delivery, such as X-GitHub-Delivery, kept with its record. Without it: Idempotency-Key, X-Request-Id. It never names the delivery: the body's SHA-256, which the signature covers, does.

The event types the function gives.

The largest delivery taken, at most and by default 1024.

What the edge answers at once: when (CEL over body and headers), reply (CEL), status, route. See Answer at once.

What the edge checks of the function's events against the delivery: for type, action, subject, text, attributes.<name> or a chat message's message.kind, workspace, room, thread, id, author.id, action, agent, private and direct, a CEL expression over body, headers, verified and sealed that gives the field's value, or a list of the values of the delivery's events in the same order (one each; an empty list: no event); at most 32, each at most 4096 bytes.Each event must be a row of its own, so one delivery gives no more events than its rows; a chat channel's delivery is one message, read as one row.Routines, flows and waits match only bound fields, and a channel's source binds the message's fields, its thread and its text. With scheme plugin nothing is verified. See Bind events to the delivery.

What the edge vouches for across a round trip through the other system, such as a form a click opened: when (CEL: which deliveries' facts it seals), facts (by name, CEL giving a string each; at most 16) and from (CEL: the seal a later delivery carries back). The function gets the seal as delivery.seal, and the bindings read a carried seal's facts as sealed; a seal opens for one hour, for its source. Not with scheme plugin. See Carry a click through a form.

The channel's name in the tenant, which bindings name. The source's name unless set.

Which chat system the channel speaks to.

The event source of this plugin that takes the chat system's deliveries.

The function that posts or updates a message, <tool>.<function> of one of this plugin's tools. Its errors with (retryable in them are posted again later.

The chat system names where replies go in each delivery: claim (a claim of the source's jwt signature, which a message's endpoint must equal) and hosts (the hosts it may be on, *.<domain> for any name under it that the domain's owner holds; a wildcard over a public suffix is refused). The edge keeps a message's endpoint only when both hold, and hands it to post.