Status: Stable.
Normative home:
promptLibrary,prompts,aiProviders,agentRuntime,mcp,workspace,secrets,modelCapabilities,scheduling,queueBus,toolHooks,httpClient,memory.
Why this exists
Node packs call advertised host.* services through ctx. Each section states the contract a host accepts by advertising that family.
promptLibrary
A host advertising promptLibrary MUST expose ctx.promptLibrary.get and MUST return a pinned version verbatim, so a replayed run resolves the same template. It MUST fail the calling node rather than substitute an unpinned version.
prompts
A host advertising prompts resolves the PromptRefs in node config (systemPromptRef, userPromptRef, fewShotPromptRefs, schemaHintPromptRef); to any other host they are opaque strings.
templateKindsandvariableSourcesnarrow what the host accepts; thesecretsource SHOULD appear only withsecrets.maxTemplateBytesMUST NOT exceed 65536.observabilityisoff,hashed(default) orfull.endpointsSupportedgates the/prompts*operations,mutableLibrarytheir writes andpacksSupportedpack installs. An operation whose gate is off answers404 not_found.librarycarriesid,renderEndpointandmaxRenderRequestBytes.
Resolution
For each (nodeId, kind), the host MUST take the first non-null ref from these layers, and MUST emit agent.prompt-resolved, with one chain[] entry per layer tried, before prompt.composed:
- node
config, where a ref beats an inline body; - under
agentBindings, the agentconfig.agentIdnames: forsystem, first its own prompt (taggedagent-intrinsic), then itspromptOverrides, and last the host MAY use apromptLibraryRefdefault. An unknown agent MUST be logged as a warning and skipped; - the workflow's
defaults.promptRefs[kind]; prompts.defaults[kind].
When every layer is null, the node fails only if its node type says so. A host honoring ai.promptOverrides applies it before any layer and MUST record a run-configurable entry.
Composition
{{varName}}substitution is literal. An unbound required variable MUST fail the node (node_config_invalid); an unbound optional or undeclared one renders empty, and install SHOULD warn on an undeclared one.secretvalues MUST appear only as[REDACTED:<secretId>]in observability output.- Untrusted input MUST be wrapped verbatim in
<UNTRUSTED>…</UNTRUSTED>, which makescontentTrustuntrusted. - Unless
observabilityisoff, the host MUST emitprompt.composedfor each composition, carrying bodies only underfull. - On replay,
hash,variableHashes,refs, the resolved ref andchain[].appliedMUST match the recording, and a mismatch MUST emitreplay.diverged. Bodies MAY be omitted.chain[].sourceSHOULD match, and a rotatedhost-defaultssource MUST be tolerated.
Library
- A ref without a version resolves to the latest. A string ref matching several templates MUST be refused with
validation_error,details.field: libraryId. renderPromptTemplatedispatches nothing, and itshashMUST equal the dispatch-timeprompt.composedhash.getPromptTemplateSHOULD sendETagandmax-age=60, plusimmutablewhenversionis pinned.- Writes MUST be authenticated and SHOULD be role-scoped. An update MUST carry a greater SemVer; built-in and pack templates are read-only.
- For a workspace-scoped read or write, the host MUST verify membership from the authenticated identity, never from a caller's
workspaceId. The check fails closed (canonically403 workspace_membership_required) and runs in the application tier, even behind a privileged database client. - A
kind: "prompt"pack MUST NOT carrynodes[]orchains[]; its templates MUST carrymeta.packNameandmeta.packVersion.
aiProviders
A host advertising aiProviders MUST expose ctx.callAI. A provider that a ctx call names MUST be in providers; byok: runs.md §ai.
- A part whose modality is absent from
inputMUST be rejected withcapability_not_provided, never dropped. Non-text input is untrusted. - Generated media is inlined as base64 only up to
maxInlineMediaBytes(default 256 KiB); above that the host MUST use aurl. imageGeneration,videoGenerationandspeechSynthesisaddctx.callImageGenerator,callVideoGeneratorandcallSpeechSynthesizer;realtimeVoiceaddscallTranscriberand streamed synthesis. Unadvertised synthesis or transcription MUST be rejected, never a no-op or whole-file fallback.- A video caller MUST honor
ctx.signal. Synthesis MUST return exactly one ofurlorbase64, and aurlis served through the SSRF guard. The transcriber MUST reject inline ormediaRefaudio. voiceId,streamRefandcachePrefixIdMUST NOT encode secrets. Transcripts are untrusted; an interim one MUST NOT be persisted or drive a side-effecting tool.callAccountingreportsctx.callAIattempts and honorsretry.
selfHosted (operator-configured OpenAI-compatible endpoints) MUST be advertised only while one is configured and reachable. A host MUST NOT disclose an endpoint's location on any wire surface or in a provider id. A client MUST NOT infer capabilities from the id; an unadvertised one fails capability_not_provided.
authModes (apiKey, oauth-pkce, oauth-device, none, subscription) is capability, not policy: a client MUST ignore an unknown mode and MUST NOT infer policy from one.
- OAuth and
subscriptioncredentials go byref, never key material; an OAuth mode SHOULD come withoauth. - A
subscriptioncredential MUST bind at user scope; a tenant or workspace binding MUST be rejected withcredential_scope_forbidden. - A host MUST NOT advertise
subscriptionwithout a reachable acquisition mechanism.
policies.modes lists the enforced modes; a client MUST tolerate any subset, and absence means optional only. The host MUST document its scopes precedence.
disabledalways refuses (provider_disabled).requiredrefuses without acredentialRef(byok_required) or a usable secret (byok_required_but_unresolved).restrictedrefuses a model matching noallowedModelsglob (model_not_allowed). An emptyrestrictedpolicy MUST fail closed.
A refusal's error MUST be policies.errorCode (default provider_policy_denied, else a vendor code); its details.reason SHOULD name the cause above, and it MUST NOT echo the policy. Each decision SHOULD be audited. A resolver outage SHOULD fail open.
Structured output
These facets govern a ctx.callAI call that supplies responseSchema.
tierOneSubsetCompliance advertises that the host accepts the Tier 1 structured-output subset shared across major providers. A host advertising it MUST accept a schema restricted to that subset for any provider it advertises, rather than refusing on provider-specific grounds.
reasoning advertises the host's prompt posture for an optional reasoning property in the response schema.
- Where the schema permits it, a host SHOULD instruct the model to populate it. A host MUST NOT reject output without it, whatever
promptDirectivesays. - A host MUST NOT route on
reasoning. A known secret in the input MUST NOT appear verbatim in it, in derived events, span attributes or the debug bundle (invariantenvelope-reasoning-secret-redaction).
A host advertising reliability:
- MUST emit
envelope.retry-exhaustedandenvelope.refusal, and list inreliability.events[]both of them and only the other reliability events it emits; - SHOULD emit
envelope.retry-attemptedbefore each retry past the first; - MUST pass
previousError,finalErrorandrefusalTextthrough its secret redaction (invariantsenvelope-refusal-no-prompt-leak,envelope-recovery-no-content-leak); - MUST replay
totalAttempts,outputTokenCountand the recoverypathidentically.refusalTextMAY differ, and a consumer MUST toleratenull.
Under reliability.completion.distinguishesTruncation, output is complete only on a clean provider stop with a payload that validates against responseSchema.
- Truncation (no clean stop): the host MUST emit
envelope.truncated. A retry SHOULD raise the output budget, bytruncationBudgetMultiplier(default 2), and MUST NOT carry a schema-correcting fragment. - Schema violation (clean stop, invalid payload): a retry's corrective fragment SHOULD reproduce the validator's failure and MUST NOT contain text from the model's output. The retry MUST NOT raise the output budget.
- Refusal is terminal: the host MUST NOT retry it, and the node MUST fail with
envelope_refusal.configurable.ai.maxRefusals(runs.md) caps theenvelope.refusalevents a run records. - Each retry past the first MUST emit
envelope.retry-attemptedwith thatreason. Both paths count againstlimits.maxRepairRoundswhen it is advertised. - On exhaustion the host MUST emit
envelope.retry-exhaustedwith thatfinalReasonandcap.breachedkind: "schema", and fail the node withenvelope_truncation_unrecoverableorenvelope_invalid. - Lenient-parse recovery consumes no retry. It emits
envelope.recovery-appliedonce per recovery, carrying only the path and an optional byte offset.
A host advertising promptPrefixCache MAY honor cachePrefixId per routed provider, and otherwise MUST ignore it. It MUST key the cache by (authenticated tenant, cachePrefixId) and MUST NOT persist prompt or response substrings keyed by it. The envelope and provider.usage token counts MUST match on hit and miss, and on replay.
agentRuntime
A host advertising agentRuntime MUST expose spawn, delegate, consensus and messageSend. Advertising it implies agents.manifestRuntime, which the host MUST satisfy.
mcp
A host advertising mcp.client MUST expose to pack code ctx.mcp.callTool, listTools, readResource and serverHealth, each against a host-configured serverId at the revision mcp negotiates.
Each rejects only for an unknown serverId (not_found), an MCP error response (carried unaltered), or a transport failure (upstream_unavailable).
callToolMUST resolve to the server'sCallToolResultunaltered (content[],structuredContent,isError,_meta), including whenisErroris true. The host handles anInputRequiredResultitself and never returns one.listToolsMUST resolve to oneListToolsResultpage unaltered,outputSchema,annotations,nextCursor,ttlMsandcacheScopeincluded, and MUST forward a pack'scursor.readResourceresolves to theReadResourceResultunaltered.serverHealthMUST reportreachable,unreachableorincompatiblefrom aserver/discoverprobe no older than itsttlMs, with theDiscoverResultwhen one was received. It MUST NOT report a connection or session state.
secrets
A host advertising secrets MUST resolve secrets to opaque references. Raw key material MUST NOT appear in any event, log, trace, prompt, error, export or screenshot, and the host MUST test this before exposing BYOK.
scopes lists the storage scopes the host implements, and a client MUST tolerate any subset. resolution is host-managed.
A host offering resolveInPack MUST expose ctx.secrets.resolve({ ref, purpose }), returning plaintext and optional expiresAt and rotatedAt. It:
- MUST keep the plaintext out of events, spans, logs, snapshots and replay state. A replay re-resolves it, and the host SHOULD record only
ref,purposeand time; - MUST resolve
refonly to a credential the calling run may read, fail areffrom another workspace, and never substitute another credential; - MUST reject a missing, revoked or expired secret with
credential_not_found, a denied one withcredential_forbidden, and an exhausted quota withrate_limited.
A pack MUST pass a non-empty purpose, which the host audits. The pack MUST NOT log the plaintext, keep it past the consuming call, or pass it to any other ctx method, and MUST treat it as run input that may differ between runs.
Run-supplied secrets
A host advertising runSecrets: { maxEntries } accepts runSecrets on createRun (runs.md §Create): an array of { ref, value }. It MUST also list run in scopes. A client MUST NOT send runSecrets to a host that does not advertise it.
- Bounds.
refMUST match^run:[A-Za-z0-9_.-]{1,64}$, andvalueis a string of 16 to 4096 characters. The array holds at mostmaxEntriesentries, eachrefonce. A request that breaks any of these MUST be refused400 validation_error, naming the field and never the value. - Bound to the run. A
run:ref MUST resolve only to a value in therunSecretsof the run resolving it, never from another run, a user, tenant, workspace, the platform or the process environment. An unsuppliedrun:ref MUST failcredential_not_found. A ref without therun:prefix MUST NOT resolve to arunSecretsvalue. - Lifetime. The host MUST NOT write a value to any store an operator or client can read in cleartext, and MUST discard it by the time the run is terminal. A fork does not inherit it, so a
run:ref in the fork failscredential_not_found. - Redaction. A value is a resolved run-scoped secret, and every redaction rule of this section and of §
memorybinds it. The host MUST NOT echo it on any response, thecreateRunanswer and the snapshot included; a read MAY return the refs. It MUST NOT log the request's values. - No digest. A value MUST NOT enter any hash, digest, fingerprint or cache key the host persists or derives from the request, including any replay, witness or audit digest. The idempotency request digest (idempotency.md) is computed with
runSecretsremoved. A same-key retry that differs only there compares equal, is answered as any duplicate is, and its values are discarded unused.
A host advertising runSecrets MUST execute the node type core.secret.witness and MUST advertise the fixture openwop-secrets-run-witness. The node's configuration is { ref, expectedSha256 }.
- A
refwithout therun:prefix MUST failcredential_forbiddenwithout resolving anything. - Otherwise the node resolves
refunder the rules above and outputs{ matched }: whether the lowercase-hex SHA-256 of the value's UTF-8 bytes equalsexpectedSha256. - It MUST NOT output, log or emit the value, its digest, its length, or any other function of it beyond
matched.
modelCapabilities
modelCapabilities.advertised lists the capability identifiers the active model offers; a host-private identifier MUST be prefixed x-host-<host>-.
When a host advertising modelCapabilities dispatches a node that declares requiredModelCapabilities, it MUST check them before dispatch:
- all met: dispatch;
- unmet, with a
fallbackModeldeclared,substitutionSupportedadvertised, and the fallback's provider inaiProviders.providerswith a resolvable credential: emitmodel.capability-substituted, then dispatch the fallback; - otherwise: emit
model.capability-insufficientand fail the run withcapability_not_provided.
The host MUST NOT substitute silently or dispatch an unsuitable model. It MUST check a fallback's full capability set, and refuse a fallback that falls short with fallbackAttempted: true rather than chain another. Checking capabilities before resolving prompts is RECOMMENDED.
scheduling
A host advertising scheduling starts runs from the schedule trigger in the forms it advertises (cron, delayed, calendar). It MAY do so without queueBus. For each schedule it MUST:
- persist it so it survives a restart and fires on time;
- fire once per tick, never as duplicate concurrent runs;
- reject a fire time beyond
maxFutureHorizonwithschedule_horizon_exceeded, whosedetails.maxFutureHorizonSHOULD echo the cap; - after missing a tick while down, either fire once on recovery or skip to the next tick, as it documents, never the whole backlog.
queueBus
A host advertising queueBus MUST expose ctx.queueBus.publish, consume, ack and nack; deadLetter when it advertises deadLetterSupported; and streamSubscribe when it advertises stream, honoring fromBeginning only under stream.fromBeginning. It MAY use any of its advertised backends.
- A tenant's consumer MUST NOT receive another tenant's messages, even on the same topic.
ackMUST remove a message,nackMUST return it for redelivery, anddeadLetterMUST route it to the configured dead-letter queue, which holds messages, not runs (runs.md §Dead letters).- A workflow triggered by a queue consume MUST get one run per inbound message, with no batching or skipping.
- The wire shape MUST NOT vary by backend. An unknown topic or expired delivery token rejects
not_found; an unreachable backend,upstream_unavailable.
toolHooks
A host advertising toolHooks extends agent.toolCalled and agent.toolReturned for every external tool call:
prePostEvents. The host MUST setargsHash,principalandtransporton the call, andstatusanddurationMson the return.argsHashis SHA-256 over the RFC 8785 canonical arguments with secrets already redacted. A non-agent egress uses the principalcore.system.durationMsis re-emitted verbatim on replay or fork, never recomputed.perToolAuthorization. Before invoking, the host MUST check the principal's scopes against the tool'srequiredScopes. If one is missing or cannot be evaluated, it MUST NOT invoke, MUST emitagent.toolReturnedwithstatus: forbidden, and MUST answer403 forbiddenwithdetails.scope: "tool",toolNameandrequiredScopes.perToolRateLimit. The host MUST keep a token bucket per(principal, toolName). When the bucket is empty, the host MUST NOT invoke; it emitsstatus: rate_limitedand answers429 rate_limitedwithdetails.scope: "tool".
A host MAY refuse an allowlisted tool at loop start. Such a return has no call: the host MUST synthesize its callId (a stable derivation is RECOMMENDED), MAY omit causationId, and MUST NOT invent an agent.toolCalled. A consumer MUST tolerate an unpaired forbidden or rate_limited return.
httpClient
A host advertising httpClient MUST advertise ssrfGuard: true and a positive maxResponseBodyBytes. Before connecting it MUST resolve the target, reject loopback, RFC 1918, link-local and cloud-metadata addresses, and pin the resolved address for the connection (invariant http-client-ssrf-guard). A refused target is egress_denied, reason: ssrf-blocked; an unreachable one, upstream_unavailable. methods lists the HTTP methods it accepts.
A host MAY expose ctx.http.safeFetch(url, init?) to pack code under safeFetch. It then:
- MUST apply that guard, enforce
maxResponseBodyBytesand anyrequestTimeoutMs, and refuse a connection upgrade; - MUST emit the
agent.toolCalledandagent.toolReturnedpair (transport: http) for every call when it also advertisestoolHooks.prePostEvents; - SHOULD NOT forward an
Authorizationheader the pack did not build from a host-issued credential.
A host advertising egressPolicy, which requires safeFetch, attaches a CredentialProvenance (never the secret) when it binds a host-issued credential to an egress, and:
- MUST emit a content-free
egress.decided, whosedestinationis the authority alone and whosereasonis from its closed set; - MUST NOT attach the credential to a destination outside its
audiences(exact host or*.domain): the egress isdeniedor, where policy permits,downgraded; - MUST deny when provenance cannot be evaluated, and MUST NOT attach an expired credential.
An egress is allowed only when the address guard and the audience check both pass.
workspace
A host advertising workspace keeps agent files (schemas/v2/workspace-file.schema.json) scoped to one {tenant, workspace}; no protocol path serves them. The host:
- MUST make each write atomic, bumping
version, and emitworkspace.updatedon each write or delete; a versioned delete leaves a tombstone; - MUST refuse a stale
If-Matchetag with409 workspace_conflict(details.currentVersion), and content overmaxFileByteswithworkspace_too_large; - with
versioned, MUST serve the latest and any retained version, retaining best-effort up tomaxVersions;maxFilescaps the file count; - MUST give a run, through
ctx.workspace, an immutable snapshot taken atrun.started, so a replay on any host sees the same files; its writes reach later runs only; - MUST derive the scope from the authenticated identity and MUST NOT return or disclose another scope's file;
404MAY stand for403(invariantworkspace-cross-tenant-isolation); - MUST persist
[REDACTED:<secretId>]for any value the run's vault resolved at user, tenant or run scope (longest first, 8-character minimum).
A workflow calling ctx.workspace MUST NOT register on a host without the family. The memory-index manifest is the workspace file MEMORY-INDEX.json.
memory
A host advertising memory serves agent memory (schemas/v2/memory-entry.schema.json) to pack code as ctx.memory; no protocol path serves it. list returns [] for an unknown ref and get returns null; writes are host-internal, and a read-only host sets writable: false.
- Refs.
memoryRefis opaque; a host MUST NOT assume another host's ref resolves. A node MUST guardctx.memory, which may be undefined. - Tenant isolation. A ref MUST resolve to one tenant's entries, whatever the caller's permissions. A malformed ref (traversal, embedded null, oversize) MUST return
[]ornull. An adapter sharing a store MUST gate on the ref's shape, not trust the store. An adapter error MUST NOT carry entry data. - Redaction. A persisted entry MUST carry
[REDACTED:<secretId>]in place of any value the run's vault resolved at user, tenant or run scope; platform scope is excluded. - Size and expiry. A host SHOULD reject a
putovermaxEntrySizeByteswithvalidation_error. UnderttlSupportedorretention.ttl, an entry pastexpiresAtMUST NOT surface, purged or not. - Long-term. A host whose
agents.memoryBackendsincludeslong-termMUST honor isolation, redaction and expiry end to end. A validator MUST NOT look formemoryBackendsundermemory. searchadvertises querymodesbeyondlist.retention.forgetis a tenant-scoped delete-by-subject of live memory only; replay reads the recorded snapshot and the log is untouched.attribution. UnderemitsWriteEvents: truethe host MUST emit a content-freememory.writtenfor every memory write a run makes; otherwise a consumer MUST tolerate its absence.injectionBudgetmakeslisthonortokenBudget, intokenCounterunits; without it the budget is ignored. The host MUST return a prefix of the ranked list within budget, omitting (never truncating) an entry that alone exceeds it. Withlimitas well, it MUST honor whichever yields fewer entries.- Ranking.
rank: relevanceMUST carryqueryand requiressearchmodesemantic; otherwise a host MUST reject it or fall back, as documented, torecency(the default), and never fabricate a ranking. Ranking MUST run over the redacted, single-tenant set. compaction(trigger: host-managed) emitsmemory.compacted. Derived content MUST pass the same redaction as a freshput. A client MUST NOT infer compaction or distillation from entry counts.distillationis budgeted compaction (runs.md §distillationsection); an absent budget MUST default tomaxTokenBudget, counting input and output. It emitsmemory.compactedwithdistillationandtrigger: host-managed, and tenant isolation covers its archive and index.- Distillation runs. A distillation run MUST read the ref's snapshot, MUST NOT re-expose a redacted secret at any recursion level, and MUST write an immutable, addressable archive, byte-stable per source set and budget, kept for
archiveRetention. UnderindexEmittedit updatesMEMORY-INDEX.json, and a.mdsibling MAY accompany it. - Degraded agents. When an agent's
memoryShapeneeds a dimension the host lacks, its inventory entry MUST setmemoryDegradedanddegradedMemoryDimensions; the agent MAY still dispatch. Arole: skillmanifest MUST keepmemoryShapescratchpad-only, enforced by schema.
Sources: RFCs 0004, 0012, 0017, 0027, 0028, 0029, 0031, 0048, 0052, 0055, 0057, 0059, 0062, 0064, 0067, 0076, 0079, 0080, 0091, 0105, 0106, 0108, 0113, 0116, 0121, 0131, 0144, 0228, 0229, 0248.