@byok-sdk/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ancienttwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @byok-sdk/protocol
+
+The frozen v1 BYOK device wire contract: envelope schemas, message payloads,
+codecs, version negotiation, and golden fixtures.
+
+```ts
+import { encodeEnvelope, decodeEnvelope } from '@byok-sdk/protocol';
+```
+
+MIT licensed. Node.js 20 or newer.

package/dist/agent-event.d.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+/**
+ * Normalized event shape that every runtime adapter (pi / claude / codex)
+ * translates its native JSONL output into. This is the interior of a
+ * `task.progress` payload's `events` array.
+ */
+export declare const AgentEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_use">;
+    tool: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_result">;
+    tool: z.ZodString;
+    output: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"artifact">;
+    name: z.ZodString;
+    contentType: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"needs_approval">;
+    summary: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"turn_end">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"usage">;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+export type AgentEvent = z.infer<typeof AgentEventSchema>;
+/**
+ * Known AgentEvent variant type discriminators — DERIVED directly from
+ * {@link AgentEventSchema}'s own discriminated-union variants via
+ * `z.toJSONSchema`, rather than hand-maintained as a second literal list.
+ * This used to be a standalone array kept in sync with the schema above by
+ * hand (dual authority); the freeze guard
+ * (`__tests__/freeze-guard.test.ts`'s "dual-authority cross-check") already
+ * asserted the two matched using this EXACT SAME `z.toJSONSchema` extraction
+ * mechanism, which is why deriving it this way is safe: the guard already
+ * proved this extraction produces the identical set the hand-written list
+ * held. With the derivation below, the two can no longer drift apart at
+ * all — there is only one authority now, {@link AgentEventSchema} itself.
+ * The freeze guard test is kept anyway (now definitionally true rather than
+ * a live check) as a regression net in case a future refactor reintroduces a
+ * hand-written list.
+ *
+ * Exported (not module-private) so {@link isKnownAgentEvent} /
+ * {@link partitionAgentEvents} (and the freeze guard) can check against the
+ * exact same set without each reaching into zod's discriminated-union
+ * internals directly. `z.toJSONSchema`'s output shape here (`.oneOf[].
+ * properties.type.const`) is a public, documented zod v4 API — not
+ * reaching into `._def`/internal fields — same as the freeze guard already
+ * relies on.
+ */
+export declare const KNOWN_AGENT_EVENT_TYPES: readonly string[];
+/**
+ * Pre-freeze compatibility widening (the freeze blocker this schema fixes):
+ * an unknown-type event — one a future runtime/protocol minor version
+ * introduces — parses as an opaque passthrough placeholder instead of
+ * hard-failing the entire `task.progress` batch it arrived in. Without this,
+ * `TaskProgressPayloadSchema.events: z.array(AgentEventSchema)` would throw
+ * on the whole array the moment one event had an unrecognized `type`, which
+ * made the wire's "additive new variants are non-breaking" promise false for
+ * the installed base — and unfixable post-freeze.
+ *
+ * The `.refine` guard is load-bearing, not decorative: it excludes every
+ * KNOWN type literal, so a *malformed* known variant (e.g. `progress`
+ * missing `text`) still fails validation instead of silently matching this
+ * fallback. Tolerance is only for unknown TYPES, never for malformed known
+ * ones — see {@link AgentEventOrUnknownSchema}, which is what actually
+ * combines this with {@link AgentEventSchema} for real use.
+ *
+ * Deliberately asymmetric with envelope-level control/security fields
+ * (`instruction`, `policy` — see `messages.ts`/`permission.ts`), which stay
+ * fail-closed on unknown shapes with no equivalent widening: this tolerance
+ * applies only to observability data (agent progress events), never to
+ * control/security surfaces. That asymmetry is the freeze rule.
+ */
+export declare const UnknownAgentEventSchema: z.ZodObject<{
+    type: z.ZodString;
+}, z.core.$loose>;
+export type UnknownAgentEvent = z.infer<typeof UnknownAgentEventSchema>;
+/**
+ * The actual element schema for `TaskProgressPayloadSchema.events`
+ * (`messages.ts`): a known, fully-typed {@link AgentEvent} OR an opaque
+ * unknown-type placeholder. `z.union` (not `discriminatedUnion`) is required
+ * here because the fallback branch matches on "not one of the known
+ * literals", which a discriminated union can't express directly.
+ */
+export declare const AgentEventOrUnknownSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_use">;
+    tool: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_result">;
+    tool: z.ZodString;
+    output: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"artifact">;
+    name: z.ZodString;
+    contentType: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"needs_approval">;
+    summary: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"turn_end">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"usage">;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "type">, z.ZodObject<{
+    type: z.ZodString;
+}, z.core.$loose>]>;
+export type AgentEventOrUnknown = z.infer<typeof AgentEventOrUnknownSchema>;
+/**
+ * Type guard distinguishing a known, fully-typed {@link AgentEvent} from an
+ * {@link UnknownAgentEvent} passthrough placeholder.
+ */
+export declare function isKnownAgentEvent(event: AgentEventOrUnknown): event is AgentEvent;
+/**
+ * Split a `task.progress` events array into known (typed, actionable) and
+ * unknown (opaque, safe-to-skip) events. Consumers should process `known`
+ * and skip `unknown` rather than throwing on it — that's the point of the
+ * pre-freeze tolerance above.
+ */
+export declare function partitionAgentEvents(events: readonly AgentEventOrUnknown[]): {
+    known: AgentEvent[];
+    unknown: UnknownAgentEvent[];
+};

