@byok-sdk/protocol 0.26.1 → 0.27.0-rc.2

package/dist/input-preparation.d.ts

@@ -1,28 +1,4 @@
 import { z } from 'zod';
-export { INPUT_PREPARATION_WIRE_VERSION } from './input-preparation-version';
-/**
- * Capability required before a task-free remote input preparation — or a
- * prepared Execution — is admitted: `agent-input-preparation-v<N>`, where
- * `<N>` is {@link INPUT_PREPARATION_WIRE_VERSION}.
- *
- * The version is IN the token because the relay wire has none. A device
- * declares exactly the one token of the contract it speaks, and a cloud admits
- * exactly the one token of the contract it speaks, so a device and a cloud on
- * different contract versions never exchange a preparation at all: the cloud
- * refuses at enqueue (`agent_capability_missing`, before any receipt or
- * mailbox row) instead of relaying a payload the other side would refuse with
- * a strict-schema 422 and a device would then redeliver forever. There is no
- * dual token and no accepted older one. The retired unversioned token
- * `agent-input-preparation` (versions up to 4) is admitted nowhere.
- *
- * The token gates NEW admissions only. A row enqueued before a version cut is
- * still in flight afterwards, and its completion is accepted only by a cloud
- * on the same version as the device answering it; across the cut it is a 422
- * and a stalled device cursor. Draining in-flight rows and upgrading cloud and
- * devices as a pair is the operator precondition for the cut (`docs/spec.md`,
- * bounded admission); nothing here parses an older receipt.
- */
-export declare const AGENT_INPUT_PREPARATION_CAPABILITY: "agent-input-preparation-v9";
 /** The preparation surface uses the package-wide lowercase `sha256:<hex>` transport form. */
 export declare const InputPreparationContentHashSchema: z.ZodString;
 /**
@@ -577,6 +553,13 @@ export declare const InputPreparationArtifactSummarySchema: z.ZodObject<{
 }, z.core.$strict>;
 /** The immutable binding a receipt carries and a later consumer must re-present. */
 export declare const InputPreparationBindingSchema: z.ZodObject<{
+    terminalProjection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"none">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"result-document">;
+        contract: z.ZodString;
+        schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
+    }, z.core.$strict>], "mode">>;
     agentMemory: z.ZodEnum<{
         none: "none";
         read: "read";
@@ -636,6 +619,13 @@ export declare const InputPreparationReceiptSummarySchema: z.ZodObject<{
         reserved: "reserved";
     }>;
     binding: z.ZodObject<{
+        terminalProjection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"none">;
+        }, z.core.$strict>, z.ZodObject<{
+            mode: z.ZodLiteral<"result-document">;
+            contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
+        }, z.core.$strict>], "mode">>;
         agentMemory: z.ZodEnum<{
             none: "none";
             read: "read";

package/dist/messages.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type PlainJsonCheck } from './plain-json';
 export declare const RuntimeIdSchema: z.ZodEnum<{
     claude: "claude";
     codex: "codex";
@@ -372,6 +373,7 @@ export declare const TaskOfferForAgentPayloadSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         mode: z.ZodLiteral<"result-document">;
         contract: z.ZodString;
+        schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
     }, z.core.$strict>], "mode">>;
     sessionRef: z.ZodOptional<z.ZodString>;
     limits: z.ZodOptional<z.ZodObject<{
@@ -438,6 +440,7 @@ export declare const TaskOfferForAgentWithEgressPayloadSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         mode: z.ZodLiteral<"result-document">;
         contract: z.ZodString;
+        schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
     }, z.core.$strict>], "mode">>;
     limits: z.ZodOptional<z.ZodObject<{
         maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -541,6 +544,7 @@ export declare const TaskOfferForAgentWithEgressFreshPayloadSchema: z.ZodObject<
     }, z.core.$strict>, z.ZodObject<{
         mode: z.ZodLiteral<"result-document">;
         contract: z.ZodString;
+        schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
     }, z.core.$strict>], "mode">>;
     limits: z.ZodOptional<z.ZodObject<{
         maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -648,6 +652,7 @@ export declare const TaskOfferPreparedPayloadSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         mode: z.ZodLiteral<"result-document">;
         contract: z.ZodString;
+        schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
     }, z.core.$strict>], "mode">>;
     limits: z.ZodOptional<z.ZodObject<{
         maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -1222,7 +1227,7 @@ export type TaskStartedPayload = z.infer<typeof TaskStartedPayloadSchema>;
  * writeup): declining does *not* introduce a new `Declined` terminal state.
  * It maps onto the existing `Failed` state via a new `Offered -> Failed`
  * transition. `reason`/`retryable` intentionally mirror `TaskFailPayload`
