@byok-sdk/server 0.5.0 → 0.6.1

package/dist/hub.d.ts

@@ -3,7 +3,7 @@ import { type Envelope, type RuntimeId, type RuntimeInfo, type TaskState, type T
 import type { DeviceRegistry } from './auth';
 import { RateLimiter } from './rate-limiter';
 import type { TaskStore } from './task-store';
-import type { ByokServerEvent, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
+import type { ByokServerEvent, AgentContentReadRequest, AgentEgressReceipt, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
 /**
  * The connection hub: tracks each device's live transport (WS or long-poll —
  * never both at once, see {@link takeOverAsLongPoll}), routes `dispatch()`'d
@@ -18,7 +18,8 @@ import type { ByokServerEvent, DispatchInput, HubStats, MachineInfo, TaskHandle,
  * transports (`ws-server.ts`'s WS message handler, `http.ts`'s
  * `POST /byok/messages`) call instead of reaching into per-type handlers
  * directly. Runs, in order: (1) type-allow — only `DAEMON_TO_SERVER_TYPES`
- * may pass, a server -> daemon type arriving inbound is rejected (P2); (2)
+ * plus the authenticated long-poll `conn.hello` snapshot may pass, a server
+ * -> daemon type arriving inbound is rejected (P2); (2)
  * ownership (N2) — an envelope for a task already owned by a *different*
  * device is dropped and logged, never force-failed (force-failing on an
  * authz mismatch would let an attacker who merely guesses a `taskId` kill
@@ -169,15 +170,11 @@ export type SteerRejectionCode = 'steer_unsupported_runtime' | 'task_not_running
  * Two reasons, either sufficient. First, scope: connection-level data is
  * discovery describing a daemon BUILD, not the per-runtime, per-task,
  * claim-time truth this gate needs — conflating the two is the original bug.
- * Second, reach: `conn.hello` is transport-shaped. A long-poll-only daemon
- * never sends one (sole sender: `ws-transport.ts:192`, `packages/client`), so
- * a connection-sourced snapshot is permanently `undefined` for an entire
- * transport and a fail-closed gate reading it disables steer across that whole
- * deployment surface — a regression, not a safety property. The claim, by
- * contrast, is the message that establishes the task↔runtime binding on every
- * transport, so the gate's input now shares a lifecycle with the thing it
- * judges. Adding a connection-level fallback here would restore both defects
- * at once and is what this design exists to forbid.
+ * Second, lifecycle: the authenticated `conn.hello` snapshot on either
+ * transport describes the device build, while the claim establishes the
+ * exact task↔runtime binding. Only the latter shares a lifecycle with the
+ * thing this gate judges. Adding a connection-level fallback here would
+ * restore the scope defect and is what this design exists to forbid.
  */
 export declare class SteerRejectedError extends Error {
     readonly taskId: string;
@@ -214,6 +211,12 @@ export declare class ConnectionHub {
     private readonly longPollWaiters;
     private readonly runtimes;
     private readonly serverEvents;
+    /** First-write-wins reliable facts; the reference composition's bounded in-memory readback. */
+    private readonly agentEgressReceipts;
+    /** Accepted requests are the authority that later receipts/transfers must echo exactly. */
+    private readonly agentContentReadRequests;
+    /** Content-free explicit-read audit facts keyed by exact authenticated device/request identity. */
+    private readonly agentContentReceipts;
     /**
      * Per-task last-inbound-activity timestamp (epoch ms) — the task-lease
      * reaper's condition (c), see the "task-lease reaper" section below. Reset
@@ -276,7 +279,7 @@ export declare class ConnectionHub {
      * connection this hub never learns capabilities for simply reads back
      * `undefined` from {@link getDeviceCapabilities}.
      */
-    registerConnection(deviceId: string, ws: WebSocket, runtimes: RuntimeInfo[] | undefined, capabilities?: readonly string[], configuredToolsets?: readonly ToolsetId[]): void;
+    registerConnection(deviceId: string, ws: WebSocket, runtimes: RuntimeInfo[] | undefined, capabilities?: readonly string[], configuredToolsets?: readonly ToolsetId[], clientVersion?: string): void;
     sendConnAck(deviceId: string, capabilities: string[]): void;
     /**
      * Reconnection procedure step 3 (§9): redeliver, in `seq` order, every
@@ -338,9 +341,10 @@ export declare class ConnectionHub {
      *    taskStore lookup or dedup bookkeeping. See {@link handleRateLimited}
      *    for what happens on exceed (never a silent drop).
      * 1. **type-allow (P2)** — only {@link DAEMON_TO_SERVER_TYPES} may pass; a
-     *    server -> daemon type (or anything unrecognized, e.g. a stale/future
-     *    `conn.hello` outside the handshake) arriving inbound is rejected
-     *    before it's dispatched or counted accepted.
+     *    server -> daemon type arriving inbound is rejected before it's
+     *    dispatched or counted accepted. `conn.hello` is the one non-task
+     *    exception, and is accepted only from the bearer-authenticated
+     *    long-poll route with an exact device/product/protocol match.
      * 2. **ownership (N2)** — an envelope for a task already owned by a
      *    *different* device is dropped (logged), never force-failed:
      *    force-failing on an authz mismatch would let an attacker who merely
@@ -360,7 +364,19 @@ export declare class ConnectionHub {
      * wire-level success even though no handler ran a second time; only
      * `rejected`/`rate_limited` (gate steps 0-2) are excluded from that count.
      */
-    handleInbound(deviceId: string, envelope: Envelope): 'accepted' | 'duplicate' | 'rejected' | 'rate_limited';
+    handleInbound(deviceId: string, envelope: Envelope, authenticatedProductId?: string): 'accepted' | 'duplicate' | 'rejected' | 'rate_limited';
+    /**
+     * Store before acking. Replays must agree on every identity/cursor/hash
+     * field and receive the original receipt id; a same event id with changed
+     * facts is rejected rather than treated as an update.
+     */
+    private handleAgentEgressReliable;
+    private handleAgentContentReceipt;
+    private sendAgentEgressAck;
+    private sendAgentContentReceiptAck;
+    private agentEgressReceiptKey;
+    /** Record the authenticated long-poll equivalent of the WS opening frame. */
+    private registerLongPollHello;
     /**
      * M4 Phase 4 (part A): `deviceId` just exceeded its inbound-envelope rate
      * limit. Never a silent drop: counts the occurrence
@@ -733,6 +749,8 @@ export declare class ConnectionHub {
     /** Reap one lease-expired task through the exact same TaskStore/canTransition path — and terminal-event emission — as any other `task.fail` (see {@link applyOrFail}). */
     private reapTask;
     dispatch(input: DispatchInput): Promise<TaskHandle>;
+    /** Capability-gated control-plane read request; no request enters the outbox on omission. */
+    requestAgentContentRead(input: AgentContentReadRequest): Promise<void>;
     private buildTaskHandle;
     /** Idempotent: cancelling an already-terminal task is a no-op, not an error. */
     private cancelTask;
@@ -800,8 +818,7 @@ export declare class ConnectionHub {
      * not {@link getDeviceCapabilities}, not `ConnectionState.runtimes`, and
      * with no fallback to either when the snapshot is absent. See
      * {@link SteerRejectedError} for why a connection-sourced input is wrong
-     * both in scope (describes a daemon build, not this task's runtime) and in
-     * reach (absent entirely on long-poll-only daemons).
+     * in scope (it describes a daemon build, not this task's runtime).
      */
     private steerTask;
     private pickFirstConnectedDevice;
@@ -848,6 +865,8 @@ export declare class ConnectionHub {
      * only, never a correctness gate).
      */
     getDeviceCapabilities(deviceId: string): readonly string[] | undefined;
+    private hasDeviceCapabilities;
+    getAgentEgressReceipt(deviceId: string, eventId: string): AgentEgressReceipt | undefined;
     getTask(taskId: string): TaskSnapshot | undefined;
     listTasks(): TaskSnapshot[];
     /**

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import type { Server as HttpServer } from 'node:http';
 import type { Hono } from 'hono';
 import { type TenantId } from './auth';
 import { type PairingCodeClaims, type PairingCodeInfo } from './pairing';
-import type { ByokServerEvent, CreateByokServerOptions, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
-export type { ByokServerEvent, CreateByokServerOptions, DispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
+import type { ByokServerEvent, AgentContentReadRequest, AgentEgressReceipt, CreateByokServerOptions, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
+export type { ByokServerEvent, AgentContentReadRequest, AgentEgressReceipt, CreateByokServerOptions, DispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
 export type { CreateTaskInput, TaskRecord, TaskStore } from './task-store';
 export { IllegalTaskTransitionError, InMemoryTaskStore } from './task-store';
 /**
@@ -60,10 +60,16 @@ export interface ByokServer {
         createPairingCode(claims: PairingCodeClaims): PairingCodeInfo;
     };
     dispatch(input: DispatchInput): Promise<TaskHandle>;
+    /** Enqueue one capability-gated, exact-identity content-read request. */
+    requestAgentContentRead(input: AgentContentReadRequest): Promise<void>;
     tasks: {
         get(taskId: string): TaskSnapshot | undefined;
         list(): TaskSnapshot[];
     };
+    /** Reference-server reliable egress receipt readback. */
+    egress: {
+        get(deviceId: string, eventId: string): AgentEgressReceipt | undefined;
+    };
     machines: {
         list(): MachineInfo[];
     };