package/dist/blob.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/**
+ * Canonical `contentHash` format (finding F9): `sha256:` followed by exactly
+ * 64 lowercase hex characters (a SHA-256 digest). Pinned here — the single
+ * source of truth both `BlobRefSchema` and `CreateBlobRequestSchema`
+ * (`http-api.ts`) validate against — rather than left as a bare `z.string()`
+ * that silently accepted any prefix (or none) and left the server to
+ * reconcile the mismatch with an ad hoc normalization step. No compat shim:
+ * the wire is pre-freeze (`v` stays `1`), so this is a straight tightening,
+ * not a migration.
+ */
+export declare const CONTENT_HASH_RE: RegExp;
+/**
+ * Reference to a large payload that was pushed out-of-band (presigned PUT) or
+ * is fetchable out-of-band (presigned GET), rather than inlined in an envelope.
+ */
+export declare const BlobRefSchema: z.ZodObject<{
+    blobId: z.ZodString;
+    contentHash: z.ZodString;
+    size: z.ZodNumber;
+    contentType: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BlobRef = z.infer<typeof BlobRefSchema>;

package/dist/codec.d.ts

@@ -0,0 +1,116 @@
+import type { z } from 'zod';
+import { type Envelope } from './envelope';
+import { MESSAGE_PAYLOAD_SCHEMAS, type MessageType } from './messages';
+/**
+ * Validate an already-parsed JS value as an {@link Envelope}, narrowing
+ * `payload` by `type`. Throws {@link UnknownMessageTypeError} when `type`
+ * isn't a recognized message type (safe for the caller to skip/ignore), or
+ * {@link EnvelopeValidationError} when a recognized type fails schema
+ * validation.
+ */
+export declare function parseMessage(data: unknown): Envelope;
+/**
+ * Decode a single NDJSON line into a validated {@link Envelope}. Accepts a
+ * string or raw bytes (e.g. a WebSocket binary frame) — isomorphic, no
+ * stream handling required of the caller.
+ */
+export declare function decodeEnvelope(line: string | Uint8Array): Envelope;
+/** Encode an {@link Envelope} as a single-line NDJSON string (trailing `\n` included). */
+export declare function encodeEnvelope(env: Envelope): string;
+interface EnvelopeShapeOptions {
+    'conn.hello': {
+        taskId?: string;
+        seq?: number;
+    };
+    'conn.ack': {
+        taskId?: string;
+        seq: number;
+    };
+    'task.offer': {
+        taskId: string;
+        seq: number;
+    };
+    'task.approve': {
+        taskId: string;
+        seq: number;
+    };
+    'task.reject': {
+        taskId: string;
+        seq: number;
+    };
+    'task.cancel': {
+        taskId: string;
+        seq: number;
+    };
+    'task.steer': {
+        taskId: string;
+        seq: number;
+    };
+    'task.claim': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.started': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.decline': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.progress': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.artifact': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.await_approval': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.complete': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.fail': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.cancelled': {
+        taskId: string;
+        seq?: number;
+    };
+    'task.approval_resolved': {
+        taskId: string;
+        seq?: number;
+    };
+}
+interface EnvelopeCommonOptions {
+    id?: string;
+    ts?: string;
+    v?: number;
+    /** Always optional regardless of `type` (docs/protocol.md §1.3). */
+    sessionRef?: string;
+}
+/** Public options shape for `createEnvelope<T>` — conditionally required `taskId`/`seq` per `EnvelopeShapeOptions[T]`, plus the always-optional common fields. Defaults to the full `MessageType` union (a loose, all-optional-ish shape) when `T` isn't pinned, which is also what `createEnvelope`'s own implementation uses internally to read `opts` without fighting the per-call-site conditional. */
+export type CreateEnvelopeOptions<T extends MessageType = MessageType> = EnvelopeCommonOptions & EnvelopeShapeOptions[T];
+/** `never` unless every key of `T` is optional — i.e. whether `createEnvelope`'s `opts` argument can be omitted entirely for a given message type. */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: object extends Pick<T, K> ? never : K;
+}[keyof T];
+/** The rest-parameter shape for `createEnvelope`'s 3rd argument: present-and-optional when `T` needs nothing, present-and-required when it needs `taskId` and/or `seq`. */
+type CreateEnvelopeArgs<T extends MessageType> = RequiredKeys<EnvelopeShapeOptions[T]> extends never ? [opts?: CreateEnvelopeOptions<T>] : [opts: CreateEnvelopeOptions<T>];
+type PayloadOf<T extends MessageType> = z.infer<(typeof MESSAGE_PAYLOAD_SCHEMAS)[T]>;
+/**
+ * Build a well-formed {@link Envelope}, filling `v`/`id`/`ts` with defaults.
+ * `opts` (`taskId`/`seq`) is required or optional depending on `type` — see
+ * the module doc above — and the constructed envelope is validated against
+ * {@link EnvelopeSchema} before being returned, throwing
+ * {@link EnvelopeValidationError} if it doesn't satisfy the schema.
+ */
+export declare function createEnvelope<T extends MessageType>(type: T, payload: PayloadOf<T>, ...rest: CreateEnvelopeArgs<T>): Extract<Envelope, {
+    type: T;
+}>;
+export {};

