@byok-sdk/server 0.6.1 → 0.8.0-beta.0

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, AgentContentReadRequest, AgentEgressReceipt, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
+import type { ByokServerEvent, AgentContentReadRequest, AgentEgressReceipt, DispatchInput, FreshAgentEgressDispatchInput, 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
@@ -749,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>;
+    dispatchFreshAgentEgress(input: FreshAgentEgressDispatchInput): Promise<TaskHandle>;
+    private dispatchInternal;
     /** Capability-gated control-plane read request; no request enters the outbox on omission. */
     requestAgentContentRead(input: AgentContentReadRequest): Promise<void>;
     private buildTaskHandle;

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, 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';
+import type { ByokServerEvent, AgentContentReadRequest, AgentEgressReceipt, CreateByokServerOptions, DispatchInput, FreshAgentEgressDispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
+export type { ByokServerEvent, AgentContentReadRequest, AgentEgressReceipt, CreateByokServerOptions, DispatchInput, FreshAgentEgressDispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
 export type { CreateTaskInput, TaskRecord, TaskStore } from './task-store';
 export { IllegalTaskTransitionError, InMemoryTaskStore } from './task-store';
 /**
@@ -60,6 +60,8 @@ export interface ByokServer {
         createPairingCode(claims: PairingCodeClaims): PairingCodeInfo;
     };
     dispatch(input: DispatchInput): Promise<TaskHandle>;
+    /** Dispatch a fresh Agent execution whose runtime will mint its session after start. */
+    dispatchFreshAgentEgress(input: FreshAgentEgressDispatchInput): Promise<TaskHandle>;
     /** Enqueue one capability-gated, exact-identity content-read request. */
     requestAgentContentRead(input: AgentContentReadRequest): Promise<void>;
     tasks: {

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, AgentContentReadPayloadSchema, 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, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, 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, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, 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) => {
@@ -1849,6 +1857,25 @@ var ConnectionHub = class {
   // dispatch() and the TaskHandle it returns
   // ---------------------------------------------------------------------
   async dispatch(input) {
+    if (input.egressPolicy !== void 0 && input.sessionRef === void 0) {
+      throw new Error("Agent egress resume dispatch requires an exact sessionRef; use dispatchFreshAgentEgress for fresh execution");
+    }
+    return this.dispatchInternal(input, false);
+  }
+  async dispatchFreshAgentEgress(input) {
+    if (Object.prototype.hasOwnProperty.call(input, "sessionRef")) {
+      throw new Error("fresh Agent egress dispatch must not carry sessionRef");
+    }
+    if (typeof input.deviceId !== "string" || input.deviceId.length === 0) {
+      throw new Error("fresh Agent egress dispatch requires an explicit deviceId");
+    }
+    if (input.agentRef === void 0 || input.egressPolicy === void 0) {
+      throw new Error("fresh Agent egress dispatch requires exact AgentRef and egress policy");
+    }
+    return this.dispatchInternal(input, true);
+  }
+  async dispatchInternal(input, freshAgentEgress) {
+    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 dispatchSelection = input.dispatchSelection === void 0 ? void 0 : DispatchSelectionSchema.parse(input.dispatchSelection);
@@ -1860,9 +1887,6 @@ var ConnectionHub = class {
     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)"
@@ -1873,9 +1897,14 @@ var ConnectionHub = class {
         `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])) {
+    const requiredEgressCapabilities = freshAgentEgress ? [
+      AGENT_EGRESS_POLICY_CAPABILITY,
+      AGENT_EGRESS_RELIABLE_ACK_CAPABILITY,
+      AGENT_EGRESS_FRESH_SESSION_CAPABILITY
+    ] : [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY];
+    if (egressPolicy !== void 0 && !this.hasDeviceCapabilities(deviceId, requiredEgressCapabilities)) {
       throw new Error(
-        `device ${deviceId} did not advertise Agent egress policy and reliable acknowledgement capabilities; refusing before enqueue`
+        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 (dispatchSelection !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("dispatch-selection") ?? false)) {
@@ -1918,7 +1947,7 @@ var ConnectionHub = class {
       policy,
       requiredToolsets,
       deviceId,
-      sessionRef: input.sessionRef,
+      sessionRef,
       agentRef
     });
     const queue = new AsyncEventQueue();
@@ -1934,36 +1963,52 @@ var ConnectionHub = class {
       policy,
       runtime,
       dispatchSelection,
-      sessionRef: input.sessionRef
+      sessionRef
     };
-    if (agentRef !== void 0 && egressPolicy !== void 0) {
+    if (agentRef !== void 0 && egressPolicy !== void 0 && freshAgentEgress) {
+      const freshOffer = {
+        instruction: input.instruction,
+        policy,
+        runtime,
+        dispatchSelection,
+        agentRef,
+        egressPolicy,
+        ...requiredToolsets === void 0 ? {} : { requiredToolsets }
+      };
+      this.sendToDevice(
+        deviceId,
+        "task.offer_for_agent_with_egress_fresh",
+        freshOffer,
+        { taskId }
+      );
+    } else if (agentRef !== void 0 && egressPolicy !== void 0) {
       this.sendToDevice(
         deviceId,
         "task.offer_for_agent_with_egress",
         {
           ...commonOffer,
-          sessionRef: input.sessionRef,
+          sessionRef,
           agentRef,
           egressPolicy,
           ...requiredToolsets === void 0 ? {} : { requiredToolsets }
         },
-        { taskId, sessionRef: input.sessionRef }
+        { taskId, sessionRef }
       );
     } else if (agentRef !== void 0) {
       this.sendToDevice(
         deviceId,
         "task.offer_for_agent",
         { ...commonOffer, agentRef, ...requiredToolsets === void 0 ? {} : { requiredToolsets } },
-        { taskId, sessionRef: input.sessionRef }
+        { taskId, sessionRef }
       );
     } else if (requiredToolsets === void 0) {
-      this.sendToDevice(deviceId, "task.offer", commonOffer, { taskId, sessionRef: input.sessionRef });
+      this.sendToDevice(deviceId, "task.offer", commonOffer, { taskId, sessionRef });
     } else {
       this.sendToDevice(
         deviceId,
         "task.offer_with_toolsets",
         { ...commonOffer, requiredToolsets },
-        { taskId, sessionRef: input.sessionRef }
+        { taskId, sessionRef }
       );
     }
     return this.buildTaskHandle(taskId);
@@ -3027,6 +3072,7 @@ function createByokServer(opts) {
       createPairingCode: (claims) => pairing.createPairingCode(claims)
     },
     dispatch: (input) => hub.dispatch(input),
+    dispatchFreshAgentEgress: (input) => hub.dispatchFreshAgentEgress(input),
     requestAgentContentRead: (input) => hub.requestAgentContentRead(input),
     tasks: {
       get: (taskId) => hub.getTask(taskId),