@byok-sdk/protocol 0.1.0

package/dist/messages.d.ts

@@ -0,0 +1,646 @@
+import { z } from 'zod';
+export declare const RuntimeIdSchema: z.ZodEnum<{
+    claude: "claude";
+    codex: "codex";
+    pi: "pi";
+}>;
+export type RuntimeId = z.infer<typeof RuntimeIdSchema>;
+/**
+ * Per-runtime feature flags reported in `conn.hello.runtimes[].capabilities`
+ * (pre-freeze addition). Distinct from the connection-level `CAPABILITY_FLAGS`
+ * (`version.ts`) / `conn.hello.capabilities` array: those are protocol-level
+ * flags negotiated for the whole connection, while this is what one specific
+ * detected runtime (pi/claude/codex) supports. The whole field is optional
+ * end-to-end — older daemons omit `capabilities` entirely — and every field
+ * inside it is itself optional, since detection can be partial.
+ *
+ * Per-tool allow/deny lists are deliberately NOT included here (noise).
+ * `permissionModes` mirrors `PERMISSION_MODES` (`permission.ts`) but is kept
+ * as a bare `string[]` rather than `z.enum(PERMISSION_MODES)`: this is a
+ * runtime's self-reported observability data, not a control/security field,
+ * so — per the freeze rule (tolerate unknown for observability, fail closed
+ * for control/security; see `agent-event.ts`'s unknown-variant tolerance for
+ * the same asymmetry applied to `task.progress` events) — it stays tolerant
+ * of a mode string a newer runtime might report that this schema doesn't
+ * enumerate yet, rather than rejecting the whole `conn.hello`.
+ *
+ * Unrecognized keys inside `capabilities` itself, by contrast, are silently
+ * stripped (zod's default object behavior — same as every other payload
+ * schema in this file) rather than passed through: this is a closed, typed
+ * shape consumers can rely on, and a genuinely new capability flag gets added
+ * here explicitly rather than round-tripped opaquely.
+ */
+export declare const RuntimeCapabilitiesSchema: 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>;
+export type RuntimeCapabilities = z.infer<typeof RuntimeCapabilitiesSchema>;
+/**
+ * Runtime detection info reported in `conn.hello`. Supersedes the M0
+ * `agents: unknown` field (M1 gap #4): typed, so the server no longer has to
+ * best-effort-normalize an untyped blob.
+ */
+export declare const RuntimeInfoSchema: 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>;
+export type RuntimeInfo = z.infer<typeof RuntimeInfoSchema>;
+/** daemon -> server: opening handshake. */
+export declare const ConnHelloPayloadSchema: 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>;
+export type ConnHelloPayload = z.infer<typeof ConnHelloPayloadSchema>;
+/** server -> daemon: handshake acknowledgement. */
+export declare const ConnAckPayloadSchema: z.ZodObject<{
+    protocolVersion: z.ZodNumber;
+    capabilities: z.ZodArray<z.ZodString>;
+    serverTime: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ConnAckPayload = z.infer<typeof ConnAckPayloadSchema>;
+/**
+ * server -> daemon: offer a task for a device to claim.
+ *
+ * `taskId` used to be duplicated here; it is now carried only by the
+ * envelope's `task_id` (M1 gap #7 — single source of truth for routing).
+ */
+export declare const TaskOfferPayloadSchema: 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>;
+export type TaskOfferPayload = z.infer<typeof TaskOfferPayloadSchema>;
+/**
+ * server -> daemon: approve a pending `task.await_approval` request.
+ *
+ * Semantics (M1 gap #3): the server's own state is authoritative on its own
+ * action — calling the server-side `approve()` API moves the task record
+ * `AwaitApproval -> Running` immediately. This wire message is a best-effort
+ * *notification* telling the daemon to resume the paused runtime session; the
+ * daemon does not send a dedicated ack. Its outcome is observable through the
+ * task's existing message stream (e.g. `task.progress` resuming, or
+ * `task.fail`/`task.cancelled` if resuming turns out to be impossible) — no
+ * new ack message type is introduced. See docs/protocol.md "Approval flow".
+ *
+ * `approvalId` (M5, additive-minor — docs/protocol.md §5.3): OPTIONAL target
+ * identity for the SPECIFIC pending approval this decision resolves, rather
+ * than "whichever one is currently pending" (the pre-M5 behavior, and still
+ * what happens when this field is absent — a legacy server that never
+ * learned an id, or one talking to a legacy daemon). When present, the
+ * daemon compares it against its own currently-dispatched approval id
+ * (`ActiveTask.pendingApprovalId`, `packages/client`'s `task-runner.ts`) and
+ * treats a mismatch as a stale, audit-only no-op instead of resolving
+ * whatever happens to be pending right now — see `TaskRunner.handleApprove`.
+ */
+export declare const TaskApprovePayloadSchema: z.ZodObject<{
+    approvalId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskApprovePayload = z.infer<typeof TaskApprovePayloadSchema>;
+/**
+ * server -> daemon: reject a pending `task.await_approval` request.
+ *
+ * Same best-effort-notification semantics as `task.approve` (M1 gap #3): the
+ * server moves its own record `AwaitApproval -> Failed` immediately; this
+ * message just tells the daemon to stop, and the daemon reports the outcome
+ * via its existing `task.fail` terminal message.
+ *
+ * `approvalId` (M5, additive-minor — docs/protocol.md §5.3): same optional
+ * targeting semantics as `TaskApprovePayloadSchema.approvalId` above, applied
+ * to the reject path (`TaskRunner.handleReject`).
+ */
+export declare const TaskRejectPayloadSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+    approvalId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskRejectPayload = z.infer<typeof TaskRejectPayloadSchema>;
+/**
+ * server -> daemon: cancel a task in any non-terminal state.
+ *
+ * Same best-effort-notification semantics (M1 gap #3): the server moves its
+ * own record to `Cancelled` immediately on its own action and does not wait
+ * for a daemon ack; this message just tells the daemon to stop local work.
+ * The daemon reports the outcome via the explicit `task.cancelled` terminal
+ * message (M1 gap #6) — not `task.fail`.
+ */
+export declare const TaskCancelPayloadSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskCancelPayload = z.infer<typeof TaskCancelPayloadSchema>;
+/** server -> daemon: inject steering text into a running task. */
+export declare const TaskSteerPayloadSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+export type TaskSteerPayload = z.infer<typeof TaskSteerPayloadSchema>;
+/**
+ * daemon -> server: claim an offered task (idempotent CAS on the server
+ * side). `taskId` used to be duplicated here; it is now carried only by the
+ * envelope's `task_id` (M1 gap #7).
+ *
+ * Claiming no longer implies the task is `Running` (M1 gap #2) — see
+ * `task.started`.
+ *
+ * `runtime` (M5, additive-minor — docs/protocol.md §3.1): the ACTUAL
+ * adapter this device selected for the task, distinct from `task.offer`'s
+ * own `runtime` (the merely REQUESTED one, `TaskOfferPayloadSchema.runtime`
+ * above). When an offer names no runtime the daemon auto-selects (pi-first —
+ * `TaskRunner.pickAdapter`, `packages/client`'s `task-runner.ts`), and before
+ * this field existed the server had no way to learn which adapter actually
+ * ran — `TaskSnapshot.runtime` (`packages/server`'s `types.ts`) only ever
+ * recorded what was requested. Plain optional property on this already-
+ * tolerant `z.object()`: an old server simply never reads it, so this needed
+ * no version bump and no emission gating (same shape as `approvalId` on
+ * `task.await_approval`/`task.approve`/`task.reject`, §5.3) — a new daemon
+ * sends it unconditionally, regardless of whether the connected server is
+ * new enough to store it.
+ *
+ * `capabilities` (S0/D-4, additive-minor — docs/protocol.md §2.4): the
+ * TASK-level capability authority — what the claiming adapter reported about
+ * itself at the moment it took this task, reusing `RuntimeCapabilitiesSchema`
+ * (above) rather than introducing a second capability shape. Same source of
+ * truth as `conn.hello.runtimes[].capabilities`, different scope: `conn.hello`
+ * is CONNECTION-level discovery ("what could this device run"), which no
+ * server-side control decision may read, because it is transport-shaped — a
+ * long-poll-only daemon never sends `conn.hello` at all — and it describes a
+ * device, not a task. This field is task-shaped: it shares a lifecycle with
+ * the task↔runtime binding the claim itself establishes, so a control gate
+ * (`steerTask()`, `packages/server`'s `hub.ts`) can key off it and stay
+ * correct across reconnects, adapter-set changes, and transports. Plain
+ * optional property on this already-tolerant `z.object()`, exactly like
+ * `runtime` above: an old daemon simply omits it, and a consumer that gates on
+ * it must fail closed on absence rather than assume a default.
+ */
+export declare const TaskClaimPayloadSchema: 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>;
+export type TaskClaimPayload = z.infer<typeof TaskClaimPayloadSchema>;
+/**
+ * daemon -> server: explicit `Claimed -> Running` transition (M1 gap #2).
+ * A `task.claim` no longer implies the task started running; the daemon
+ * sends this once it has actually started the runtime session for the task.
+ */
+export declare const TaskStartedPayloadSchema: z.ZodObject<{}, z.core.$strip>;
+export type TaskStartedPayload = z.infer<typeof TaskStartedPayloadSchema>;
+/**
+ * daemon -> server: decline an offer *before* claiming it (M1 gap #5) — e.g.
+ * no compatible/available runtime, or the offered policy exceeds this
+ * device's ceiling. Fail-closed rejections must use this instead of silently
+ * dropping the offer.
+ *
+ * Decision (see docs/protocol.md "Declined vs. Failed" for the full
+ * 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
+ * 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
+ * terminal-state consumer into "Failed or Declined, handle both".
+ */
+export declare const TaskDeclinePayloadSchema: z.ZodObject<{
+    reason: z.ZodString;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TaskDeclinePayload = z.infer<typeof TaskDeclinePayloadSchema>;
+/**
+ * daemon -> server: batch of normalized agent events.
+ *
+ * `events` elements are known-or-unknown (`AgentEventOrUnknownSchema` —
+ * `agent-event.ts`), not bare `AgentEventSchema`: pre-freeze, an unrecognized
+ * event `type` must not fail the whole batch, since a peer running a newer
+ * minor version may have emitted an additive event variant this schema
+ * doesn't know about yet. See `agent-event.ts` for the full rationale and
+ * `partitionAgentEvents`/`isKnownAgentEvent` for how consumers should skip
+ * unknowns instead of choking on them.
+ */
+export declare const TaskProgressPayloadSchema: 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>;
+export type TaskProgressPayload = z.infer<typeof TaskProgressPayloadSchema>;
+/** daemon -> server: an artifact produced by the task, inline or by blob ref. */
+export declare const TaskArtifactPayloadSchema: 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>;
+export type TaskArtifactPayload = z.infer<typeof TaskArtifactPayloadSchema>;
+/**
+ * daemon -> server: task is blocked on an out-of-band approval.
+ *
+ * `approvalId` (M5, additive-minor — docs/protocol.md §5.3): the daemon's own
+ * locally-generated identity for THIS SPECIFIC pending approval
+ * (`ApprovalRegistry`, `packages/client`'s `approvals.ts`) — included
+ * unconditionally by an M5+ daemon, regardless of whether the connected
+ * server has advertised the `approval-targeting` capability flag
+ * (`version.ts`; see that flag's own doc comment for why no emission gating
+ * is needed here — it's a tolerant `z.object()` field, so an older server
+ * simply ignores it). Optional purely for wire tolerance with a pre-M5
+ * daemon build that never set it at all: a server that never learns an id
+ * for a task's current approval can't target a later `approve`/`reject`
+ * decision and falls back to resolving "whichever approval is currently
+ * pending" — the same behavior every server had before this field existed.
+ */
+export declare const TaskAwaitApprovalPayloadSchema: z.ZodObject<{
+    summary: z.ZodString;
+    approvalId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskAwaitApprovalPayload = z.infer<typeof TaskAwaitApprovalPayloadSchema>;
+/** daemon -> server: task finished successfully. */
+export declare const TaskCompletePayloadSchema: 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>;
+export type TaskCompletePayload = z.infer<typeof TaskCompletePayloadSchema>;
+/** daemon -> server: task failed. */
+export declare const TaskFailPayloadSchema: z.ZodObject<{
+    reason: z.ZodString;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TaskFailPayload = z.infer<typeof TaskFailPayloadSchema>;
+/**
+ * daemon -> server: task ended in the `Cancelled` state (M1 gap #6) — either
+ * in response to a server-sent `task.cancel`, or a cancellation the daemon
+ * observed/decided locally (e.g. a local stop action) that the server didn't
+ * initiate. This is the canonical way to report a `Cancelled` outcome; it
+ * supersedes the M0 convention of `task.fail({ reason: 'cancelled' })`.
+ *
+ * This is deliberately its own message rather than folded into `task.fail`
+ * (decision: prefer the explicit message — see docs/protocol.md) because
+ * `Cancelled` is semantically distinct from `Failed`: one is an intentional
+ * stop, the other an error. Overloading `task.fail` with a magic
+ * `reason: 'cancelled'` string convention hid that distinction on the wire.
+ *
+ * Dual-purpose on receipt: if the server already moved its own record to
+ * `Cancelled` (it initiated the cancel — M1 gap #3's "server state is
+ * authoritative" rule), this is an idempotent no-op ack. If the server
+ * hasn't yet (a locally-observed cancellation), this is the authoritative
+ * trigger that moves `Claimed`/`Running`/`AwaitApproval -> Cancelled`.
+ */
+export declare const TaskCancelledPayloadSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskCancelledPayload = z.infer<typeof TaskCancelledPayloadSchema>;
+/**
+ * daemon -> server: a pending `task.await_approval` was resolved entirely
+ * LOCALLY on the device — the local control-socket `approvals.resolve` RPC,
+ * a fail-closed `requestApproval` timeout, or a fail-closed eviction/finish
+ * rejection (see `packages/client`'s `task-runner.ts`/`approvals.ts`) —
+ * *without* a wire `task.approve`/`task.reject` ever having been exchanged
+ * for it. This is the additive-minor answer to a gap the M4 Phase 3 approval
+ * work left open (see the "Deferred additive candidate" note this schema
+ * resolves, `docs/protocol.md`): today the server only learns of a local
+ * resolution IMPLICITLY, after the fact, once the daemon's next
+ * `task.progress`/`task.artifact`/`task.complete` proves the task already
+ * moved on (`ConnectionHub.resumeIfImplicitlyApproved`,
+ * `packages/server/src/hub.ts`) — a window in which a SaaS-side
+ * `TaskHandle.approve()`/`.reject()` can independently decide (and win) the
+ * server's own authoritative record before that evidence ever arrives. This
+ * message lets the daemon report the local resolution explicitly and
+ * immediately, narrowing that window from "until the next progress message"
+ * down to ordinary network latency; the implicit-inference path stays as-is,
+ * unconditionally, as the compatibility fallback for an old server that
+ * never advertises the `approval_resolved` capability flag (`version.ts`) or
+ * an old daemon that predates this message entirely.
+ *
+ * Observability-class tolerance applies (not control/security — see the
+ * freeze rule's asymmetry, `docs/protocol.md`): this is a daemon reporting
+ * what it already did locally, not a payload that grants/denies anything on
+ * its own — the receiving server's own state machine (`TASK_TRANSITIONS`,
+ * `task-state.ts`) is still what decides whether the reported resolution is
+ * legal to apply. Plain `z.object()` (not `.strict()`), same as every other
+ * non-control payload in this file.
+ *
+ * `resolvedBy` is a single-value enum (`'local'`) rather than a bare string:
+ * deliberately future-proof (a later wave could add e.g. `'operator-cli'` as
+ * a DISTINCT value without a version bump — a new enum member is additive,
+ * same as a new message type or capability flag), while still being a closed,
+ * typed shape today rather than an open string a typo could silently widen.
+ */
+export declare const TaskApprovalResolvedPayloadSchema: z.ZodObject<{
+    approvalId: z.ZodString;
+    decision: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+    }>;
+    resolvedBy: z.ZodEnum<{
+        local: "local";
+    }>;
+    at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type TaskApprovalResolvedPayload = z.infer<typeof TaskApprovalResolvedPayloadSchema>;
+export declare const MESSAGE_PAYLOAD_SCHEMAS: {
+    readonly 'conn.hello': 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>;
+    readonly 'conn.ack': z.ZodObject<{
+        protocolVersion: z.ZodNumber;
+        capabilities: z.ZodArray<z.ZodString>;
+        serverTime: z.ZodISODateTime;
+    }, z.core.$strip>;
+    readonly 'task.offer': 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>;
+    readonly 'task.approve': z.ZodObject<{
+        approvalId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'task.reject': z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+        approvalId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'task.cancel': z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'task.steer': z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip>;
+    readonly 'task.claim': 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>;
+    readonly 'task.started': z.ZodObject<{}, z.core.$strip>;
+    readonly 'task.decline': z.ZodObject<{
+        reason: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly 'task.progress': 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>;
+    readonly 'task.artifact': 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>;
+    readonly 'task.await_approval': z.ZodObject<{
+        summary: z.ZodString;
+        approvalId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'task.complete': 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>;
+    readonly 'task.fail': z.ZodObject<{
+        reason: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly 'task.cancelled': z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'task.approval_resolved': z.ZodObject<{
+        approvalId: z.ZodString;
+        decision: z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+        }>;
+        resolvedBy: z.ZodEnum<{
+            local: "local";
+        }>;
+        at: z.ZodISODateTime;
+    }, z.core.$strip>;
+};
+export type MessageType = keyof typeof MESSAGE_PAYLOAD_SCHEMAS;
+export declare const MESSAGE_TYPES: MessageType[];
+/**
+ * Message types the server sends to the daemon. Used by {@link EnvelopeSchema}
+ * (`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"];
+/**
+ * Message types the daemon sends to the server — the flip side of
+ * {@link SERVER_TO_DAEMON_TYPES}. `conn.hello` is deliberately excluded: it's
+ * only ever valid as the first frame of a WS handshake (`ws-server.ts`), not
+ * as ongoing inbound traffic through `ConnectionHub.handleInbound`.
+ *
+ * Used by `handleInbound` (`@byok-sdk/server`'s `hub.ts`) as the type-allow gate
+ * for every inbound envelope, WS and `POST /byok/messages` alike (finding
+ * P2): a `type` outside this set — a server -> daemon type arriving inbound,
+ * or anything unrecognized — is rejected before it's dispatched to any
+ * handler or counted `accepted` on the `/byok/messages` wire.
+ */
+export declare const DAEMON_TO_SERVER_TYPES: readonly ["task.claim", "task.started", "task.decline", "task.progress", "task.artifact", "task.await_approval", "task.complete", "task.fail", "task.cancelled", "task.approval_resolved"];

package/dist/permission.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export declare const PERMISSION_MODES: readonly ['auto', 'confirm', 'readonly', 'plan'];
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+/**
+ * Policy the server proposes for a task. The daemon/runtime adapter maps this
+ * onto the concrete runtime's flags; anything that can't be expressed exactly
+ * must fail closed (deny) rather than silently widen the grant.
+ *
+ * `.strict()`: this is control/security data, so per the freeze rule's
+ * observability-vs-control asymmetry (docs/protocol.md "Freeze rule") an
+ * unrecognized field must be REJECTED, not silently stripped-and-ignored the
+ * way an ordinary payload's unknown field is (plain `z.object()`'s default
+ * behavior). Without `.strict()`, a policy carrying a future constraint this
+ * schema doesn't know about yet would parse successfully with that
+ * constraint silently discarded — exactly the silent-widening failure mode
+ * this type's own doc comment above warns against, since a stripped
+ * constraint is indistinguishable from a constraint that was never sent.
+ *
+ * Consequence: adding a new field to this schema post-freeze is therefore a
+ * BREAKING change requiring a `PROTOCOL_VERSION` bump — unlike the general
+ * "a new optional field on an existing payload is non-breaking" rule the
+ * freeze rule grants every other schema. That's intentional: a new
+ * security/control constraint must force a conscious version bump so an
+ * unupgraded peer can never silently ignore it, rather than being added the
+ * same low-friction way a harmless observability field would be.
+ */
+export declare const PermissionPolicySchema: 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>;
+export type PermissionPolicy = z.infer<typeof PermissionPolicySchema>;