package/dist/envelope.d.ts

@@ -0,0 +1,333 @@
+import { z } from 'zod';
+import { type MessageType } from './messages';
+/**
+ * The wire envelope: common transport fields plus a `payload` whose shape is
+ * determined by `type`. Unknown top-level fields are tolerated (stripped) for
+ * forward-compat; unknown `type` values do not match any branch below and are
+ * handled explicitly by {@link parseMessage} in `codec.ts`.
+ *
+ * Two cross-cutting requiredness rules, fixed at M1 (see docs/protocol.md
+ * "M0 -> M1 breaking changes"):
+ *
+ * - `task_id` is REQUIRED for every `task.*` type (they all route by task id)
+ *   and stays optional for `conn.*` (M1 gap #1).
+ * - `seq` is REQUIRED for every type the *server* sends to the daemon — a
+ *   per-device monotonic counter used as a redelivery cursor — and stays
+ *   optional for daemon -> server types (M1 redelivery cursor; see
+ *   `conn.hello.cursor` in `messages.ts`).
+ */
+export declare const EnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"conn.hello">;
+    task_id: z.ZodOptional<z.ZodString>;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        protocolVersions: z.ZodArray<z.ZodNumber>;
+        capabilities: z.ZodArray<z.ZodString>;
+        deviceId: z.ZodString;
+        productId: z.ZodString;
+        runtimes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                pi: "pi";
+            }>;
+            version: z.ZodOptional<z.ZodString>;
+            authPresent: z.ZodOptional<z.ZodBoolean>;
+            capabilities: z.ZodOptional<z.ZodObject<{
+                steer: z.ZodOptional<z.ZodBoolean>;
+                resume: z.ZodOptional<z.ZodBoolean>;
+                approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+                permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        cursor: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"conn.ack">;
+    task_id: z.ZodOptional<z.ZodString>;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    payload: z.ZodObject<{
+        protocolVersion: z.ZodNumber;
+        capabilities: z.ZodArray<z.ZodString>;
+        serverTime: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.offer">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    payload: 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";
+        }>>;
+        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>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.approve">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    payload: z.ZodObject<{
+        approvalId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.reject">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    payload: z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+        approvalId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.cancel">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    payload: z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.steer">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    payload: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.claim">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        deviceId: z.ZodString;
+        agentId: z.ZodOptional<z.ZodString>;
+        runtime: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            pi: "pi";
+        }>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            steer: z.ZodOptional<z.ZodBoolean>;
+            resume: z.ZodOptional<z.ZodBoolean>;
+            approvalInteractive: z.ZodOptional<z.ZodBoolean>;
+            permissionModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.started">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{}, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.decline">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        reason: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.progress">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        seq: z.ZodNumber;
+        events: z.ZodArray<z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"progress">;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tool_use">;
+            tool: z.ZodString;
+            input: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tool_result">;
+            tool: z.ZodString;
+            output: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"artifact">;
+            name: z.ZodString;
+            contentType: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"needs_approval">;
+            summary: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"turn_end">;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"error">;
+            message: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"usage">;
+            inputTokens: z.ZodOptional<z.ZodNumber>;
+            cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+            outputTokens: z.ZodOptional<z.ZodNumber>;
+            reasoningTokens: z.ZodOptional<z.ZodNumber>;
+            totalTokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], "type">, z.ZodObject<{
+            type: z.ZodString;
+        }, z.core.$loose>]>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.artifact">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        name: z.ZodString;
+        contentType: z.ZodString;
+        inline: z.ZodOptional<z.ZodString>;
+        blobRef: z.ZodOptional<z.ZodObject<{
+            blobId: z.ZodString;
+            contentHash: z.ZodString;
+            size: z.ZodNumber;
+            contentType: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.await_approval">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        summary: z.ZodString;
+        approvalId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.complete">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        summary: z.ZodString;
+        sessionRef: z.ZodString;
+        artifactRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            blobId: z.ZodString;
+            contentHash: z.ZodString;
+            size: z.ZodNumber;
+            contentType: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.fail">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        reason: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.cancelled">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodNumber;
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    type: z.ZodLiteral<"task.approval_resolved">;
+    task_id: z.ZodString;
+    session_ref: z.ZodOptional<z.ZodString>;
+    seq: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodObject<{
+        approvalId: z.ZodString;
+        decision: z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+        }>;
+        resolvedBy: z.ZodEnum<{
+            local: "local";
+        }>;
+        at: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+export type Envelope = z.infer<typeof EnvelopeSchema>;
+/** `true` for every message type the server sends to the daemon (envelope `seq` is required for these). */
+export declare function isServerToDaemonType(type: MessageType): boolean;

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+import type { ZodError } from 'zod';
+/** Base class for all protocol decode/validation errors. */
+export declare class ProtocolError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The input was not valid JSON at all (only thrown by `decodeEnvelope`). */
+export declare class EnvelopeParseError extends ProtocolError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * The `type` field did not match any known message type. This is distinct
+ * from {@link EnvelopeValidationError} on purpose: a daemon/server on an
+ * older minor version should catch this specifically and skip the message
+ * instead of treating it as a bug, since a newer peer may have introduced an
+ * additive message type it doesn't understand yet.
+ */
+export declare class UnknownMessageTypeError extends ProtocolError {
+    readonly type: unknown;
+    constructor(type: unknown);
+}
+/** The `type` field was recognized but the envelope/payload failed schema validation. */
+export declare class EnvelopeValidationError extends ProtocolError {
+    readonly issues: ZodError;
+    constructor(message: string, issues: ZodError);
+}