@byok-sdk/cloud 0.14.0 → 0.16.0

package/dist/index.js

@@ -1,11 +1,30 @@
 import { BOARD_STATUSES, CapabilityDeclarationSchema, NONCE_SIGNING_DOMAIN, hasCapability, isTenantId, tenantId, principalTenant, parseDeviceProofEnvelope, deviceProofSigningInput, contentHash, parseCapabilityDeclaration, ByokCoreError, tenantKey, PRESENCE_LEVELS, createInMemoryCoreStores, authenticateDeviceAssertion, assertCapability, isCoreConflictError, isCoreError, DEVICE_PROOF_HEADER, TRUTH_RECORD_KINDS, STORAGE_ERROR_CODES, STORAGE_ERROR_HTTP_STATUS } from '@byok-sdk/core';
 export { DEVICE_PROOF_HEADER, NONCE_SIGNING_DOMAIN, isTenantId, tenantId } from '@byok-sdk/core';
-import { AgentEventOrUnknownSchema, PROTOCOL_VERSION, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, encodeEnvelope, decodeEnvelope, AgentHomeProjectionCompletionRequestSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_AGENT_MEMORY_PROJECTIONS_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, BYOK_BOARD_PATH, BYOK_BOARD_CLAIM_ROUTE, BYOK_BOARD_UNCLAIM_ROUTE, BYOK_BOARD_STATUS_ROUTE, BYOK_BOARD_STREAM_PATH, BYOK_PRESENCE_PATH, BYOK_ACTIVITY_PATH, BYOK_RECORDS_PATH, BYOK_RECORD_ROUTE, BYOK_SKILL_PACKS_PATH, BYOK_SKILL_PACK_FILE_ROUTE, BYOK_BLOBS_PATH, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, createEnvelope, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, AGENT_MESSAGE_EGRESS_CAPABILITY, TERMINAL_PROJECTION_SELECTION_CAPABILITY, TaskOfferForAgentWithEgressFreshPayloadSchema, AgentMessageServerContextSchema, TaskOfferForAgentWithEgressPayloadSchema, TaskOfferForAgentPayloadSchema, AgentMemoryProjectionMutationSchema, AgentMemoryProjectionReceiptSchema, AGENT_MEMORY_PROJECTION_MAX_ORDERING_VALUE, AgentMemoryProjectionEraseResultSchema, STRICT_AGENT_ONLY_CAPABILITY, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, AGENT_HOME_PROJECTION_CAPABILITY, AgentRefSchema, PairRequestSchema, PairResponseSchema, ChallengeRequestSchema, TokenRequestSchema, AgentMemoryProjectionCommitRequestSchema, agentMemoryProjectionBase64UrlByteLength, MessagesSendRequestSchema, PresencePublishRequestSchema, CreateBlobRequestSchema, byokBlobContentPath, AgentEgressAckPayloadSchema, AgentContentReceiptPayloadSchema } from '@byok-sdk/protocol';
+import { AgentEventOrUnknownSchema, PROTOCOL_VERSION, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, encodeEnvelope, decodeEnvelope, AgentHomeProjectionCompletionRequestSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_AGENT_MEMORY_PROJECTIONS_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, BYOK_BOARD_PATH, BYOK_BOARD_CLAIM_ROUTE, BYOK_BOARD_UNCLAIM_ROUTE, BYOK_BOARD_STATUS_ROUTE, BYOK_BOARD_STREAM_PATH, BYOK_PRESENCE_PATH, BYOK_ACTIVITY_PATH, BYOK_RECORDS_PATH, BYOK_RECORD_ROUTE, BYOK_SKILL_PACKS_PATH, BYOK_SKILL_PACK_FILE_ROUTE, BYOK_BLOBS_PATH, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, createEnvelope, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, AGENT_MESSAGE_EGRESS_CAPABILITY, TERMINAL_PROJECTION_SELECTION_CAPABILITY, TaskOfferForAgentWithEgressFreshPayloadSchema, AgentMessageServerContextSchema, TaskOfferForAgentWithEgressPayloadSchema, TaskOfferForAgentPayloadSchema, AgentMemoryProjectionMutationSchema, AgentMemoryProjectionReceiptSchema, AGENT_MEMORY_PROJECTION_MAX_ORDERING_VALUE, AgentMemoryProjectionEraseResultSchema, HarnessIdSchema, STRICT_AGENT_ONLY_CAPABILITY, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, AGENT_HOME_PROJECTION_CAPABILITY, AgentRefSchema, PairRequestSchema, PairResponseSchema, ChallengeRequestSchema, TokenRequestSchema, AgentMemoryProjectionCommitRequestSchema, agentMemoryProjectionBase64UrlByteLength, MAILBOX_READ_AHEAD_MAX_SEQS, MAILBOX_READ_AHEAD_CAPABILITY, MessagesSendRequestSchema, PresencePublishRequestSchema, CreateBlobRequestSchema, byokBlobContentPath, AgentEgressAckPayloadSchema, AgentContentReceiptPayloadSchema } from '@byok-sdk/protocol';
 import { z } from 'zod';
 import { Hono } from 'hono';
 
 // src/index.ts
 
