@byok-sdk/server 0.6.0 → 0.7.0

package/dist/index.js

@@ -5,7 +5,7 @@ import { mkdir, writeFile, readFile } from 'fs/promises';
 import { mkdtempSync, mkdirSync, existsSync, chmodSync } from 'fs';
 import { tmpdir } from 'os';
 import path, { dirname } from 'path';
-import { CAPABILITY_FLAGS, byokBlobContentPath, canTransition, PROTOCOL_VERSION, encodeEnvelope, DAEMON_TO_SERVER_TYPES, DispatchSelectionSchema, RequiredToolsetsSchema, createEnvelope, TASK_STATES, BYOK_PAIR_PATH, PairRequestSchema, BYOK_CHALLENGE_PATH, ChallengeRequestSchema, BYOK_TOKEN_PATH, TokenRequestSchema, BYOK_BLOBS_PATH, CreateBlobRequestSchema, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, MessagesSendRequestSchema, decodeEnvelope, BYOK_WS_PATH } from '@byok-sdk/protocol';
+import { CAPABILITY_FLAGS, byokBlobContentPath, canTransition, PROTOCOL_VERSION, encodeEnvelope, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, AgentRefSchema, AgentEgressPolicySchema, DispatchSelectionSchema, RequiredToolsetsSchema, AgentContentReadPayloadSchema, createEnvelope, TASK_STATES, BYOK_PAIR_PATH, PairRequestSchema, PairResponseSchema, BYOK_CHALLENGE_PATH, ChallengeRequestSchema, BYOK_TOKEN_PATH, TokenRequestSchema, BYOK_BLOBS_PATH, CreateBlobRequestSchema, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, MessagesSendRequestSchema, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, PairResponseTenantIdSchema, decodeEnvelope, BYOK_WS_PATH } from '@byok-sdk/protocol';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { createRequire } from 'module';
@@ -266,8 +266,6 @@ function generateDeviceId() {
 function generateTaskId() {
   return `task_${randomUUID()}`;
 }
-
-// src/pairing.ts
 var PAIRING_CODE_TTL_MS = 10 * 60 * 1e3;
 var PairingCodeInvalidError = class extends Error {
   constructor(reason) {
@@ -320,13 +318,14 @@ function validatePairingCodeClaims(claims) {
     throw new TypeError("createPairingCode requires { tenantId, productId } claims");
   }
   const { tenantId, productId } = claims;
-  if (typeof tenantId !== "string" || tenantId.length === 0) {
-    throw new TypeError("createPairingCode requires a non-empty tenantId");
+  const tenantResult = PairResponseTenantIdSchema.safeParse(tenantId);
+  if (!tenantResult.success) {
+    throw new TypeError("createPairingCode requires a valid bounded tenantId");
   }
   if (typeof productId !== "string" || productId.length === 0) {
     throw new TypeError("createPairingCode requires a non-empty productId");
   }
-  return { tenantId, productId };
+  return { tenantId: tenantResult.data, productId };
 }
 
 // src/http.ts
@@ -366,12 +365,21 @@ function buildHonoApp(deps) {
       deviceName,
       devicePublicKey
     });
+    const device = deps.devices.get(claims.tenantId, deviceId);
+    if (device === void 0) {
+      throw new Error("paired device row was not persisted");
+    }
     const { accessToken, expiresAt } = await mintAccessToken(deps.tokenSigner, {
-      deviceId,
-      tenantId: claims.tenantId,
-      productId: claims.productId
+      deviceId: device.deviceId,
+      tenantId: device.tenantId,
+      productId: device.productId
+    });
+    const response = PairResponseSchema.parse({
+      deviceId: device.deviceId,
+      accessToken,
+      refreshHint: expiresAt,
+      tenantId: device.tenantId
     });
-    const response = { deviceId, accessToken, refreshHint: expiresAt };
     return c.json(response, 200);
   });
   app.post(BYOK_CHALLENGE_PATH, async (c) => {
@@ -500,7 +508,7 @@ function buildHonoApp(deps) {
     let accepted = 0;
     let rejected = 0;
     for (const envelope of parsed.data.messages) {
-      const result = deps.hub.handleInbound(principal.deviceId, envelope);
+      const result = deps.hub.handleInbound(principal.deviceId, envelope, principal.productId);
       if (result === "rate_limited") {
         return c.json({ error: "rate limit exceeded" }, 429);
       }
@@ -711,6 +719,25 @@ function isTerminal(state) {
 function isClaimedState(state) {
   return state === "Claimed" || state === "Running" || state === "AwaitApproval";
 }
+function sameAgentRef(expected, actual) {
+  return actual?.agentId === expected.agentId && actual.profileRevision === expected.profileRevision;
+}
+function sameAgentEgressPayload(expected, actual) {
+  return sameAgentRef(expected.agentRef, actual.agentRef) && expected.sessionRef === actual.sessionRef && expected.policyRevision === actual.policyRevision && expected.eventId === actual.eventId && expected.cursor === actual.cursor && expected.contentHash === actual.contentHash && expected.byteCount === actual.byteCount && JSON.stringify(expected.payload) === JSON.stringify(actual.payload);
+}
+function matchesContentReadReceipt(request, receipt) {
+  return request.requestId === receipt.requestId && request.surface === receipt.surface && request.actor.kind === receipt.actor.kind && request.actor.id === receipt.actor.id && sameAgentRef(request.agentRef, receipt.agentRef) && request.sessionRef === receipt.sessionRef && request.runtime === receipt.runtime && request.cwd === receipt.cwd && request.policyRevision === receipt.policyRevision && request.target === receipt.target && request.mimeType === receipt.mimeType && request.decodeAs === receipt.decodeAs;
+}
+function contentReadCapability(surface) {
+  switch (surface) {
+    case "workspace":
+      return AGENT_CONTENT_WORKSPACE_READ_CAPABILITY;
+    case "transcript":
+      return AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY;
+    case "artifact":
+      return AGENT_CONTENT_ARTIFACT_READ_CAPABILITY;
+  }
+}
 var UnknownTaskError = class extends Error {
   constructor(taskId) {
     super(`unknown taskId: ${taskId}`);
@@ -788,6 +815,12 @@ var ConnectionHub = class {
   longPollWaiters = /* @__PURE__ */ new Map();
   runtimes = /* @__PURE__ */ new Map();
   serverEvents = new AsyncEventQueue();
+  /** First-write-wins reliable facts; the reference composition's bounded in-memory readback. */
+  agentEgressReceipts = /* @__PURE__ */ new Map();
+  /** Accepted requests are the authority that later receipts/transfers must echo exactly. */
+  agentContentReadRequests = /* @__PURE__ */ new Map();
+  /** Content-free explicit-read audit facts keyed by exact authenticated device/request identity. */
+  agentContentReceipts = /* @__PURE__ */ new Map();
   /**
    * Per-task last-inbound-activity timestamp (epoch ms) — the task-lease
    * reaper's condition (c), see the "task-lease reaper" section below. Reset
@@ -844,12 +877,13 @@ var ConnectionHub = class {
    * connection this hub never learns capabilities for simply reads back
    * `undefined` from {@link getDeviceCapabilities}.
    */
-  registerConnection(deviceId, ws, runtimes, capabilities, configuredToolsets) {
+  registerConnection(deviceId, ws, runtimes, capabilities, configuredToolsets, clientVersion) {
     const at = (/* @__PURE__ */ new Date()).toISOString();
     this.connections.set(deviceId, {
       ws,
       connected: true,
       lastSeen: at,
+      clientVersion,
       runtimes,
       capabilities,
       configuredToolsets
@@ -993,9 +1027,10 @@ var ConnectionHub = class {
    *    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
@@ -1015,16 +1050,34 @@ var ConnectionHub = class {
    * 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, envelope) {
+  handleInbound(deviceId, envelope, authenticatedProductId) {
     this.envelopesInCount++;
     if (!this.rateLimiter.consume(deviceId)) {
       this.handleRateLimited(deviceId);
       return "rate_limited";
     }
     this.rateLimitEventEmittedFor.delete(deviceId);
+    if (envelope.type === "conn.hello") {
+      const payload = envelope.payload;
+      if (authenticatedProductId === void 0 || payload.deviceId !== deviceId || payload.productId !== authenticatedProductId || !payload.protocolVersions.includes(PROTOCOL_VERSION)) {
+        return "rejected";
+      }
+      if (this.checkAndRecordDuplicate(deviceId, envelope.id)) {
+        this.dedupDropCount++;
+        return "duplicate";
+      }
+      this.registerLongPollHello(deviceId, payload);
+      return "accepted";
+    }
     if (!DAEMON_TO_SERVER_TYPES.includes(envelope.type)) {
       return "rejected";
     }
+    if (envelope.type === "agent.egress.reliable") {
+      return this.handleAgentEgressReliable(deviceId, envelope.payload);
+    }
+    if (envelope.type === "agent.content.receipt") {
+      return this.handleAgentContentReceipt(deviceId, envelope.payload);
+    }
     const taskId = envelope.task_id;
     if (taskId === void 0) return "rejected";
     const record = this.taskStore.get(taskId);
@@ -1039,6 +1092,100 @@ var ConnectionHub = class {
     this.dispatchToHandler(deviceId, taskId, envelope);
     return "accepted";
   }
+  /**
+   * 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.
+   */
+  handleAgentEgressReliable(deviceId, payload) {
+    if (!this.hasDeviceCapabilities(deviceId, [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
+      return "rejected";
+    }
+    const key = this.agentEgressReceiptKey(deviceId, payload.eventId);
+    const existing = this.agentEgressReceipts.get(key);
+    if (existing !== void 0) {
+      if (!sameAgentEgressPayload(existing.payload, payload)) return "rejected";
+      this.sendAgentEgressAck(deviceId, existing);
+      this.dedupDropCount++;
+      return "duplicate";
+    }
+    const receipt = {
+      deviceId,
+      payload,
+      receiptId: crypto.randomUUID(),
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.agentEgressReceipts.set(key, receipt);
+    this.sendAgentEgressAck(deviceId, receipt);
+    return "accepted";
+  }
+  handleAgentContentReceipt(deviceId, payload) {
+    const capability = contentReadCapability(payload.surface);
+    if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) return "rejected";
+    if (payload.eventId !== payload.requestId) return "rejected";
+    const key = `${deviceId}\0${payload.requestId}`;
+    const request = this.agentContentReadRequests.get(key);
+    if (request === void 0 || !matchesContentReadReceipt(request, payload)) return "rejected";
+    const existing = this.agentContentReceipts.get(key);
+    if (existing !== void 0) {
+      if (JSON.stringify(existing.payload) !== JSON.stringify(payload)) return "rejected";
+      this.sendAgentContentReceiptAck(deviceId, existing);
+      this.dedupDropCount++;
+      return "duplicate";
+    }
+    const receipt = {
+      deviceId,
+      payload,
+      receiptId: payload.requestId,
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.agentContentReceipts.set(key, receipt);
+    this.sendAgentContentReceiptAck(deviceId, receipt);
+    return "accepted";
+  }
+  sendAgentEgressAck(deviceId, receipt) {
+    this.sendToDevice(
+      deviceId,
+      "agent.egress.ack",
+      {
+        agentRef: receipt.payload.agentRef,
+        sessionRef: receipt.payload.sessionRef,
+        policyRevision: receipt.payload.policyRevision,
+        eventId: receipt.payload.eventId,
+        cursor: receipt.payload.cursor,
+        receiptId: receipt.receiptId
+      },
+      {}
+    );
+  }
+  sendAgentContentReceiptAck(deviceId, receipt) {
+    this.sendToDevice(
+      deviceId,
+      "agent.egress.ack",
+      {
+        agentRef: receipt.payload.agentRef,
+        sessionRef: receipt.payload.sessionRef,
+        policyRevision: receipt.payload.policyRevision,
+        eventId: receipt.payload.eventId,
+        cursor: receipt.payload.cursor,
+        receiptId: receipt.receiptId
+      },
+      {}
+    );
+  }
+  agentEgressReceiptKey(deviceId, eventId) {
+    return `${deviceId}\0${eventId}`;
+  }
+  /** Record the authenticated long-poll equivalent of the WS opening frame. */
+  registerLongPollHello(deviceId, payload) {
+    this.takeOverAsLongPoll(deviceId);
+    const connection = this.connections.get(deviceId);
+    if (!connection) return;
+    connection.runtimes = payload.runtimes;
+    connection.capabilities = payload.capabilities;
+    connection.configuredToolsets = payload.configuredToolsets;
+    connection.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
+  }
   /**
    * M4 Phase 4 (part A): `deviceId` just exceeded its inbound-envelope rate
    * limit. Never a silent drop: counts the occurrence
@@ -1140,7 +1287,7 @@ var ConnectionHub = class {
         this.onStarted(envelope.task_id, envelope.payload);
         return;
       case "task.decline":
-        this.onDecline(envelope.task_id, envelope.payload);
+        this.onDecline(deviceId, envelope.task_id, envelope.payload);
         return;
       case "task.progress":
         this.onProgress(envelope.task_id, envelope.payload);
@@ -1206,6 +1353,14 @@ var ConnectionHub = class {
   onClaim(deviceId, taskId, payload) {
     const record = this.taskStore.get(taskId);
     if (!record) return;
+    if (record.deviceId !== void 0 && record.deviceId !== deviceId) {
+      console.warn(`[byok/server] dropping task.claim for ${taskId}: offered to a different device`);
+      return;
+    }
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.claim AgentRef does not exactly match the offered AgentRef");
+      return;
+    }
     if (record.state === "Claimed" || record.state === "Running") return;
     this.applyOrFail(taskId, "Claimed", {
       deviceId,
@@ -1230,10 +1385,18 @@ var ConnectionHub = class {
    * ever legal from `Offered`; anything else is stale. Ownership is already
    * enforced by {@link handleInbound} (N2) before this runs.
    */
-  onDecline(taskId, payload) {
+  onDecline(deviceId, taskId, payload) {
     const record = this.taskStore.get(taskId);
     if (!record) return;
     if (record.state !== "Offered") return;
+    if (record.deviceId !== void 0 && record.deviceId !== deviceId) {
+      console.warn(`[byok/server] dropping task.decline for ${taskId}: offered to a different device`);
+      return;
+    }
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.decline AgentRef does not exactly match the offered AgentRef");
+      return;
+    }
     this.applyOrFail(taskId, "Failed", {
       result: { state: "Failed", reason: payload.reason, retryable: payload.retryable }
     });
@@ -1283,6 +1446,10 @@ var ConnectionHub = class {
     const record = this.taskStore.get(taskId);
     if (!record) return;
     if (isTerminal(record.state)) return;
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.complete AgentRef does not exactly match the offered AgentRef");
+      return;
+    }
     this.resumeIfImplicitlyApproved(record);
     const result = {
       state: "Complete",
@@ -1306,6 +1473,10 @@ var ConnectionHub = class {
     const record = this.taskStore.get(taskId);
     if (!record) return;
     if (isTerminal(record.state)) return;
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.fail AgentRef does not exactly match the offered AgentRef");
+      return;
+    }
     const result = { state: "Failed", reason: payload.reason, retryable: payload.retryable };
     this.applyOrFail(taskId, "Failed", { result });
   }
@@ -1324,6 +1495,10 @@ var ConnectionHub = class {
     if (!record) return;
     if (record.state === "Cancelled") return;
     if (isTerminal(record.state)) return;
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.cancelled AgentRef does not exactly match the offered AgentRef");
+      return;
+    }
     this.applyOrFail(taskId, "Cancelled", { result: { state: "Cancelled", reason: payload.reason } });
   }
   /**
@@ -1682,14 +1857,35 @@ var ConnectionHub = class {
   // dispatch() and the TaskHandle it returns
   // ---------------------------------------------------------------------
   async dispatch(input) {
+    const agentRef = input.agentRef === void 0 ? void 0 : AgentRefSchema.parse(input.agentRef);
+    const egressPolicy = input.egressPolicy === void 0 ? void 0 : AgentEgressPolicySchema.parse(input.egressPolicy);
     const dispatchSelection = input.dispatchSelection === void 0 ? void 0 : DispatchSelectionSchema.parse(input.dispatchSelection);
     const requiredToolsets = input.requiredToolsets === void 0 ? void 0 : RequiredToolsetsSchema.parse(input.requiredToolsets);
     const deviceId = input.deviceId ?? this.pickFirstConnectedDevice(requiredToolsets);
+    if (agentRef !== void 0 && input.deviceId === void 0) {
+      throw new Error("Agent-bound dispatch requires an explicit deviceId for capability admission");
+    }
+    if (egressPolicy !== void 0 && agentRef === void 0) {
+      throw new Error("Agent egress policy requires an explicit AgentRef; legacy task dispatch cannot consume it");
+    }
+    if (egressPolicy !== void 0 && input.sessionRef === void 0) {
+      throw new Error("Agent egress policy requires an exact sessionRef");
+    }
     if (!deviceId || !this.connections.get(deviceId)?.connected) {
       throw new Error(
         deviceId ? `device ${deviceId} is not connected` : "no connected device to dispatch to (M0 does not queue tasks until a device connects)"
       );
     }
+    if (agentRef !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("agent-home-contract") ?? false)) {
+      throw new Error(
+        `device ${deviceId} did not advertise agent-home-contract capability; refusing Agent-bound dispatch`
+      );
+    }
+    if (egressPolicy !== void 0 && !this.hasDeviceCapabilities(deviceId, [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
+      throw new Error(
+        `device ${deviceId} did not advertise Agent egress policy and reliable acknowledgement capabilities; refusing before enqueue`
+      );
+    }
     if (dispatchSelection !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("dispatch-selection") ?? false)) {
       throw new Error(
         `device ${deviceId} did not advertise dispatch-selection capability; refusing authoritative provider/model dispatch`
@@ -1730,7 +1926,8 @@ var ConnectionHub = class {
       policy,
       requiredToolsets,
       deviceId,
-      sessionRef: input.sessionRef
+      sessionRef: input.sessionRef,
+      agentRef
     });
     const queue = new AsyncEventQueue();
     let resolveResult;
@@ -1747,7 +1944,27 @@ var ConnectionHub = class {
       dispatchSelection,
       sessionRef: input.sessionRef
     };
-    if (requiredToolsets === void 0) {
+    if (agentRef !== void 0 && egressPolicy !== void 0) {
+      this.sendToDevice(
+        deviceId,
+        "task.offer_for_agent_with_egress",
+        {
+          ...commonOffer,
+          sessionRef: input.sessionRef,
+          agentRef,
+          egressPolicy,
+          ...requiredToolsets === void 0 ? {} : { requiredToolsets }
+        },
+        { taskId, sessionRef: input.sessionRef }
+      );
+    } else if (agentRef !== void 0) {
+      this.sendToDevice(
+        deviceId,
+        "task.offer_for_agent",
+        { ...commonOffer, agentRef, ...requiredToolsets === void 0 ? {} : { requiredToolsets } },
+        { taskId, sessionRef: input.sessionRef }
+      );
+    } else if (requiredToolsets === void 0) {
       this.sendToDevice(deviceId, "task.offer", commonOffer, { taskId, sessionRef: input.sessionRef });
     } else {
       this.sendToDevice(
@@ -1759,6 +1976,27 @@ var ConnectionHub = class {
     }
     return this.buildTaskHandle(taskId);
   }
+  /** Capability-gated control-plane read request; no request enters the outbox on omission. */
+  async requestAgentContentRead(input) {
+    const payload = AgentContentReadPayloadSchema.parse(input.payload);
+    const deviceId = input.deviceId;
+    if (!this.connections.get(deviceId)?.connected) {
+      throw new Error(`device ${deviceId} is not connected`);
+    }
+    const capability = contentReadCapability(payload.surface);
+    if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
+      throw new Error(
+        `device ${deviceId} did not advertise ${capability} and reliable acknowledgement support; refusing Agent content read before enqueue`
+      );
+    }
+    const key = `${deviceId}\0${payload.requestId}`;
+    const existing = this.agentContentReadRequests.get(key);
+    if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(payload)) {
+      throw new Error(`Agent content request ${payload.requestId} already exists with a different immutable body`);
+    }
+    this.agentContentReadRequests.set(key, payload);
+    this.sendToDevice(deviceId, "agent.content.read", payload, {});
+  }
   buildTaskHandle(taskId) {
     const hub = this;
     return {
@@ -1887,8 +2125,7 @@ var ConnectionHub = class {
    * 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).
    */
   async steerTask(taskId, text) {
     const record = this.taskStore.get(taskId);
@@ -1941,7 +2178,8 @@ var ConnectionHub = class {
     const envelope = createEnvelope(type, payload, combinedOpts);
     const taskId = opts.taskId;
     const redeliverThroughTerminal = type === "task.cancel" || type === "task.reject";
-    outbox.ring.push({ seq, taskId, envelope, redeliverThroughTerminal });
+    const redeliverWithoutTask = type === "agent.egress.ack" || type === "agent.content.read";
+    outbox.ring.push({ seq, taskId, envelope, redeliverThroughTerminal, redeliverWithoutTask });
     if (outbox.ring.length > OUTBOX_RING_CAPACITY) outbox.ring.shift();
     this.deliverToDevice(deviceId, envelope);
     return envelope;
@@ -1966,7 +2204,7 @@ var ConnectionHub = class {
     const outbox = this.outboxes.get(deviceId);
     if (!outbox) return [];
     return outbox.ring.filter(
-      (entry) => entry.seq > cursor && entry.taskId !== void 0 && (!this.isTaskTerminal(entry.taskId) || entry.redeliverThroughTerminal)
+      (entry) => entry.seq > cursor && (entry.taskId === void 0 ? entry.redeliverWithoutTask === true : !this.isTaskTerminal(entry.taskId) || entry.redeliverThroughTerminal)
     ).map((entry) => entry.envelope);
   }
   isTaskTerminal(taskId) {
@@ -1997,6 +2235,7 @@ var ConnectionHub = class {
         deviceName,
         connected: conn?.connected ?? false,
         lastSeen: conn?.lastSeen,
+        ...conn?.clientVersion === void 0 ? {} : { clientVersion: conn.clientVersion },
         runtimes: conn?.runtimes,
         configuredToolsets: conn?.configuredToolsets ? [...conn.configuredToolsets] : void 0
       };
@@ -2018,6 +2257,13 @@ var ConnectionHub = class {
   getDeviceCapabilities(deviceId) {
     return this.connections.get(deviceId)?.capabilities;
   }
+  hasDeviceCapabilities(deviceId, required) {
+    const advertised = this.getDeviceCapabilities(deviceId);
+    return advertised !== void 0 && required.every((capability) => advertised.includes(capability));
+  }
+  getAgentEgressReceipt(deviceId, eventId) {
+    return this.agentEgressReceipts.get(this.agentEgressReceiptKey(deviceId, eventId));
+  }
   getTask(taskId) {
     return this.taskStore.get(taskId);
   }
@@ -2081,6 +2327,7 @@ var InMemoryTaskStore = class {
       requiredToolsets: input.requiredToolsets,
       deviceId: input.deviceId,
       sessionRef: input.sessionRef,
+      agentRef: input.agentRef,
       createdAt: now,
       updatedAt: now
     };
@@ -2251,7 +2498,8 @@ function handleConnection(ws, principal, deps) {
       ws,
       payload.runtimes,
       payload.capabilities,
-      payload.configuredToolsets
+      payload.configuredToolsets,
+      payload.clientVersion
     );
     deps.hub.sendConnAck(deviceId, SUPPORTED_CAPABILITIES);
     if (payload.cursor !== void 0) {
@@ -2365,6 +2613,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   policy_json         TEXT NOT NULL,
   device_id           TEXT,
   session_ref         TEXT,
+  agent_ref_json      TEXT,
   created_at          TEXT NOT NULL,
   updated_at          TEXT NOT NULL,
   result_json         TEXT,
@@ -2385,7 +2634,8 @@ var ADDITIVE_COLUMNS = [
   {
     name: "claimed_runtime_capabilities_json",
     ddl: "ALTER TABLE tasks ADD COLUMN claimed_runtime_capabilities_json TEXT"
-  }
+  },
+  { name: "agent_ref_json", ddl: "ALTER TABLE tasks ADD COLUMN agent_ref_json TEXT" }
 ];
 function currentTaskColumns(db) {
   return new Set(db.prepare("PRAGMA table_info(tasks)").all().map((c) => c.name));
@@ -2411,6 +2661,7 @@ function rowToRecord(row) {
   const resultJson = row.result_json;
   const requiredToolsetsJson = row.required_toolsets_json;
   const claimedRuntimeCapabilitiesJson = row.claimed_runtime_capabilities_json;
+  const agentRefJson = row.agent_ref_json;
   return {
     taskId: row.task_id,
     state: row.state,
@@ -2420,6 +2671,7 @@ function rowToRecord(row) {
     policy: JSON.parse(row.policy_json),
     deviceId: row.device_id ?? void 0,
     sessionRef: row.session_ref ?? void 0,
+    agentRef: agentRefJson ? JSON.parse(agentRefJson) : void 0,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
     result: resultJson ? JSON.parse(resultJson) : void 0,
@@ -2444,13 +2696,13 @@ var SqliteTaskStore = class {
       secureSqliteFilePermissions(opts.path);
       this.insertStmt = this.db.prepare(
         `INSERT INTO tasks
-           (task_id, state, instruction, runtime, required_toolsets_json, policy_json, device_id, session_ref, created_at, updated_at, result_json)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+           (task_id, state, instruction, runtime, required_toolsets_json, policy_json, device_id, session_ref, agent_ref_json, created_at, updated_at, result_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       );
       this.updateStmt = this.db.prepare(
         `UPDATE tasks SET
            state = ?, instruction = ?, runtime = ?, required_toolsets_json = ?, policy_json = ?, device_id = ?,
-           session_ref = ?, created_at = ?, updated_at = ?, result_json = ?, pending_approval_id = ?,
+           session_ref = ?, agent_ref_json = ?, created_at = ?, updated_at = ?, result_json = ?, pending_approval_id = ?,
            claimed_runtime = ?, claimed_runtime_capabilities_json = ?
          WHERE task_id = ? AND state = ?`
       );
@@ -2478,6 +2730,7 @@ var SqliteTaskStore = class {
       policy: input.policy,
       deviceId: input.deviceId,
       sessionRef: input.sessionRef,
+      agentRef: input.agentRef,
       createdAt: now,
       updatedAt: now
     };
@@ -2490,6 +2743,7 @@ var SqliteTaskStore = class {
       JSON.stringify(record.policy),
       record.deviceId ?? null,
       record.sessionRef ?? null,
+      record.agentRef ? JSON.stringify(record.agentRef) : null,
       record.createdAt,
       record.updatedAt,
       record.result ? JSON.stringify(record.result) : null
@@ -2548,6 +2802,7 @@ var SqliteTaskStore = class {
         JSON.stringify(updated.policy),
         updated.deviceId ?? null,
         updated.sessionRef ?? null,
+        updated.agentRef ? JSON.stringify(updated.agentRef) : null,
         updated.createdAt,
         updated.updatedAt,
         updated.result ? JSON.stringify(updated.result) : null,
@@ -2780,10 +3035,14 @@ function createByokServer(opts) {
       createPairingCode: (claims) => pairing.createPairingCode(claims)
     },
     dispatch: (input) => hub.dispatch(input),
+    requestAgentContentRead: (input) => hub.requestAgentContentRead(input),
     tasks: {
       get: (taskId) => hub.getTask(taskId),
       list: () => hub.listTasks()
     },
+    egress: {
+      get: (deviceId, eventId) => hub.getAgentEgressReceipt(deviceId, eventId)
+    },
     machines: {
       list: () => hub.listMachines()
     },