@byok-sdk/protocol 0.30.0 → 0.30.2

package/dist/messages.d.ts

@@ -329,15 +329,19 @@ export declare const AgentHomeAccessSchema: z.ZodLiteral<"memory-reader">;
 export type AgentHomeAccess = z.infer<typeof AgentHomeAccessSchema>;
 /**
  * The `agentMemory` of an ordinary Agent offer: the prepared modes plus
- * `read-if-admitted`. That value runs as `read` when the daemon admits the
- * memory MCP and as `none` when it does not. A host sends it only to a device
- * that advertises `agent-memory-read-if-admitted`. Prepared offers refuse it.
+ * `read-if-admitted` and `read-write-if-admitted`. When the daemon admits the
+ * memory MCP they run as `read` and `read-write`; when it does not, both run as
+ * `none`. A host sends each only to a device that advertises
+ * `agent-memory-read-if-admitted` or `agent-memory-read-write-if-admitted`. A
+ * `memory-reader` Attempt cannot select `read-write-if-admitted`. Prepared
+ * offers refuse both.
  */
 export declare const AgentMemorySelectionSchema: z.ZodEnum<{
     none: "none";
     read: "read";
     "read-if-admitted": "read-if-admitted";
     "read-write": "read-write";
+    "read-write-if-admitted": "read-write-if-admitted";
 }>;
 export type AgentMemorySelection = z.infer<typeof AgentMemorySelectionSchema>;
 /**
@@ -372,6 +376,7 @@ export declare const TaskOfferForAgentPayloadSchema: z.ZodObject<{
         read: "read";
         "read-if-admitted": "read-if-admitted";
         "read-write": "read-write";
+        "read-write-if-admitted": "read-write-if-admitted";
     }>>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
@@ -447,6 +452,7 @@ export declare const TaskOfferForAgentWithEgressPayloadSchema: z.ZodObject<{
         read: "read";
         "read-if-admitted": "read-if-admitted";
         "read-write": "read-write";
+        "read-write-if-admitted": "read-write-if-admitted";
     }>>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
@@ -559,6 +565,7 @@ export declare const TaskOfferForAgentWithEgressFreshPayloadSchema: z.ZodObject<
         read: "read";
         "read-if-admitted": "read-if-admitted";
         "read-write": "read-write";
+        "read-write-if-admitted": "read-write-if-admitted";
     }>>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
@@ -1718,6 +1725,48 @@ export declare const TaskCompletePayloadSchema: z.ZodObject<{
     }, z.core.$strict>], "outcome">>;
 }, z.core.$strip>;
 export type TaskCompletePayload = z.infer<typeof TaskCompletePayloadSchema>;
+/** A closed runtime failure class (#869). `unknown` means the runtime gave no structured evidence. */
+export declare const RuntimeFailureClassSchema: z.ZodEnum<{
+    auth: "auth";
+    billing: "billing";
+    input_too_large: "input_too_large";
+    invalid_request: "invalid_request";
+    limit_reached: "limit_reached";
+    model_unavailable: "model_unavailable";
+    output_schema: "output_schema";
+    overloaded: "overloaded";
+    provider: "provider";
+    quota: "quota";
+    rate_limited: "rate_limited";
+    runtime_exited: "runtime_exited";
+    unknown: "unknown";
+}>;
+export type RuntimeFailureClass = z.infer<typeof RuntimeFailureClassSchema>;
+/**
+ * The machine-readable failure of a `task.fail` (#869); `reason` stays display
+ * text. `resetsAt` (ISO 8601 UTC) exists only on `quota`, and only when the
+ * runtime reported when the limit resets.
+ */
+export declare const TaskFailureSchema: z.ZodUnion<readonly [z.ZodObject<{
+    class: z.ZodLiteral<"quota">;
+    resetsAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>, z.ZodObject<{
+    class: z.ZodEnum<{
+        auth: "auth";
+        billing: "billing";
+        input_too_large: "input_too_large";
+        invalid_request: "invalid_request";
+        limit_reached: "limit_reached";
+        model_unavailable: "model_unavailable";
+        output_schema: "output_schema";
+        overloaded: "overloaded";
+        provider: "provider";
+        rate_limited: "rate_limited";
+        runtime_exited: "runtime_exited";
+        unknown: "unknown";
+    }>;
+}, z.core.$strict>]>;
+export type TaskFailure = z.infer<typeof TaskFailureSchema>;
 /** daemon -> server: task failed. */
 export declare const TaskFailPayloadSchema: z.ZodObject<{
     sealed: z.ZodOptional<z.ZodNever>;
@@ -1729,6 +1778,25 @@ export declare const TaskFailPayloadSchema: z.ZodObject<{
     harnessId: z.ZodOptional<z.ZodString>;
     reason: z.ZodString;
     retryable: z.ZodOptional<z.ZodBoolean>;
+    failure: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        class: z.ZodLiteral<"quota">;
+        resetsAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>, z.ZodObject<{
+        class: z.ZodEnum<{
+            auth: "auth";
+            billing: "billing";
+            input_too_large: "input_too_large";
+            invalid_request: "invalid_request";
+            limit_reached: "limit_reached";
+            model_unavailable: "model_unavailable";
+            output_schema: "output_schema";
+            overloaded: "overloaded";
+            provider: "provider";
+            rate_limited: "rate_limited";
+            runtime_exited: "runtime_exited";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>]>>;
     usage: z.ZodOptional<z.ZodObject<{
         runtime: z.ZodEnum<{
             claude: "claude";
@@ -1839,8 +1907,8 @@ export type TaskCancelledPayload = z.infer<typeof TaskCancelledPayloadSchema>;
  * 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
+ * moved on (the `relay.onTaskActivity` hook in
+ * `packages/server/src/index.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
@@ -2059,6 +2127,7 @@ export declare const TaskOfferForAgentSealedPayloadSchema: z.ZodObject<{
         read: "read";
         "read-if-admitted": "read-if-admitted";
         "read-write": "read-write";
+        "read-write-if-admitted": "read-write-if-admitted";
     }>>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
@@ -2162,6 +2231,7 @@ export declare const TaskOfferForAgentWithEgressSealedPayloadSchema: z.ZodObject
         read: "read";
         "read-if-admitted": "read-if-admitted";
         "read-write": "read-write";
+        "read-write-if-admitted": "read-write-if-admitted";
     }>>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
@@ -2304,6 +2374,7 @@ export declare const TaskOfferForAgentWithEgressFreshSealedPayloadSchema: z.ZodO
         read: "read";
         "read-if-admitted": "read-if-admitted";
         "read-write": "read-write";
+        "read-write-if-admitted": "read-write-if-admitted";
     }>>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
@@ -2549,6 +2620,25 @@ export declare const TaskFailSealedPayloadSchema: z.ZodObject<{
     }, z.core.$strict>>;
     harnessId: z.ZodOptional<z.ZodString>;
     retryable: z.ZodOptional<z.ZodBoolean>;
+    failure: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        class: z.ZodLiteral<"quota">;
+        resetsAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>, z.ZodObject<{
+        class: z.ZodEnum<{
+            auth: "auth";
+            billing: "billing";
+            input_too_large: "input_too_large";
+            invalid_request: "invalid_request";
+            limit_reached: "limit_reached";
+            model_unavailable: "model_unavailable";
+            output_schema: "output_schema";
+            overloaded: "overloaded";
+            provider: "provider";
+            rate_limited: "rate_limited";
+            runtime_exited: "runtime_exited";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>]>>;
     usage: z.ZodOptional<z.ZodObject<{
         runtime: z.ZodEnum<{
             claude: "claude";
@@ -2905,12 +2995,12 @@ export declare const MESSAGE_TYPES: MessageType[];
 export declare const SERVER_TO_DAEMON_TYPES: readonly ["conn.ack", "task.offer", "task.offer_with_toolsets", "task.offer_for_agent", "task.offer_for_agent_with_egress", "task.offer_for_agent_with_egress_fresh", "task.offer_prepared", "agent.egress.ack", "agent.message.disposition", "agent.content.read", "agent.home.projection", "agent.input.preparation", "provider.provisioning.available", "agent.memory.intent.available", "task.approve", "task.reject", "task.cancel", "task.steer", "task.offer_sealed", "task.offer_with_toolsets_sealed", "task.offer_for_agent_sealed", "task.offer_for_agent_with_egress_sealed", "task.offer_for_agent_with_egress_fresh_sealed", "task.steer_sealed", "e2ee.key_package.available"];
 /**
  * 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`.
+ * {@link SERVER_TO_DAEMON_TYPES}. `conn.hello` is deliberately excluded: the
+ * inbound gate handles a bearer-authenticated `conn.hello` as a capability
+ * snapshot on its own, before the type-allow check.
  *
- * 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
+ * Used by `handleInboundEnvelope` (`@byok-sdk/cloud`'s `inbound.ts`) as the
+ * type-allow gate for every inbound `POST /byok/messages` envelope (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.

package/dist/sealed-split-table.d.ts

@@ -58,6 +58,12 @@ export interface SealedSplitEntry {
     readonly limits?: {
         readonly [field: string]: number;
     };
+    /**
+     * The sealed form carries inline ciphertext only, never `ciphertextRef`
+     * (decision 12e). The Host keeps it in a tail row that expires, so it holds
+     * no blob for it. The schema does not check this; the Host and the device do.
+     */
+    readonly inlineOnly?: true;
 }
 /**
  * The split table (design §8.3): each sealed message type, the plaintext type
@@ -146,6 +152,7 @@ export declare const SEALED_SPLIT_TABLE: Readonly<{
         readonly digests: {
             readonly 'events[].spill.blob.contentHash': 'sealed';
         };
+        readonly inlineOnly: true;
     };
     readonly 'task.artifact_sealed': {
         readonly plainType: 'task.artifact';
@@ -167,6 +174,7 @@ export declare const SEALED_SPLIT_TABLE: Readonly<{
         readonly moved: readonly ["summary"];
         readonly forbidden: readonly [];
         readonly digests: {};
+        readonly inlineOnly: true;
     };
 }>;
 export type SealedMessageType = keyof typeof SEALED_SPLIT_TABLE;

package/dist/version.d.ts

@@ -43,9 +43,10 @@ export declare const STRICT_AGENT_ONLY_CAPABILITY: 'strict-agent-only';
  */
 export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
 /**
- * Capability flags exchanged during the connection handshake (`conn.hello` /
- * `conn.ack`). Additional flags may be introduced without a protocol version
- * bump; unrecognized flags must be ignored by both sides.
+ * Capability flags. The daemon sends its flags in `conn.hello`; the server
+ * sends its own on every long-poll response (`EventsPollResponse`). Additional
+ * flags may be introduced without a protocol version bump; unrecognized flags
+ * must be ignored by both sides.
  *
  * `interactive-approval` is RESERVED as of this addition: it gates the
  * (currently unexercised) approval seam — a server must not route an
@@ -56,11 +57,10 @@ export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
  * `approval_resolved` (additive-minor): a SERVER-advertised flag meaning
  * "I understand the `task.approval_resolved` message" (`messages.ts`). This
  * is the N/N-1 answer for that new daemon -> server message: an old server's
- * `CAPABILITY_FLAGS`/`conn.ack.capabilities` never includes it, so a new
- * daemon talking to an old server never sends `task.approval_resolved` at
- * all (see `packages/client`'s `task-runner.ts`) and falls back to the
- * pre-existing implicit-resume inference
- * (`ConnectionHub.resumeIfImplicitlyApproved`, `packages/server/src/hub.ts`)
+ * advertised capabilities never include it, so a new daemon talking to an old
+ * server never sends `task.approval_resolved` at all (see `packages/client`'s
+ * `task-runner.ts`) and falls back to the pre-existing implicit-resume inference
+ * (the `relay.onTaskActivity` hook in `packages/server/src/index.ts`)
  * unconditionally, exactly as before this flag existed. Unlike
  * `interactive-approval`, this one IS exercised the moment both sides
  * support it — there is no reserved/dormant period for it.
@@ -77,13 +77,14 @@ export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
  * by FIELD PRESENCE on the specific message at hand (does this particular
  * `task.approve`/`task.reject`/`onApprovalResolved` payload carry an
  * `approvalId`, and does a stored one exist to compare it against?), never
- * by checking this flag -- see `ConnectionHub.approveTask`/`rejectTask`/
- * `onApprovalResolved` and `TaskRunner.handleApprove`/`handleReject`
- * (`packages/client`'s `task-runner.ts`). This flag exists only so each side
- * can advertise, and an embedder/operator can observe (`ConnectionHub.
- * getDeviceCapabilities`), whether the OTHER side is new enough to
- * participate in targeting at all -- the same N/N-1-safe shape as every
- * other flag here, just consumed for observability instead of gating.
+ * by checking this flag -- see `approveTask`/`rejectTask` (`@byok-sdk/cloud`)
+ * and `TaskRunner.handleApprove`/`handleReject` (`packages/client`'s
+ * `task-runner.ts`). This flag exists only so each side can advertise
+ * whether the OTHER side is new enough to participate in targeting at all (an
+ * embedder could observe it through the old
+ * reference server's `ConnectionHub.getDeviceCapabilities`; `@byok-sdk/server`
+ * now reads it only internally) -- the same N/N-1-safe shape as every other
+ * flag here, just consumed for observability instead of gating.
  */
 /**
  * `dispatch-selection` (additive-minor) is a correctness gate for the
@@ -100,5 +101,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', '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", "agent-memory-selection", "agent-memory-read-if-admitted", 'agent-message-draft', "sealed-payload-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", "agent-memory-selection", "agent-memory-read-if-admitted", "agent-memory-read-write-if-admitted", 'agent-message-draft', "sealed-payload-v1", "sealed-output-ciphertext-ref", "runtime-failure-class"];
 export type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];

package/dist/wire-additions.d.ts

@@ -8,7 +8,8 @@
  *
  * - `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
+ *   carries the field (and, with `value`, when the field equals it); a
+ *   dotted field names a nested field, for example `sealed.ciphertextRef`. 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

package/package.json

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