+// src/offer-identity.ts
+function uuidFromSha256(value) {
+  const match = /^sha256:([0-9a-f]{64})$/.exec(value);
+  if (match === null) throw new Error("CloudCrypto.sha256 must return canonical sha256 hex");
+  const digest = match[1];
+  if (digest === void 0) throw new Error("CloudCrypto.sha256 must return canonical sha256 hex");
+  const hex = digest.slice(0, 32).split("");
+  hex[12] = "8";
+  hex[16] = ["8", "9", "a", "b"][Number.parseInt(hex[16], 16) & 3];
+  return `${hex.slice(0, 8).join("")}-${hex.slice(8, 12).join("")}-${hex.slice(12, 16).join("")}-${hex.slice(16, 20).join("")}-${hex.slice(20).join("")}`;
+}
+async function taskOfferMessageId(tenant, taskId, deviceId, agentRef, sha256) {
+  return uuidFromSha256(await sha256(new TextEncoder().encode(JSON.stringify({ domain: "byok:task-offer", tenant, taskId, deviceId, agentRef }))));
+}
+async function hashOfferBytes(bytes) {
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(bytes)));
+  return `sha256:${Array.from(hash, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+
 // src/approval-control.ts
 var StaleApprovalError = class extends Error {
   constructor(taskId, requestedApprovalId, currentApprovalId) {
@@ -668,7 +687,8 @@ function tenantStoresFor(principal, root) {
       revoke: (deviceId) => cloud.devices.revoke(tenant, deviceId),
       recordCapabilities: (input) => principal.kind === "device" ? cloud.devices.recordCapabilities(tenant, {
         deviceId: principal.deviceId,
-        capabilities: input.capabilities
+        capabilities: input.capabilities,
+        ...input.harnesses === void 0 ? {} : { harnesses: input.harnesses }
       }) : Promise.resolve(void 0),
       readiness: () => cloud.devices.readiness(tenant, core.presence)
     },
@@ -1029,6 +1049,8 @@ function tokenHandler(deps) {
   };
 }
 var CLOUD_PROTOCOL_CAPABILITIES = [
+  "custom-harness",
+  MAILBOX_READ_AHEAD_CAPABILITY,
   "result-document",
   // The kernel's inbound handles `task.approval_resolved` on both the plain
   // and the approval-timeline paths (`packages/cloud/src/inbound.ts:576,610`).
@@ -1065,7 +1087,13 @@ function eventsHandler(deps) {
       }
       cursor = parsedCursor;
     }
+    const afterRaw = c.req.query("afterSeq");
+    const afterSeq = afterRaw === void 0 ? cursor : Number(afterRaw);
+    if (!Number.isSafeInteger(afterSeq) || afterSeq < cursor || afterSeq - cursor > MAILBOX_READ_AHEAD_MAX_SEQS) {
+      return c.json({ error: "invalid read-ahead offset" }, 400);
+    }
     const acked = await stores.mailbox.readCursor(device.deviceId);
+    if (afterRaw !== void 0 && afterSeq > acked.deliveredSeq) return c.json({ error: "read offset exceeds delivered watermark" }, 409);
     if (cursor > acked.ackedSeq) {
       try {
         await stores.mailbox.advanceCursor({ deviceId: device.deviceId, ackedSeq: cursor });
@@ -1078,7 +1106,7 @@ function eventsHandler(deps) {
     }
     const attempts = Math.max(1, Math.ceil(deps.longPollHoldMs / deps.longPollIntervalMs));
     for (let attempt = 0; attempt < attempts; attempt += 1) {
-      let scanCursor = cursor;
+      let scanCursor = afterSeq;
       while (true) {
         const page = await stores.mailbox.readAfter({
           deviceId: device.deviceId,
@@ -1122,7 +1150,7 @@ function eventsHandler(deps) {
     }
     const response = {
       events: [],
-      cursor,
+      cursor: afterSeq,
       capabilities: CLOUD_PROTOCOL_CAPABILITIES
     };
     return c.json(response, 200);
@@ -1385,6 +1413,7 @@ function agentRefEchoRequired(envelope) {
   return envelope.type === "task.claim" || envelope.type === "task.decline" || envelope.type === "task.complete" || envelope.type === "task.fail" || envelope.type === "task.cancelled";
 }
 async function handleInboundEnvelope(stores, deviceId, envelope, activityBounds = DEFAULT_ACTIVITY_BOUNDS, agentMessageConsume, observer) {
+  if (envelope.v !== PROTOCOL_VERSION) return "rejected";
   const outcome = await applyInboundGate(
     stores,
     deviceId,
@@ -1404,12 +1433,13 @@ async function applyInboundGate(stores, deviceId, envelope, activityBounds, agen
   if (!await stores.rateLimiter.consume(deviceId)) return "rate_limited";
   if (envelope.type === "conn.hello") {
     if (envelope.payload.deviceId !== deviceId) return "rejected";
+    if (envelope.payload.harnesses !== void 0 && !envelope.payload.capabilities.includes("custom-harness")) return "rejected";
     if (!envelope.payload.protocolVersions.includes(PROTOCOL_VERSION)) return "rejected";
     const device = await stores.devices.get(deviceId);
     if (device === void 0 || device.revoked || device.productId !== envelope.payload.productId) {
       return "rejected";
     }
-    if (await stores.devices.recordCapabilities({ capabilities: envelope.payload.capabilities }) === void 0) {
+    if (await stores.devices.recordCapabilities({ capabilities: envelope.payload.capabilities, ...envelope.payload.harnesses === void 0 ? {} : { harnesses: envelope.payload.harnesses } }) === void 0) {
       return "rejected";
     }
     return completeInboundEnvelope(stores, deviceId, envelope.id, void 0);
@@ -1456,6 +1486,34 @@ async function applyInboundGate(stores, deviceId, envelope, activityBounds, agen
   if (attempt === void 0 || attempt.deviceId !== deviceId) return "rejected";
   if (attempt?.ownerDeviceId !== void 0 && attempt.ownerDeviceId !== deviceId) return "rejected";
   if (envelope.type === "task.claim" && envelope.payload.deviceId !== deviceId) return "rejected";
+  if (envelope.type === "task.claim") {
+    const harnessId = envelope.payload.harnessId;
+    if (harnessId !== void 0 && envelope.payload.runtime !== void 0) return "rejected";
+    if (attempt.ownerDeviceId !== void 0 && (harnessId !== void 0 || attempt.claimedHarnessId !== void 0) && harnessId !== attempt.claimedHarnessId) return "rejected";
+    const device = await stores.devices.get(deviceId);
+    if (harnessId !== void 0 && (!device?.capabilities?.includes("custom-harness") || !device.harnesses?.some((harness) => harness.id === harnessId))) return "rejected";
+    const messageId = await taskOfferMessageId(stores.tenant, taskId, deviceId, attempt.agentRef, hashOfferBytes);
+    const offer = await stores.receipts.get(`task-offer:${messageId}`);
+    if (offer !== void 0) {
+      const sealed = JSON.parse(offer.body);
+      if (harnessId !== void 0 && (sealed.payload.runtime !== void 0 || sealed.payload.dispatchSelection !== void 0)) return "rejected";
+      if (sealed.payload.harnessId !== void 0 && sealed.payload.harnessId !== harnessId) return "rejected";
+    } else if (harnessId !== void 0) return "rejected";
+  }
+  let unclaimedInterruption = false;
+  if (envelope.type === "task.fail" && envelope.payload.recovery !== void 0) {
+    if (envelope.payload.reason !== "daemon_interrupted" || envelope.payload.retryable !== false) return "rejected";
+    const messageId = await taskOfferMessageId(stores.tenant, taskId, deviceId, attempt.agentRef, hashOfferBytes);
+    if (envelope.payload.recovery.offerId !== messageId) return "rejected";
+    const offer = await stores.receipts.get(`task-offer:${messageId}`);
+    if (offer === void 0) return "rejected";
+    const sealed = JSON.parse(offer.body);
+    const harnessId = envelope.payload.harnessId;
+    if (sealed.payload.harnessId !== void 0 && sealed.payload.harnessId !== harnessId) return "rejected";
+    if (harnessId !== void 0 && (sealed.payload.runtime !== void 0 || sealed.payload.dispatchSelection !== void 0)) return "rejected";
+    unclaimedInterruption = attempt.ownerDeviceId === void 0 && attempt.claimedHarnessId === void 0;
+  }
+  if ((envelope.type === "task.complete" || envelope.type === "task.fail" || envelope.type === "task.cancelled") && !unclaimedInterruption && envelope.payload.harnessId !== attempt.claimedHarnessId) return "rejected";
   if (attempt?.agentRef !== void 0 && agentRefEchoRequired(envelope) && !sameAgentRef(attempt.agentRef, inboundAgentRef(envelope))) {
     return "rejected";
   }
@@ -1487,7 +1545,8 @@ async function applyInboundGate(stores, deviceId, envelope, activityBounds, agen
       throw caught;
     }
   }
-  await applyLifecycle(stores, deviceId, taskId, envelope, activityBounds, attempt?.agentRef);
+  const lifecycleOutcome = await applyLifecycle(stores, deviceId, taskId, envelope, activityBounds, attempt?.agentRef);
+  if (lifecycleOutcome === "rejected") return "rejected";
   return completeInboundEnvelope(stores, deviceId, envelope.id, attempt?.agentRef);
 }
 async function completeInboundEnvelope(stores, deviceId, envelopeId, agentRef) {
@@ -1496,14 +1555,17 @@ async function completeInboundEnvelope(stores, deviceId, envelopeId, agentRef) {
 }
 async function applyLifecycle(stores, deviceId, taskId, envelope, activityBounds, persistedAgentRef) {
   switch (envelope.type) {
-    case "task.claim":
-      await stores.tasks.claim({
+    case "task.claim": {
+      const claimed = await stores.tasks.claim({
         taskId,
         deviceId,
         ...envelope.payload.runtime === void 0 ? {} : { runtime: envelope.payload.runtime },
+        ...envelope.payload.harnessId === void 0 ? {} : { harnessId: envelope.payload.harnessId },
         ...envelope.payload.capabilities === void 0 ? {} : { capabilities: envelope.payload.capabilities }
       });
+      if (claimed === void 0 || claimed.ownerDeviceId !== deviceId || claimed.claimedRuntime !== envelope.payload.runtime || claimed.claimedHarnessId !== envelope.payload.harnessId) return "rejected";
       return;
+    }
     case "task.started":
       await stores.tasks.recordStatus({
         taskId,
@@ -2620,6 +2682,7 @@ function projectTerminalResult(taskId, receipt) {
         sessionRef: envelope.payload.sessionRef,
         ...envelope.payload.artifactRefs !== void 0 ? { artifactRefs: envelope.payload.artifactRefs } : {},
         ...envelope.payload.document !== void 0 ? { document: envelope.payload.document } : {},
+        ...envelope.payload.harnessId === void 0 ? {} : { harnessId: envelope.payload.harnessId },
         ...envelope.payload.usage !== void 0 ? { usage: envelope.payload.usage } : {},
         recordedAt: receipt.recordedAt
       };
@@ -2628,9 +2691,11 @@ function projectTerminalResult(taskId, receipt) {
         taskId,
         state: "failed",
         ...envelope.payload.agentRef === void 0 ? {} : { agentRef: envelope.payload.agentRef },
+        ...envelope.payload.recovery === void 0 ? {} : { recovery: envelope.payload.recovery },
         reason: envelope.payload.reason,
         terminalCause: envelope.payload.reason,
         ...envelope.payload.retryable !== void 0 ? { retryable: envelope.payload.retryable } : {},
+        ...envelope.payload.harnessId === void 0 ? {} : { harnessId: envelope.payload.harnessId },
         ...envelope.payload.usage !== void 0 ? { usage: envelope.payload.usage } : {},
         recordedAt: receipt.recordedAt
       };
@@ -2656,6 +2721,7 @@ function projectTerminalResult(taskId, receipt) {
         ...envelope.payload.agentRef === void 0 ? {} : { agentRef: envelope.payload.agentRef },
         ...envelope.payload.reason !== void 0 ? { reason: envelope.payload.reason } : {},
         ...envelope.payload.reason === void 0 ? {} : { terminalCause: envelope.payload.reason },
+        ...envelope.payload.harnessId === void 0 ? {} : { harnessId: envelope.payload.harnessId },
         ...envelope.payload.usage !== void 0 ? { usage: envelope.payload.usage } : {},
         recordedAt: receipt.recordedAt
       };
@@ -2679,16 +2745,6 @@ function isTerminalAttemptStatus(status) {
 function sameAgentRef2(expected, actual) {
   return actual?.agentId === expected.agentId && actual.profileRevision === expected.profileRevision;
 }
-function uuidFromSha256(value) {
-  const match = /^sha256:([0-9a-f]{64})$/.exec(value);
-  if (match === null) throw new Error("CloudCrypto.sha256 must return canonical sha256 hex");
-  const digest = match[1];
-  if (digest === void 0) throw new Error("CloudCrypto.sha256 must return canonical sha256 hex");
-  const hex = digest.slice(0, 32).split("");
-  hex[12] = "8";
-  hex[16] = ["8", "9", "a", "b"][Number.parseInt(hex[16], 16) & 3];
-  return `${hex.slice(0, 8).join("")}-${hex.slice(8, 12).join("")}-${hex.slice(12, 16).join("")}-${hex.slice(16, 20).join("")}-${hex.slice(20).join("")}`;
-}
 function sameOfferEnvelope(expected, actual) {
   return expected.id === actual.id && expected.type === actual.type && expected.task_id === actual.task_id && JSON.stringify(expected.payload) === JSON.stringify(actual.payload);
 }
@@ -2895,13 +2951,16 @@ function createByokCloud(options) {
   async function enqueueTaskEnvelope(tenant, deviceId, requestedTaskId, agentRef, buildEnvelope, beforeMailbox) {
     const stores = tenantStoresFor(controlPlane(tenant), root);
     const taskId = requestedTaskId ?? `task_${options.crypto.randomUuid()}`;
-    const messageId = uuidFromSha256(
-      await options.crypto.sha256(
-        new TextEncoder().encode(
-          JSON.stringify({ domain: "byok:task-offer", tenant, taskId, deviceId, agentRef })
-        )
-      )
-    );
+    const messageId = await taskOfferMessageId(tenant, taskId, deviceId, agentRef, (bytes) => options.crypto.sha256(bytes));
+    const proposed = buildEnvelope(taskId, 0, messageId);
+    const selection = proposed.payload;
+    if (selection.harnessId !== void 0) {
+      HarnessIdSchema.parse(selection.harnessId);
+      if (selection.runtime !== void 0 || selection.dispatchSelection !== void 0) throw new ByokCloudError("coordination_input_invalid", "harnessId conflicts with built-in runtime selection");
+      await assertAgentCapabilities(tenant, deviceId, ["custom-harness"]);
+      const device = await options.cloud.devices.get(tenant, deviceId);
+      if (!device?.harnesses?.some((harness) => harness.id === selection.harnessId)) throw new ByokCloudError("coordination_input_invalid", "requested custom harness is not advertised by this device");
+    }
     const reservation = agentRef === void 0 ? void 0 : await stores.tasks.reserveAgentOffer({ taskId, deviceId, agentRef });
     const openedBeforeAppend = reservation?.attempt ?? (agentRef === void 0 ? await stores.tasks.open({ taskId, deviceId }) : void 0);
     if (openedBeforeAppend === void 0 || openedBeforeAppend.deviceId !== deviceId || (agentRef === void 0 ? openedBeforeAppend.agentRef !== void 0 : openedBeforeAppend.agentRef === void 0 || !sameAgentRef2(agentRef, openedBeforeAppend.agentRef))) {
@@ -2918,7 +2977,6 @@ function createByokCloud(options) {
         `Task ${taskId} already has a durable delivered attempt and cannot be enqueued again.`
       );
     }
-    const proposed = buildEnvelope(taskId, 0, messageId);
     const proposedBody = JSON.stringify({
       deviceId,
       type: proposed.type,
@@ -3983,7 +4041,8 @@ var InMemoryDeviceDirectory = class {
     if (record === void 0 || record.revoked) return void 0;
     const updated = {
       ...record,
-      capabilities: Object.freeze([...input.capabilities])
+      capabilities: Object.freeze([...input.capabilities]),
+      harnesses: Object.freeze((input.harnesses ?? []).map((value) => Object.freeze({ ...value })))
     };
     this.#byTenant.set(key, updated);
     return updated;
@@ -4365,6 +4424,7 @@ var InMemoryTaskAttemptStore = class {
         ...existing,
         ownerDeviceId: input.deviceId,
         ...input.runtime === void 0 ? {} : { claimedRuntime: input.runtime },
+        ...input.harnessId === void 0 ? {} : { claimedHarnessId: input.harnessId },
         ...input.capabilities === void 0 ? {} : { claimedRuntimeCapabilities: { ...input.capabilities } },
         status: "claimed",
         updatedAt: this.#now()