@byok-sdk/server 0.8.0 → 0.9.0-rc.1

package/dist/hub.d.ts

@@ -1,5 +1,5 @@
 import type { WebSocket } from 'ws';
-import { type Envelope, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionReadback, type RuntimeId, type RuntimeInfo, type TaskState, type ToolsetId } from '@byok-sdk/protocol';
+import { type Envelope, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionReadback, type RuntimeId, type RuntimeInfo, type TaskState, type ToolsetId } from '@byok-sdk/protocol';
 import type { DeviceRegistry } from './auth';
 import { RateLimiter } from './rate-limiter';
 import type { TaskStore } from './task-store';
@@ -209,6 +209,7 @@ export declare class ConnectionHub {
      * working unchanged.
      */
     private readonly rateLimiter;
+    private readonly agentMessage?;
     private readonly connections;
     private readonly outboxes;
     /** Idempotency window per device (N3) — recent inbound envelope ids, capped at {@link DEDUP_RING_CAPACITY}. */
@@ -218,6 +219,9 @@ export declare class ConnectionHub {
     private readonly serverEvents;
     /** First-write-wins reliable facts; the reference composition's bounded in-memory readback. */
     private readonly agentEgressReceipts;
+    private readonly agentMessageRequirements;
+    private readonly agentMessageReceipts;
+    private readonly agentMessageTaskPayloads;
     /** 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. */
@@ -267,7 +271,17 @@ export declare class ConnectionHub {
      * call site (this hub is constructed directly by several tests) keeps
      * working unchanged.
      */
-    rateLimiter?: RateLimiter);
+    rateLimiter?: RateLimiter, agentMessage?: {
+        consume(input: {
+            readonly deviceId: string;
+            readonly taskId: string;
+            readonly context: AgentMessageServerContext;
+            readonly payload: AgentMessagePublishPayload;
+        }): {
+            readonly outcome: 'accepted' | 'held' | 'refused';
+            readonly reasonCode?: string;
+        };
+    } | undefined);
     /**
      * Stop the task-lease reaper's sweep timer — called by `ByokServer.stop()`
      * (`index.ts`) on shutdown. Idempotent: clearing an already-cleared
@@ -380,6 +394,8 @@ export declare class ConnectionHub {
      * facts is rejected rather than treated as an update.
      */
     private handleAgentEgressReliable;
+    private handleAgentMessagePublish;
+    private sendAgentMessageDisposition;
     private handleAgentContentReceipt;
     private sendAgentEgressAck;
     private sendAgentContentReceiptAck;

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, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, AgentRefSchema, AgentEgressPolicySchema, DispatchSelectionSchema, RequiredToolsetsSchema, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, AgentContentReadPayloadSchema, AgentHomeProjectionPayloadSchema, AGENT_HOME_PROJECTION_CAPABILITY, AgentHomeProjectionReadbackSchema, AgentHomeProjectionCompletionRequestSchema, 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, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, 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 { CAPABILITY_FLAGS, byokBlobContentPath, canTransition, PROTOCOL_VERSION, encodeEnvelope, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, AGENT_MESSAGE_EGRESS_CAPABILITY, AgentRefSchema, AgentEgressPolicySchema, AgentMessageEgressRequirementSchema, TerminalProjectionSelectionSchema, AgentMessageServerContextSchema, DispatchSelectionSchema, RequiredToolsetsSchema, STRICT_AGENT_ONLY_CAPABILITY, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, TERMINAL_PROJECTION_SELECTION_CAPABILITY, AgentContentReadPayloadSchema, AgentHomeProjectionPayloadSchema, AGENT_HOME_PROJECTION_CAPABILITY, AgentHomeProjectionReadbackSchema, AgentHomeProjectionCompletionRequestSchema, 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, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, 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';
@@ -540,11 +540,12 @@ var AgentHomeProjectionCompletionError = class extends Error {
   code;
 };
 var ConnectionHub = class {
-  constructor(taskStore, devices, taskLeaseMs, rateLimiter = new RateLimiter()) {
+  constructor(taskStore, devices, taskLeaseMs, rateLimiter = new RateLimiter(), agentMessage) {
     this.taskStore = taskStore;
     this.devices = devices;
     this.taskLeaseMs = taskLeaseMs;
     this.rateLimiter = rateLimiter;
+    this.agentMessage = agentMessage;
     const sweepIntervalMs = Math.min(Math.max(taskLeaseMs, 10), MAX_LEASE_REAPER_SWEEP_INTERVAL_MS);
     this.leaseReaperTimer = setInterval(() => this.sweepLeases(), sweepIntervalMs);
     this.leaseReaperTimer.unref?.();
@@ -553,6 +554,7 @@ var ConnectionHub = class {
   devices;
   taskLeaseMs;
   rateLimiter;
+  agentMessage;
   connections = /* @__PURE__ */ new Map();
   outboxes = /* @__PURE__ */ new Map();
   /** Idempotency window per device (N3) — recent inbound envelope ids, capped at {@link DEDUP_RING_CAPACITY}. */
@@ -562,6 +564,9 @@ var ConnectionHub = class {
   serverEvents = new AsyncEventQueue();
   /** First-write-wins reliable facts; the reference composition's bounded in-memory readback. */
   agentEgressReceipts = /* @__PURE__ */ new Map();
+  agentMessageRequirements = /* @__PURE__ */ new Map();
+  agentMessageReceipts = /* @__PURE__ */ new Map();
+  agentMessageTaskPayloads = /* @__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. */
@@ -824,6 +829,9 @@ var ConnectionHub = class {
     if (envelope.type === "agent.egress.reliable") {
       return this.handleAgentEgressReliable(deviceId, envelope.payload);
     }
+    if (envelope.type === "agent.message.publish") {
+      return this.handleAgentMessagePublish(deviceId, envelope.task_id, envelope.payload);
+    }
     if (envelope.type === "agent.content.receipt") {
       return this.handleAgentContentReceipt(deviceId, envelope.payload);
     }
@@ -868,6 +876,40 @@ var ConnectionHub = class {
     this.sendAgentEgressAck(deviceId, receipt);
     return "accepted";
   }
+  handleAgentMessagePublish(deviceId, taskId, payload) {
+    if (!this.hasDeviceCapabilities(deviceId, [AGENT_MESSAGE_EGRESS_CAPABILITY])) return "rejected";
+    const binding = this.agentMessageRequirements.get(taskId);
+    const record = this.taskStore.get(taskId);
+    if (binding === void 0 || record === void 0 || record.deviceId !== deviceId || binding.deviceId !== deviceId || !sameAgentRef(binding.agentRef, payload.agentRef) || binding.sessionRef !== void 0 && binding.sessionRef !== payload.sessionRef || binding.requirement.contract !== payload.contract || binding.requirement.contentType !== payload.contentType || payload.byteCount > binding.requirement.maxBytes) return "rejected";
+    const taskPayload = this.agentMessageTaskPayloads.get(taskId);
+    if (taskPayload !== void 0 && JSON.stringify(taskPayload) !== JSON.stringify(payload)) return "rejected";
+    if (taskPayload === void 0) this.agentMessageTaskPayloads.set(taskId, payload);
+    const key = `${deviceId}\0${payload.messageId}`;
+    const previous = this.agentMessageReceipts.get(key);
+    if (previous !== void 0) {
+      if (JSON.stringify(previous.payload) !== JSON.stringify(payload)) return "rejected";
+      this.sendAgentMessageDisposition(deviceId, taskId, previous.disposition);
+      return "duplicate";
+    }
+    const decision = this.agentMessage?.consume({ deviceId, taskId, context: binding.context, payload }) ?? { outcome: "held", reasonCode: "consumer_unavailable" };
+    const disposition = {
+      agentRef: payload.agentRef,
+      sessionRef: payload.sessionRef,
+      contract: payload.contract,
+      messageId: payload.messageId,
+      cursor: payload.cursor,
+      contentHash: payload.contentHash,
+      outcome: decision.outcome,
+      receiptId: crypto.randomUUID(),
+      ...decision.reasonCode === void 0 ? {} : { reasonCode: decision.reasonCode }
+    };
+    this.agentMessageReceipts.set(key, { payload, disposition });
+    this.sendAgentMessageDisposition(deviceId, taskId, disposition);
+    return "accepted";
+  }
+  sendAgentMessageDisposition(deviceId, taskId, payload) {
+    this.sendToDevice(deviceId, "agent.message.disposition", payload, { taskId });
+  }
   handleAgentContentReceipt(deviceId, payload) {
     const capability = contentReadCapability(payload.surface);
     if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) return "rejected";
@@ -1627,20 +1669,34 @@ var ConnectionHub = class {
     const sessionRef = "sessionRef" in input ? input.sessionRef : void 0;
     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 messageEgress = input.messageEgress === void 0 ? void 0 : AgentMessageEgressRequirementSchema.parse(input.messageEgress);
+    const terminalProjection = input.terminalProjection === void 0 ? void 0 : TerminalProjectionSelectionSchema.parse(input.terminalProjection);
+    if (messageEgress === void 0 && input.agentMessageContext !== void 0) {
+      throw new Error("agentMessageContext requires messageEgress");
+    }
+    const agentMessageContext = messageEgress === void 0 ? void 0 : AgentMessageServerContextSchema.parse(input.agentMessageContext);
     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);
+    const deviceId = input.deviceId ?? this.pickFirstConnectedDevice(requiredToolsets, agentRef !== void 0);
     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 (messageEgress !== void 0 && egressPolicy === void 0) {
+      throw new Error("Agent message egress requires the typed Agent egress offer path");
+    }
     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(STRICT_AGENT_ONLY_CAPABILITY) === true) {
+      throw new Error(
+        `device ${deviceId} advertises strict-agent-only; legacy task dispatch is refused before enqueue`
+      );
+    }
     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`
@@ -1656,6 +1712,12 @@ var ConnectionHub = class {
         freshAgentEgress ? `device ${deviceId} did not advertise Agent egress policy, reliable acknowledgement, and fresh-session capabilities; refusing before enqueue` : `device ${deviceId} did not advertise Agent egress policy and reliable acknowledgement capabilities; refusing before enqueue`
       );
     }
+    if (messageEgress !== void 0 && !this.hasDeviceCapabilities(deviceId, [AGENT_MESSAGE_EGRESS_CAPABILITY])) {
+      throw new Error(`device ${deviceId} did not advertise Agent message egress capability; refusing before enqueue`);
+    }
+    if (terminalProjection !== void 0 && !this.hasDeviceCapabilities(deviceId, [TERMINAL_PROJECTION_SELECTION_CAPABILITY])) {
+      throw new Error(`device ${deviceId} did not advertise terminal projection selection capability; 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`
@@ -1705,6 +1767,9 @@ var ConnectionHub = class {
       resolveResult = resolve;
     });
     this.runtimes.set(taskId, { queue, resolveResult, result });
+    if (messageEgress !== void 0 && agentRef !== void 0) {
+      this.agentMessageRequirements.set(taskId, { deviceId, agentRef, sessionRef, requirement: messageEgress, context: agentMessageContext });
+    }
     queue.push({ kind: "state", state: record.state, at: record.createdAt });
     this.serverEvents.push({ kind: "task.created", taskId, at: record.createdAt });
     const commonOffer = {
@@ -1722,6 +1787,8 @@ var ConnectionHub = class {
         dispatchSelection,
         agentRef,
         egressPolicy,
+        terminalProjection,
+        ...messageEgress === void 0 ? {} : { messageEgress },
         ...requiredToolsets === void 0 ? {} : { requiredToolsets }
       };
       this.sendToDevice(
@@ -1739,6 +1806,8 @@ var ConnectionHub = class {
           sessionRef,
           agentRef,
           egressPolicy,
+          terminalProjection,
+          ...messageEgress === void 0 ? {} : { messageEgress },
           ...requiredToolsets === void 0 ? {} : { requiredToolsets }
         },
         { taskId, sessionRef }
@@ -1747,7 +1816,12 @@ var ConnectionHub = class {
       this.sendToDevice(
         deviceId,
         "task.offer_for_agent",
-        { ...commonOffer, agentRef, ...requiredToolsets === void 0 ? {} : { requiredToolsets } },
+        {
+          ...commonOffer,
+          agentRef,
+          ...terminalProjection === void 0 ? {} : { terminalProjection },
+          ...requiredToolsets === void 0 ? {} : { requiredToolsets }
+        },
         { taskId, sessionRef }
       );
     } else if (requiredToolsets === void 0) {
@@ -2005,9 +2079,10 @@ var ConnectionHub = class {
     }
     this.sendToDevice(record.deviceId, "task.steer", { text }, { taskId });
   }
-  pickFirstConnectedDevice(requiredToolsets) {
+  pickFirstConnectedDevice(requiredToolsets, allowStrictAgentOnly = false) {
     for (const [deviceId, conn] of this.connections) {
       if (!conn.connected) continue;
+      if (!allowStrictAgentOnly && conn.capabilities?.includes(STRICT_AGENT_ONLY_CAPABILITY)) continue;
       if (requiredToolsets === void 0) return deviceId;
       if (!conn.capabilities?.includes("toolset-selection")) continue;
       if (conn.configuredToolsets === void 0) continue;
@@ -2039,7 +2114,7 @@ var ConnectionHub = class {
     const envelope = createEnvelope(type, payload, combinedOpts);
     const taskId = opts.taskId;
     const redeliverThroughTerminal = type === "task.cancel" || type === "task.reject";
-    const redeliverWithoutTask = type === "agent.egress.ack" || type === "agent.content.read" || type === "agent.home.projection";
+    const redeliverWithoutTask = type === "agent.egress.ack" || type === "agent.content.read" || type === "agent.home.projection" || type === "agent.message.disposition";
     outbox.ring.push({ seq, taskId, envelope, redeliverThroughTerminal, redeliverWithoutTask });
     if (outbox.ring.length > OUTBOX_RING_CAPACITY) outbox.ring.shift();
     this.deliverToDevice(deviceId, envelope);
@@ -3145,7 +3220,7 @@ function createByokServer(opts) {
   const taskLeaseMs = opts.taskLeaseMs ?? DEFAULT_TASK_LEASE_MS;
   const rateLimiter = new RateLimiter(opts.rateLimit);
   const taskStore = opts.taskStore ?? new InMemoryTaskStore();
-  const hub = new ConnectionHub(taskStore, devices, taskLeaseMs, rateLimiter);
+  const hub = new ConnectionHub(taskStore, devices, taskLeaseMs, rateLimiter, opts.agentMessage);
   const hono = buildHonoApp({
     pairing,
     devices,