@byok-sdk/protocol 0.2.0 → 0.3.0

package/dist/messages.d.ts

@@ -34,6 +34,7 @@ export declare const RuntimeCapabilitiesSchema: z.ZodObject<{
     steer: z.ZodOptional<z.ZodBoolean>;
     resume: z.ZodOptional<z.ZodBoolean>;
     approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+    mcpToolsets: z.ZodOptional<z.ZodBoolean>;
     permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type RuntimeCapabilities = z.infer<typeof RuntimeCapabilitiesSchema>;
@@ -54,6 +55,7 @@ export declare const RuntimeInfoSchema: z.ZodObject<{
         steer: z.ZodOptional<z.ZodBoolean>;
         resume: z.ZodOptional<z.ZodBoolean>;
         approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+        mcpToolsets: z.ZodOptional<z.ZodBoolean>;
         permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -76,6 +78,7 @@ export declare const ConnHelloPayloadSchema: z.ZodObject<{
             steer: z.ZodOptional<z.ZodBoolean>;
             resume: z.ZodOptional<z.ZodBoolean>;
             approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+            mcpToolsets: z.ZodOptional<z.ZodBoolean>;
             permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
@@ -89,6 +92,28 @@ export declare const ConnAckPayloadSchema: z.ZodObject<{
     serverTime: z.ZodISODateTime;
 }, z.core.$strip>;
 export type ConnAckPayload = z.infer<typeof ConnAckPayloadSchema>;
+/**
+ * The web-selected runtime/model target carried end to end with a task.
+ *
+ * This is an additive v1 field. The discriminated union makes lane ownership
+ * fail closed at decode time: subscription credentials can only belong to the
+ * vendor CLIs, while a BYOK provider can only be executed through Pi.
+ */
+export declare const DispatchSelectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    lane: z.ZodLiteral<"subscription">;
+    runtimeId: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+    }>;
+    providerId: z.ZodNull;
+    modelId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    lane: z.ZodLiteral<"byok">;
+    runtimeId: z.ZodLiteral<"pi">;
+    providerId: z.ZodString;
+    modelId: z.ZodString;
+}, z.core.$strict>], "lane">;
+export type DispatchSelection = z.infer<typeof DispatchSelectionSchema>;
 /**
  * server -> daemon: offer a task for a device to claim.
  *
@@ -122,6 +147,20 @@ export declare const TaskOfferPayloadSchema: z.ZodObject<{
         codex: "codex";
         pi: "pi";
     }>>;
+    dispatchSelection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        lane: z.ZodLiteral<"subscription">;
+        runtimeId: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+        }>;
+        providerId: z.ZodNull;
+        modelId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        lane: z.ZodLiteral<"byok">;
+        runtimeId: z.ZodLiteral<"pi">;
+        providerId: z.ZodString;
+        modelId: z.ZodString;
+    }, z.core.$strict>], "lane">>;
     sessionRef: z.ZodOptional<z.ZodString>;
     workspaceHint: z.ZodOptional<z.ZodString>;
     limits: z.ZodOptional<z.ZodObject<{
@@ -130,6 +169,73 @@ export declare const TaskOfferPayloadSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type TaskOfferPayload = z.infer<typeof TaskOfferPayloadSchema>;
+/**
+ * Logical, host-owned MCP toolset identifier. A task may request this name,
+ * but the executable/server definition behind it exists only in the daemon's
+ * local configuration and never crosses the SaaS wire.
+ */
+export declare const ToolsetIdSchema: z.ZodString;
+export type ToolsetId = z.infer<typeof ToolsetIdSchema>;
+/** Every named toolset is required; duplicates are rejected instead of silently de-duplicated. */
+export declare const RequiredToolsetsSchema: z.ZodArray<z.ZodString>;
+/**
+ * Additive v1 offer variant for tasks whose semantics require local MCP
+ * tools. This is a distinct message type rather than an optional field on
+ * `task.offer`: an older v1 daemon skips an unknown message type, whereas it
+ * would legally strip an unknown optional control field and run the task
+ * without its required tools. The whole payload is strict because every
+ * field here affects execution authority.
+ */
+export declare const TaskOfferWithToolsetsPayloadSchema: z.ZodObject<{
+    instruction: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        blobRef: z.ZodObject<{
+            blobId: z.ZodString;
+            contentHash: z.ZodString;
+            size: z.ZodNumber;
+            contentType: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strict>]>;
+    policy: z.ZodObject<{
+        mode: z.ZodEnum<{
+            auto: "auto";
+            confirm: "confirm";
+            plan: "plan";
+            readonly: "readonly";
+        }>;
+        allowTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        denyTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        workspaceRoot: z.ZodOptional<z.ZodString>;
+        network: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    runtime: z.ZodOptional<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        pi: "pi";
+    }>>;
+    dispatchSelection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        lane: z.ZodLiteral<"subscription">;
+        runtimeId: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+        }>;
+        providerId: z.ZodNull;
+        modelId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        lane: z.ZodLiteral<"byok">;
+        runtimeId: z.ZodLiteral<"pi">;
+        providerId: z.ZodString;
+        modelId: z.ZodString;
+    }, z.core.$strict>], "lane">>;
+    sessionRef: z.ZodOptional<z.ZodString>;
+    workspaceHint: z.ZodOptional<z.ZodString>;
+    limits: z.ZodOptional<z.ZodObject<{
+        maxDurationMs: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    requiredToolsets: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type TaskOfferWithToolsetsPayload = z.infer<typeof TaskOfferWithToolsetsPayloadSchema>;
 /**
  * server -> daemon: approve a pending `task.await_approval` request.
  *
@@ -241,6 +347,7 @@ export declare const TaskClaimPayloadSchema: z.ZodObject<{
         steer: z.ZodOptional<z.ZodBoolean>;
         resume: z.ZodOptional<z.ZodBoolean>;
         approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+        mcpToolsets: z.ZodOptional<z.ZodBoolean>;
         permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -356,7 +463,125 @@ export declare const TaskAwaitApprovalPayloadSchema: z.ZodObject<{
     approvalId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TaskAwaitApprovalPayload = z.infer<typeof TaskAwaitApprovalPayloadSchema>;
-/** daemon -> server: task finished successfully. */
+/**
+ * Hard cap (1 MiB) on a single `task.complete.document` (see
+ * {@link TaskCompletePayloadSchema}), measured as the UTF-8 byte length of
+ * its canonical JSON encoding — NOT as a node/key count, since a document is
+ * schema-neutral and its object shape is unbounded by design.
+ *
+ * The cap is a REJECT-AT-BOUNDARY limit on both sides: a daemon that
+ * produces an over-cap document reports `task.fail` instead of sending it,
+ * and a server rejects an over-cap document at schema validation. It is
+ * never truncated — a truncated JSON document is not valid JSON, so
+ * "shrinking to fit" can only hand the consumer garbage.
+ *
+ * 1 MiB is the conservative ceiling declared by the first real consumer
+ * (`docs/researches/2026-08-12-salesko-consumption-evidence.md` §1/§2:
+ * smallest real frame 8.4 KiB, typical 48-96 KiB, 512 KiB comfortable).
+ * Producers should stay at or under ~512 KiB (docs/protocol.md); the extra
+ * headroom exists because raising a protocol cap later is additive while
+ * lowering one is breaking. A result too big for this channel belongs in
+ * `artifactRefs` (the multi-file/binary/oversized channel), not here.
+ */
+export declare const RESULT_DOCUMENT_MAX_BYTES = 1048576;
+/**
+ * Outcome of {@link checkResultDocument}.
+ *
+ * `bytes` is the measured canonical JSON UTF-8 byte length, present on both
+ * the accept and the over-cap rejection so a caller can name the actual size
+ * 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';
+};
+/**
+ * THE single authority for "is this a legal `task.complete.document`", and
+ * the one place its canonical form is produced. `TaskCompletePayloadSchema`'s
+ * own refinement calls it, and the daemon-side pre-send gate
+ * (`packages/client`'s `task-runner.ts`) imports and calls the exact same
+ * function rather than re-deriving any part of it: a daemon that measured or
+ * judged a document even slightly differently from the server that validates
+ * it would either reject documents the wire would have accepted, or hand the
+ * server a payload it is about to reject after the runtime session already
+ * ended.
+ *
+ * **The contract is: a document must be PLAIN JSON DATA.** Not "an object
+ * that happens to survive `JSON.stringify`" — that bar is far too low, and
+ * two concrete attacks/mistakes live under it:
+ *
+ *   1. `JSON.stringify` succeeding does not mean the value was preserved. An
+ *      `undefined`-valued key, a `NaN`, a function-valued property, or a
+ *      `Date` all serialize "successfully" while silently becoming something
+ *      else (dropped, `null`, or a string). The result is a well-formed,
+ *      under-cap document that is not what the producer had — a confidently
+ *      wrong terminal result, the worst outcome this channel has.
+ *   2. `toJSON(key)` receives the property key it is being serialized under,
+ *      so an object can legally answer one way at the root (`key === ''`,
+ *      where this function measures it) and a completely different way when
+ *      nested inside the envelope payload (`key === 'document'`, where the
+ *      codec actually serializes it). A root-only measurement is therefore
+ *      not a bound on what goes on the wire at all. The same hole exists for
+ *      any getter that answers differently on a second read.
+ *
+ * Both die together via the same mechanism. The steps:
+ *
+ *   1. `JSON.stringify` must succeed and not return `undefined`.
+ *   2. Its UTF-8 byte length must be within {@link RESULT_DOCUMENT_MAX_BYTES}.
+ *   3. `JSON.parse` that string — the CANONICAL SNAPSHOT. It is pure data:
+ *      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
+ *      JSON data, and it is rejected rather than silently transformed.
+ *
+ * On success the snapshot is returned as `canonical`, and **every sender
+ * must put THAT on the wire, never the original reference** — which is what
+ * closes the contextual-`toJSON`/unstable-getter hole for good: pure data
+ * serializes identically at the root and nested, so what was measured is
+ * necessarily what is sent. The check is idempotent on pure data, so the
+ * server re-running it on an already-parsed payload is a no-op that always
+ * agrees.
+ */
+export declare function checkResultDocument(document: unknown): ResultDocumentCheck;
+/**
+ * daemon -> server: task finished successfully.
+ *
+ * `document` (additive-minor, docs/protocol.md "Freeze rule"): 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
+ * `z.unknown()`: this SDK never understands, validates, or transforms the
+ * product's own document schema — that validation belongs to the consumer.
+ * The only constraints the wire imposes are the ones
+ * {@link checkResultDocument} enforces: it must be PLAIN JSON DATA (equal to
+ * its own JSON round trip — see that function for why "stringify succeeded"
+ * is not enough), and its canonical JSON UTF-8 encoding must be at most
+ * {@link RESULT_DOCUMENT_MAX_BYTES}. An over-cap document is REJECTED here,
+ * 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`.
+ */
 export declare const TaskCompletePayloadSchema: z.ZodObject<{
     summary: z.ZodString;
     sessionRef: z.ZodString;
@@ -367,6 +592,7 @@ export declare const TaskCompletePayloadSchema: z.ZodObject<{
         contentType: z.ZodString;
         url: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    document: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
 export type TaskCompletePayload = z.infer<typeof TaskCompletePayloadSchema>;
 /** daemon -> server: task failed. */
@@ -464,6 +690,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
                 steer: z.ZodOptional<z.ZodBoolean>;
                 resume: z.ZodOptional<z.ZodBoolean>;
                 approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+                mcpToolsets: z.ZodOptional<z.ZodBoolean>;
                 permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
@@ -501,6 +728,20 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             codex: "codex";
             pi: "pi";
         }>>;
+        dispatchSelection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            lane: z.ZodLiteral<"subscription">;
+            runtimeId: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+            }>;
+            providerId: z.ZodNull;
+            modelId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            lane: z.ZodLiteral<"byok">;
+            runtimeId: z.ZodLiteral<"pi">;
+            providerId: z.ZodString;
+            modelId: z.ZodString;
+        }, z.core.$strict>], "lane">>;
         sessionRef: z.ZodOptional<z.ZodString>;
         workspaceHint: z.ZodOptional<z.ZodString>;
         limits: z.ZodOptional<z.ZodObject<{
@@ -508,6 +749,55 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             maxTokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
+    readonly 'task.offer_with_toolsets': z.ZodObject<{
+        instruction: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            blobRef: z.ZodObject<{
+                blobId: z.ZodString;
+                contentHash: z.ZodString;
+                size: z.ZodNumber;
+                contentType: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strict>]>;
+        policy: z.ZodObject<{
+            mode: z.ZodEnum<{
+                auto: "auto";
+                confirm: "confirm";
+                plan: "plan";
+                readonly: "readonly";
+            }>;
+            allowTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            denyTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            workspaceRoot: z.ZodOptional<z.ZodString>;
+            network: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        runtime: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            pi: "pi";
+        }>>;
+        dispatchSelection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            lane: z.ZodLiteral<"subscription">;
+            runtimeId: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+            }>;
+            providerId: z.ZodNull;
+            modelId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            lane: z.ZodLiteral<"byok">;
+            runtimeId: z.ZodLiteral<"pi">;
+            providerId: z.ZodString;
+            modelId: z.ZodString;
+        }, z.core.$strict>], "lane">>;
+        sessionRef: z.ZodOptional<z.ZodString>;
+        workspaceHint: z.ZodOptional<z.ZodString>;
+        limits: z.ZodOptional<z.ZodObject<{
+            maxDurationMs: z.ZodOptional<z.ZodNumber>;
+            maxTokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        requiredToolsets: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
     readonly 'task.approve': z.ZodObject<{
         approvalId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -533,6 +823,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             steer: z.ZodOptional<z.ZodBoolean>;
             resume: z.ZodOptional<z.ZodBoolean>;
             approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+            mcpToolsets: z.ZodOptional<z.ZodBoolean>;
             permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
@@ -603,6 +894,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             contentType: z.ZodString;
             url: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        document: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
     readonly 'task.fail': z.ZodObject<{
         reason: z.ZodString;
@@ -630,7 +922,7 @@ export declare const MESSAGE_TYPES: MessageType[];
  * (`envelope.ts`) to decide which branches require envelope `seq` (M1
  * redelivery cursor).
  */
-export declare const SERVER_TO_DAEMON_TYPES: readonly ["conn.ack", "task.offer", "task.approve", "task.reject", "task.cancel", "task.steer"];
+export declare const SERVER_TO_DAEMON_TYPES: readonly ["conn.ack", "task.offer", "task.offer_with_toolsets", "task.approve", "task.reject", "task.cancel", "task.steer"];
 /**
  * Message types the daemon sends to the server — the flip side of
  * {@link SERVER_TO_DAEMON_TYPES}. `conn.hello` is deliberately excluded: it's

package/dist/version.d.ts

@@ -66,5 +66,39 @@ export declare const PROTOCOL_VERSION = 1;
  * participate in targeting at all -- the same N/N-1-safe shape as every
  * other flag here, just consumed for observability instead of gating.
  */
-export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting'];
+/**
+ * `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 `CAPABILITY_FLAGS`/`conn.ack.capabilities` 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
+ * authoritative provider/model selection unless the target connection
+ * advertises this flag. Absence means reject before task creation, not send
+ * a legacy runtime-only offer that could reach a different provider.
+ *
+ * `toolset-selection` (additive-minor) means the daemon understands
+ * `task.offer_with_toolsets` and can resolve its logical ids against local
+ * MCP configuration. The distinct message type is also the N/N-1 safety
+ * boundary for long-poll: an older daemon skips it as unknown and therefore
+ * cannot accidentally execute the instruction without the required tools.
+ */
+export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'result-document', 'dispatch-selection', 'toolset-selection'];
 export type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/protocol",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "BYOK SDK wire protocol: envelope schema, message types, and codec helpers",
   "type": "module",
   "license": "MIT",