- * exactly, because a pre-claim decline and a post-claim failure are the same
+ * semantics, because a pre-claim decline and a post-claim failure are the same
  * outcome from the dispatcher's point of view (this attempt produced no
  * result; here's whether retrying — e.g. offering to a different device —
  * makes sense), and keeping the state machine minimal avoids forking every
@@ -1235,6 +1240,10 @@ export declare const TaskDeclinePayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>>;
+    code: z.ZodOptional<z.ZodEnum<{
+        agent_home_reader_busy: "agent_home_reader_busy";
+        agent_home_writer_busy: "agent_home_writer_busy";
+    }>>;
 }, z.core.$strip>;
 export type TaskDeclinePayload = z.infer<typeof TaskDeclinePayloadSchema>;
 /**
@@ -1392,21 +1401,7 @@ export declare const RESULT_DOCUMENT_MAX_BYTES = 1048576;
  * in a failure reason. `canonical` is the CANONICAL SNAPSHOT — the value a
  * sender must actually put on the wire; see {@link checkResultDocument}.
  */
-export type ResultDocumentCheck = {
-    readonly ok: true;
-    readonly bytes: number;
-    readonly canonical: unknown;
-} | {
-    readonly ok: false;
-    readonly reason: 'not-serializable';
-} | {
-    readonly ok: false;
-    readonly reason: 'over-cap';
-    readonly bytes: number;
-} | {
-    readonly ok: false;
-    readonly reason: 'not-plain-json';
-};
+export type ResultDocumentCheck = PlainJsonCheck;
 /**
  * THE single authority for "is this a legal `task.complete.document`", and
  * the one place its canonical form is produced. `TaskCompletePayloadSchema`'s
@@ -1444,7 +1439,7 @@ export type ResultDocumentCheck = {
  *      no `toJSON`, no getters, no prototype, nothing left that can answer
  *      differently a second time.
  *   4. The original must be structurally equal to the snapshot
- *      ({@link isSameJsonData}). Any mismatch means the value was not plain
+ *      (`isSameJsonData`, `plain-json.ts`). Any mismatch means the value was not plain
  *      JSON data, and it is rejected rather than silently transformed.
  *
  * On success the snapshot is returned as `canonical`, and **every sender
@@ -1566,7 +1561,7 @@ export type TerminalAgentHomeMemoryChange = z.infer<typeof TerminalAgentHomeMemo
 /**
  * daemon -> server: task finished successfully.
  *
- * `document` (additive-minor, docs/protocol.md "Freeze rule"): the OPTIONAL
+ * `document` (docs/protocol.md §7.2): the OPTIONAL
  * structured terminal result of the task — one JSON value the product on the
  * other side consumes as the task's actual output, as opposed to `summary`
  * (human-readable prose) or `artifactRefs` (files). Deliberately
@@ -1580,14 +1575,12 @@ export type TerminalAgentHomeMemoryChange = z.infer<typeof TerminalAgentHomeMemo
  * never truncated (see that constant's own doc comment). A sender puts the
  * check's `canonical` snapshot on the wire, never the original object.
  *
- * Unlike `approvalId` on `task.await_approval` above, emitting this field IS
- * gated on a capability flag (`result-document`, `version.ts`): a pre-
- * `result-document` server strips it silently as an unknown key (the
- * tolerant `z.object()` behavior §1 mandates), and silently losing the
- * task's primary structured result is not a tolerable degradation the way
- * losing an observability hint is. So a daemon sends `document` only to a
- * server that advertised the flag, and fails the task loudly otherwise —
- * see `packages/client`'s `task-runner.ts`.
+ * Wire v3: every v3 server keeps this field, so no capability flag gates it
+ * (the v2 `result-document` flag is gone). For a
+ * `terminalProjection.mode: 'result-document'` offer it carries the outcome
+ * the daemon validated against the offer's frozen schema
+ * (`validateResultOutcome`, `result-schema.ts`, at most
+ * `RESULT_OUTCOME_MAX_BYTES`).
  */
 export declare const TaskCompletePayloadSchema: z.ZodObject<{
     harnessId: z.ZodOptional<z.ZodString>;
@@ -1950,6 +1943,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         sessionRef: z.ZodOptional<z.ZodString>;
         limits: z.ZodOptional<z.ZodObject<{
@@ -2010,6 +2004,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         limits: z.ZodOptional<z.ZodObject<{
             maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -2106,6 +2101,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         limits: z.ZodOptional<z.ZodObject<{
             maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -2192,6 +2188,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         limits: z.ZodOptional<z.ZodObject<{
             maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -2402,6 +2399,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         sessionRef: z.ZodOptional<z.ZodString>;
         limits: z.ZodOptional<z.ZodObject<{
@@ -2462,6 +2460,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         limits: z.ZodOptional<z.ZodObject<{
             maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -2558,6 +2557,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         limits: z.ZodOptional<z.ZodObject<{
             maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -2644,6 +2644,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
         }, z.core.$strict>, z.ZodObject<{
             mode: z.ZodLiteral<"result-document">;
             contract: z.ZodString;
+            schema: z.ZodCustom<import("./result-schema").ResultSchema, import("./result-schema").ResultSchema>;
         }, z.core.$strict>], "mode">>;
         limits: z.ZodOptional<z.ZodObject<{
             maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -3113,6 +3114,10 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>>;
+        code: z.ZodOptional<z.ZodEnum<{
+            agent_home_reader_busy: "agent_home_reader_busy";
+            agent_home_writer_busy: "agent_home_writer_busy";
+        }>>;
     }, z.core.$strip>;
     readonly 'task.progress': z.ZodObject<{
         seq: z.ZodNumber;

package/dist/plain-json.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Plain-JSON-data canonicalization shared by every bounded JSON channel of
+ * the wire: `task.complete.document` (`checkResultDocument`, messages.ts) and
+ * the result-document schema and outcome (`result-schema.ts`). One rule, one
+ * implementation, so the channels cannot disagree about what "plain JSON
+ * data" means or how its canonical UTF-8 size is measured.
+ *
+ * Zod-free and free of node builtins.
+ */
+/** Outcome of {@link canonicalizePlainJson} without a depth bound. */
+export type PlainJsonCheck = {
+    readonly ok: true;
+    readonly bytes: number;
+    readonly canonical: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: 'not-serializable';
+} | {
+    readonly ok: false;
+    readonly reason: 'over-cap';
+    readonly bytes: number;
+} | {
+    readonly ok: false;
+    readonly reason: 'not-plain-json';
+};
+/** Outcome of {@link canonicalizePlainJson} with a container-nesting bound. */
+export type BoundedPlainJsonCheck = PlainJsonCheck | {
+    readonly ok: false;
+    readonly reason: 'too-deep';
+    readonly bytes: number;
+};
+/**
+ * Container nesting depth of pure JSON data (a `JSON.parse` output), computed
+ * iteratively so no input can exhaust the call stack. A scalar is depth 0,
+ * `{}` and `[]` are depth 1. Stops as soon as `limit` is exceeded.
+ */
+export declare function jsonDepthExceeds(value: unknown, limit: number): boolean;
+/**
+ * Canonicalize `value` as plain JSON data within `maxBytes` canonical UTF-8
+ * bytes:
+ *
+ *   1. `JSON.stringify` must succeed and not return `undefined`.
+ *   2. Its UTF-8 byte length must be at most `maxBytes`.
+ *   3. `JSON.parse` that string: the CANONICAL SNAPSHOT (pure data).
+ *   4. With `maxDepth`, the snapshot's container nesting must be at most
+ *      `maxDepth`. This runs before step 5, so the recursive comparison
+ *      below is bounded by it.
+ *   5. The original must be structurally equal to the snapshot
+ *      (`isSameJsonData`).
+ *
+ * On success a sender uses `canonical`, never the original reference.
+ */
+export declare function canonicalizePlainJson(value: unknown, maxBytes: number): PlainJsonCheck;
+export declare function canonicalizePlainJson(value: unknown, maxBytes: number, maxDepth: number): BoundedPlainJsonCheck;

package/dist/provider-profile-binding.d.ts

@@ -1,6 +1,4 @@
 import { z } from 'zod';
-/** Daemon capability required before an exact local provider profile may be offered. */
-export declare const PROVIDER_PROFILE_BINDING_CAPABILITY: 'provider-profile-binding';
 /** Opaque, portable local profile identity. It is one logical id, never a path. */
 export declare const ProviderProfileRefSchema: z.ZodString;
 export type ProviderProfileRef = z.infer<typeof ProviderProfileRefSchema>;

package/dist/provider-provisioning.d.ts

@@ -23,8 +23,6 @@ import { z } from 'zod';
  * Audiences, route paths and product names are Host vocabulary and stay out of
  * this package.
  */
-/** Device capability required before a Host may enqueue `provider.provisioning.available`. */
-export declare const PROVIDER_PROVISIONING_CAPABILITY: 'provider-provisioning.v1';
 /**
  * Device-proof `operation` for the signed claim that registers the device's
  * provider-secret sealing public key (`{ keyId, epoch, publicJwk }`).

package/dist/result-schema.d.ts

@@ -0,0 +1,95 @@
+/** Maximum canonical JSON UTF-8 size of a result-document schema. */
+export declare const RESULT_SCHEMA_MAX_BYTES = 16384;
+/** Maximum canonical JSON UTF-8 size of a submitted outcome document. */
+export declare const RESULT_OUTCOME_MAX_BYTES = 65536;
+/**
+ * Maximum subschema nesting below the root (each `properties` member, `items`
+ * and `oneOf` branch is one level). With the 16 KiB cap this bounds how much
+ * schema structure one validation walks.
+ */
+export declare const RESULT_SCHEMA_MAX_DEPTH = 32;
+/**
+ * Maximum JSON container nesting of a schema or outcome document, checked
+ * iteratively before any recursive routine runs on it.
+ */
+export declare const RESULT_JSON_MAX_DEPTH = 128;
+/** Maximum number of issues one failed check reports. */
+export declare const RESULT_ISSUES_MAX_COUNT = 20;
+/** Maximum UTF-8 size of the reported issue list, as JSON. */
+export declare const RESULT_ISSUES_MAX_BYTES = 4096;
+export declare const RESULT_SCHEMA_KEYWORDS: readonly ["type", "properties", "required", "additionalProperties", "items", "enum", "const", "oneOf", "minLength", "maxLength", "minItems", "maxItems", "minimum", "maximum", "description"];
+export type ResultSchemaKeyword = (typeof RESULT_SCHEMA_KEYWORDS)[number];
+export declare const RESULT_SCHEMA_INSTANCE_TYPES: readonly ["object", "array", "string", "number", "integer", "boolean", "null"];
+export type ResultSchemaInstanceType = (typeof RESULT_SCHEMA_INSTANCE_TYPES)[number];
+/** A schema inside the admitted subset. Only {@link checkResultSchema} proves a value is one. */
+export interface ResultSchema {
+    readonly type?: ResultSchemaInstanceType | readonly ResultSchemaInstanceType[];
+    readonly properties?: {
+        readonly [name: string]: ResultSchema;
+    };
+    readonly required?: readonly string[];
+    readonly additionalProperties?: false;
+    readonly items?: ResultSchema;
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly oneOf?: readonly ResultSchema[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly description?: string;
+}
+/**
+ * One bounded failure detail. `pointer` is an RFC 6901 JSON Pointer into the
+ * checked document: the schema for admission issues, the outcome for
+ * validation issues (`''` is the document root). `keyword` is the JSON Schema
+ * keyword at fault, or a document-level code: `not-serializable`,
+ * `not-plain-json`, `over-cap`, `too-deep` (JSON nesting), `schema` (a
+ * subschema that is not an object) or `depth` (subschema nesting).
+ */
+export interface ResultIssue {
+    readonly pointer: string;
+    readonly keyword: string;
+    readonly message: string;
+}
+/** Document-level failure shared by the schema and outcome checks. */
+export type ResultDocumentFailureReason = 'not-serializable' | 'not-plain-json' | 'over-cap' | 'too-deep';
+interface ResultFailure<Reason extends string> {
+    readonly ok: false;
+    readonly reason: Reason;
+    /** Canonical UTF-8 size, when it was measured. */
+    readonly bytes?: number;
+    /** At least one issue; at most {@link RESULT_ISSUES_MAX_COUNT} and {@link RESULT_ISSUES_MAX_BYTES}. */
+    readonly issues: readonly ResultIssue[];
+    /** True when issues were dropped to respect the caps. */
+    readonly truncated: boolean;
+}
+export type ResultSchemaCheck = {
+    readonly ok: true;
+    readonly bytes: number;
+    readonly canonical: ResultSchema;
+} | ResultFailure<ResultDocumentFailureReason | 'not-subset'>;
+export type ResultOutcomeCheck = {
+    readonly ok: true;
+    readonly bytes: number;
+    readonly canonical: unknown;
+} | ResultFailure<'schema-not-admitted' | ResultDocumentFailureReason | 'schema-mismatch'>;
+/**
+ * The admission guard for a result-document schema. Accepts only plain JSON
+ * data of at most {@link RESULT_SCHEMA_MAX_BYTES} canonical UTF-8 bytes that
+ * lies inside the subset (module comment). On success, `canonical` is the
+ * snapshot every party freezes and validates against.
+ */
+export declare function checkResultSchema(schema: unknown): ResultSchemaCheck;
+/**
+ * Validate one outcome document against a result schema. The guard
+ * ({@link checkResultSchema}) always runs first; a schema it refuses is
+ * `schema-not-admitted` and never reaches the library. The outcome must be
+ * plain JSON data of at most {@link RESULT_OUTCOME_MAX_BYTES} canonical UTF-8
+ * bytes, checked before validation. On success, `canonical` is the snapshot
+ * a sender stages and puts on the wire.
+ */
+export declare function validateResultOutcome(schema: unknown, outcome: unknown): ResultOutcomeCheck;
+export {};

package/dist/task-assertion.d.ts

@@ -26,5 +26,3 @@
  * carries this exact literal, so a name legal in only one of the two channels
  * would leave them naming different things.
  */
-/** Contract §8.1's capability gate for `byok-task-assertion-v1` tool authority. */
-export declare const HOST_MCP_TASK_CONTEXT_CAPABILITY: 'host-mcp-task-context';

package/dist/terminal-projection.d.ts

@@ -1,12 +1,19 @@
 import { z } from 'zod';
-/** Capability required before an offer may select terminal projection behavior. */
-export declare const TERMINAL_PROJECTION_SELECTION_CAPABILITY: 'terminal-projection-selection';
+import { type ResultSchema } from './result-schema';
 export declare const TerminalProjectionContractSchema: z.ZodString;
-/** Offer-scoped authority: explicit bypass or one required structured result. */
+/**
+ * The frozen outcome schema of a result-document offer (wire v3). The value
+ * is kept exactly as sent; {@link checkResultSchema} decides admission, so
+ * every decode (Host submit, server/cloud parse, daemon admission) applies
+ * the one subset guard and reports its capped issues.
+ */
+export declare const ResultDocumentSchemaSchema: z.ZodCustom<ResultSchema, ResultSchema>;
+/** Offer-scoped authority: explicit bypass or one required structured result with its frozen schema. */
 export declare const TerminalProjectionSelectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     mode: z.ZodLiteral<"none">;
 }, z.core.$strict>, z.ZodObject<{
     mode: z.ZodLiteral<"result-document">;
     contract: z.ZodString;
+    schema: z.ZodCustom<ResultSchema, ResultSchema>;
 }, z.core.$strict>], "mode">;
 export type TerminalProjectionSelection = z.infer<typeof TerminalProjectionSelectionSchema>;

package/dist/version.d.ts

@@ -2,15 +2,22 @@
 export declare const MAILBOX_READ_AHEAD_MAX_SEQS = 4096;
 export declare const MAILBOX_READ_AHEAD_CAPABILITY = "mailbox-read-ahead";
 /**
- * Wire protocol version. Bump on breaking (non-additive) changes to the envelope
- * or message shapes. Additive changes (new optional fields, new message types)
- * do not require a bump — servers negotiate the highest common version and
- * daemons/servers must ignore unknown fields and unknown message types.
+ * Wire protocol version. Every v3 change is a version bump, a gated addition
+ * or a strip-safe addition: see docs/protocol.md "Freeze rule", which is the
+ * one statement of the rule, and `src/wire-additions.ts`, which declares the
+ * receiver-capability gates and additions. No v3 release has been published
+ * yet, so `src/__tests__/compat.test.ts` has no published v3 decoder to prove
+ * additions against; cross-release gates stay unproven until one exists.
  *
- * FROZEN (see docs/protocol.md "Freeze rule"): `PROTOCOL_VERSION` does not
- * bump for additive changes (new optional fields, new message types, new
- * `AgentEvent` variants, new capability flags) — only for a breaking one
- * (changing, removing, or retyping anything that already exists).
+ * v3 makes `schema` required on the `terminalProjection.mode:
+ * 'result-document'` arm (`terminal-projection.ts`, `result-schema.ts`): the
+ * offer freezes the outcome schema, and the outcome reaches the Host only as
+ * `task.complete.document`. That narrows a strict shape, so it is a wire
+ * major. A v2 envelope is rejected; there is no v2 reader and no capability
+ * negotiation between the two result-document shapes. Drain, then upgrade
+ * server and client together. Every addition v2 declared is part of the v3
+ * baseline, and the v2 `result-document` capability flag is gone: every v3
+ * server keeps `task.complete.document`.
  *
  * v2 removed the task offer's `policy` (`PermissionPolicy`), the runtime
  * capability `permissionModes` and the input-preparation `permissionMode`.
@@ -23,18 +30,8 @@ export declare const MAILBOX_READ_AHEAD_CAPABILITY = "mailbox-read-ahead";
  * and the readiness reason `executor_identity_unproven`. The SDK does not
  * attest tool executables. The artifact names its counted tools in
  * `toolNames`.
- *
- * IMPORTANT: changing this constant, or changing/removing/retyping any
- * already-frozen schema in this package, requires a DELIBERATE update to the
- * committed golden fixtures in `src/__tests__/golden/` (`v<N>.frozen.json`,
- * `v<N>.envelopes.ndjson`) — see `src/__tests__/freeze-guard.test.ts`, which
- * fails loudly on exactly that kind of drift. A passing freeze-guard run
- * after such a change means either (a) the change was genuinely additive and
- * the golden was regenerated with justification, or (b) this constant was
- * bumped alongside a new golden generation for the new version — never a
- * silent edit to either file to make the test pass.
  */
-export declare const PROTOCOL_VERSION = 2;
+export declare const PROTOCOL_VERSION = 3;
 /** Host declares that this device accepts only Agent-bound offer variants. */
 export declare const STRICT_AGENT_ONLY_CAPABILITY: 'strict-agent-only';
 /**
@@ -89,27 +86,6 @@ export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
  * other flag here, just consumed for observability instead of gating.
  */
 /**
- * `result-document` (additive-minor): a SERVER-advertised flag meaning "I
- * understand the optional `task.complete.document` field" (`messages.ts`).
- * Functionally gating, like `approval_resolved` and unlike
- * `approval-targeting`.
- *
- * This is the N/N-1 answer for that new daemon -> server FIELD. An old
- * server's transport advertisement (`conn.ack.capabilities` on WS or
- * `EventsPollResponse.capabilities` on long-poll) never includes it, and
- * its `TaskCompletePayloadSchema` is a tolerant (non-`.strict()`)
- * `z.object()`, so a `document` sent to it would be silently STRIPPED on
- * parse and vanish without a trace. That is exactly why emission is gated
- * here rather than sent unconditionally the way `approvalId` is: `document`
- * carries the task's primary structured RESULT, so losing it silently is
- * data loss, not a missed observability hint. A new daemon talking to an old
- * server therefore never sends `document` at all, and — if its configured
- * extractor did produce one — reports `task.fail` (retryable: false; the
- * same server will strip it on every retry too) instead of completing the
- * task with its main result quietly deleted (`packages/client`'s
- * `task-runner.ts`). A new server talking to an old daemon is unaffected:
- * the field is optional, and an old daemon simply never sets it.
- *
  * `dispatch-selection` (additive-minor) is a correctness gate for the
  * optional `task.offer.dispatchSelection` control field. An older v1 daemon
  * legally strips unknown optional fields, so a server must never send an
@@ -124,5 +100,5 @@ export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
  * cannot accidentally execute the instruction without the required tools.
  */
 export declare const CUSTOM_HARNESS_CAPABILITY: 'custom-harness';
-export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'result-document', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "agent-home-readers", "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v9", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead", "provider-provisioning.v1", "agent-memory-intent.v1"];
+export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "agent-home-readers", "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v9", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead", "provider-provisioning.v1", "agent-memory-intent.v1"];
 export type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];

package/dist/wire-additions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The one table of receiver-capability gates and wire additions
+ * (docs/protocol.md "Freeze rule").
+ *
+ * A v3 change takes exactly one of three paths: a version bump, a gated
+ * addition, or a strip-safe addition. Envelope and HTTP rows have explicit
+ * kinds. The last two are declared here.
+ *
+ * - `gated`: the sender must not emit the surface unless the receiver
+ *   durably advertised `capability`. A field entry applies when the payload
+ *   carries the field (and, with `value`, when the field equals it); a type
+ *   entry applies to every message of that type. Server-to-daemon surfaces
+ *   are gated by a device flag, daemon-to-server surfaces by a server flag.
+ * - `strip-safe`: an optional field an older receiver drops without changing
+ *   what it executes or acknowledges.
+ *
+ * v3 baseline: every v3 decoder reads every surface v2 had, so the v2
+ * strip-safe rows and the v2 `result-document` gate are gone. The device
+ * gates kept below name capabilities a daemon advertises only when it is
+ * configured for them (Agent home, egress, input preparation, provisioning,
+ * memory intents and so on): they gate on the receiver's configuration. The
+ * server-advertised `approval_resolved` gate is kept as the daemon's sending
+ * condition for `task.approval_resolved`. No v3 release has been
+ * published, so no row is proven against a published v3 decoder yet
+ * (`src/__tests__/compat.test.ts`).
+ *
+ * Senders derive their admission flags from {@link requiredReceiverCapabilities}
+ * and nowhere else, so a gate cannot exist in one place and be missing in
+ * another. This module imports no runtime code (types only) so it stays free
+ * of zod.
+ */
+import type { MessageType } from './messages';
+import type { CapabilityFlag } from './version';
+type HttpWireSurface = 'ChallengeRequest' | 'ChallengeResponse' | 'TokenRequest' | 'TokenResponse' | 'EventsPollQuery' | 'EventsPollResponse' | 'MessagesSendRequest' | 'MessagesSendResponse';
+export type WireAddition = {
+    readonly kind: 'envelope';
+    readonly rule: 'gated';
+    readonly surface: MessageType;
+    readonly field?: string;
+    readonly value?: string;
+    readonly capability: CapabilityFlag;
+    readonly advertisedBy: 'device' | 'server';
+} | {
+    readonly kind: 'envelope';
+    readonly rule: 'strip-safe';
+    readonly surface: MessageType;
+    readonly field: string;
+} | {
+    readonly kind: 'http';
+    readonly rule: 'strip-safe';
+    readonly surface: HttpWireSurface;
+    readonly field: string;
+};
+export declare const WIRE_ADDITIONS: readonly WireAddition[];
+/**
+ * Every capability the receiver must have durably advertised before a sender
+ * may emit this message. Deduplicated, in table order. A sender refuses (before
+ * creating the task or appending to the mailbox) when any is missing.
+ */
+export declare function requiredReceiverCapabilities(type: MessageType, payload: unknown): CapabilityFlag[];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/protocol",
-  "version": "0.26.1",
+  "version": "0.27.0-rc.2",
   "description": "BYOK SDK wire protocol: envelope schema, message types, and codec helpers",
   "type": "module",
   "license": "MIT",
@@ -26,9 +26,9 @@
       "import": "./dist/index.js"
     },
     "./package.json": "./package.json",
-    "./input-preparation-version": {
-      "types": "./dist/input-preparation-version.d.ts",
-      "import": "./dist/input-preparation-version.js"
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "import": "./dist/constants.js"
     }
   },
   "files": [
@@ -48,6 +48,10 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@cfworker/json-schema": "4.1.1",
     "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "byok-protocol-previous": "https://registry.npmjs.org/@byok-sdk/protocol/-/protocol-0.26.1.tgz"
   }
 }

package/dist/input-preparation-version.d.ts

@@ -1,12 +0,0 @@
-/**
- * The ONE version of the input-preparation contract, shared by this relay wire
- * (the `agent.input.preparation` payload and the completion receipt summary)
- * and by the device-local request, receipt and artifact
- * (`@byok-sdk/client`'s `INPUT_PREPARATION_VERSION`, which is this value).
- *
- * The relay wire carries no version field of its own, so a version change is
- * made visible where admission actually happens: in the capability token
- * below. See `INPUT_PREPARATION_VERSION` in the client for what each version
- * changed.
- */
-export declare const INPUT_PREPARATION_WIRE_VERSION: 9;

package/dist/input-preparation-version.js

@@ -1,6 +0,0 @@
-// src/input-preparation-version.ts
-var INPUT_PREPARATION_WIRE_VERSION = 9;
-
-export { INPUT_PREPARATION_WIRE_VERSION };
-//# sourceMappingURL=input-preparation-version.js.map
-//# sourceMappingURL=input-preparation-version.js.map