@byok-sdk/cloud 0.3.0 → 0.4.1

package/README.md

@@ -4,7 +4,7 @@ Stateless hosted BYOK HTTP handlers and an in-memory reference composition over
 tenant-first `@byok-sdk/core` ports. It owns device-facing protocol/auth/policy
 logic but no durable database or object-storage driver.
 
-Pair it with `@byok-sdk/cloud-postgres` for Postgres + R2 production storage.
+Pair it with `@byok-sdk/cloud-dataplane` for Postgres + R2 production storage.
 
 Hosted compositions enqueue the distinct toolset offer message explicitly:
 
@@ -22,6 +22,31 @@ await cloud.enqueueToolsetOffer(tenantId, deviceId, {
 
 Unlike the live self-hosted coordinator, this stateless enqueue API cannot
 infer current device capabilities; the host must route to a device known to
-advertise `toolset-selection`.
+advertise `toolset-selection`. `listPresence(tenant)` includes the optional
+`configuredToolsets` reported by each live daemon, so the host can narrow
+candidate devices before enqueue. This is TTL-bounded discovery, not execution
+authority: the daemon still resolves every required ID locally and declines
+fail-closed if its configuration changed.
 
-MIT licensed. Node.js 22.19.0 or newer.
+Reading a task's outcome goes through the same first terminal fact twice:
+`readTerminalReceipt(tenant, taskId)` returns the stored envelope raw, and
+`readTaskResult(tenant, taskId)` decodes that same receipt into a typed
+`TerminalResult` — the state, plus `summary`/`sessionRef`/`artifactRefs`/
+`document` on a completion or `reason`/`retryable` on a failure — projected
+verbatim with no re-validation:
+
+```ts
+const result = await cloud.readTaskResult(tenantId, taskId);
+if (result === undefined) {
+  // No terminal fact yet. A declined task records none — read the attempt
+  // status with `readTaskAttempt(tenant, taskId)` for that case.
+} else if (result.state === 'failed' && result.retryable) {
+  // re-offer
+}
+```
+
+`document` is absent, never null, when the daemon sent none; a receipt whose
+stored body is not a terminal envelope throws `ByokCloudError` rather than
+returning a best-effort shape.
+
+MIT licensed. Node.js 22.22.0 or newer.

package/dist/cloud.d.ts

@@ -20,6 +20,7 @@ import type { TokenSigner } from './auth/tokens';
 import type { CloudCrypto } from './crypto/port';
 import { type RouteDescriptor } from './router/registry';
 import type { BlobContentProxy, CloudStores, DeviceRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
+import { type TerminalResult } from './terminal-result';
 import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
 /** Matches the reference server's ceiling (§7). */
 export declare const DEFAULT_MAX_BLOB_SIZE_BYTES: number;
@@ -127,6 +128,19 @@ export interface ByokCloud {
     readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     /** The recorded terminal for a task — the first one, re-encoded canonically under the frozen v1 codec (see `recordTerminal`, `inbound.ts`: the stored body is `encodeEnvelope` of the zod-parsed envelope, not the device's original byte sequence). */
     readTerminalReceipt(tenant: TenantId, taskId: string): Promise<RequestReceipt | undefined>;
+    /**
+     * Host control plane: the same first terminal, decoded into the typed read
+     * model ({@link TerminalResult}) so a host reads result fields, not envelope
+     * prose. `undefined` ONLY means no terminal fact is recorded yet:
+     * first-terminal-wins is inherited from the receipt store
+     * ({@link ByokCloud.readTerminalReceipt} reads the same row), and a declined
+     * task records no terminal at all — use {@link ByokCloud.readTaskAttempt}
+     * for that attempt status. An absent `document` covers both a legacy
+     * pre-`result-document` daemon build and a daemon with no `resultDocument`
+     * extractor; a receipt whose body is not a terminal envelope throws rather
+     * than returning a best-effort shape.
+     */
+    readTaskResult(tenant: TenantId, taskId: string): Promise<TerminalResult | undefined>;
     listDevices(tenant: TenantId): Promise<readonly DeviceRecord[]>;
     revokeDevice(tenant: TenantId, deviceId: string): Promise<void>;
     /** Host control plane: create a board row from explicit producer labels. */

package/dist/errors.d.ts

@@ -32,6 +32,13 @@ export declare const CLOUD_ERROR_CODES: {
     readonly capability_over_declared: 'capability_over_declared';
     /** Host-supplied board labels or coordination input exceeded the explicit contract. */
     readonly coordination_input_invalid: 'coordination_input_invalid';
+    /**
+     * A terminal receipt whose stored body is not a terminal envelope — either
+     * undecodable or a non-terminal type. Whatever wrote that row broke the
+     * receipt-store contract, so the typed read model fails closed instead of
+     * projecting a best-effort shape.
+     */
+    readonly terminal_receipt_unreadable: 'terminal_receipt_unreadable';
     /** A progress/activity batch exceeded the configured event or byte ceiling. */
     readonly activity_batch_too_large: 'activity_batch_too_large';
 };

package/dist/index.d.ts

@@ -40,6 +40,8 @@ export { createWebCrypto } from './crypto/web-crypto';
 export type { CloudCrypto } from './crypto/port';
 export { handleInboundEnvelope, terminalReceiptKey } from './inbound';
 export type { InboundOutcome } from './inbound';
+export { projectTerminalResult } from './terminal-result';
+export type { TerminalResult } from './terminal-result';
 export { tenantStoresFor } from './tenant-stores';
 export type { TenantBoundActivity, TenantBoundBoard, CloudRootStores, TenantBoundBlobs, TenantBoundDedup, TenantBoundDevices, TenantBoundMailbox, TenantBoundPresence, TenantBoundQuota, TenantBoundRateLimiter, TenantBoundReceipts, TenantBoundTaskAttempts, TenantStores, } from './tenant-stores';
 export { DEFAULT_ACTIVITY_BOUNDS, DEFAULT_ACTIVITY_CAPACITY, DEFAULT_ACTIVITY_MAX_BYTES, DEFAULT_ACTIVITY_MAX_EVENTS, DEFAULT_ACTIVITY_TTL_MS, DEFAULT_BOARD_CHANNEL_MAX_BYTES, DEFAULT_BOARD_TITLE_MAX_BYTES, DEFAULT_PRESENCE_DETAIL_MAX_BYTES, DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS, DEFAULT_PRESENCE_TTL_MS, } from './coordination';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { BOARD_STATUSES, PRESENCE_LEVELS, CapabilityDeclarationSchema, NONCE_SIGNING_DOMAIN, hasCapability, isTenantId, tenantId, principalTenant, parseDeviceProofEnvelope, deviceProofSigningInput, parseCapabilityDeclaration, ByokCoreError, tenantKey, createInMemoryCoreStores, assertCapability, contentHash, 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, DAEMON_TO_SERVER_TYPES, encodeEnvelope, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, 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, decodeEnvelope, createEnvelope, PairRequestSchema, ChallengeRequestSchema, TokenRequestSchema, MessagesSendRequestSchema, CreateBlobRequestSchema, byokBlobContentPath } from '@byok-sdk/protocol';
+import { ConfiguredToolsetsSchema, AgentEventOrUnknownSchema, DAEMON_TO_SERVER_TYPES, encodeEnvelope, decodeEnvelope, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, 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, PairRequestSchema, ChallengeRequestSchema, TokenRequestSchema, MessagesSendRequestSchema, CreateBlobRequestSchema, byokBlobContentPath } from '@byok-sdk/protocol';
 import { z } from 'zod';
 import { Hono } from 'hono';
 
@@ -309,6 +309,13 @@ var CLOUD_ERROR_CODES = {
   capability_over_declared: "capability_over_declared",
   /** Host-supplied board labels or coordination input exceeded the explicit contract. */
   coordination_input_invalid: "coordination_input_invalid",
+  /**
+   * A terminal receipt whose stored body is not a terminal envelope — either
+   * undecodable or a non-terminal type. Whatever wrote that row broke the
+   * receipt-store contract, so the typed read model fails closed instead of
+   * projecting a best-effort shape.
+   */
+  terminal_receipt_unreadable: "terminal_receipt_unreadable",
   /** A progress/activity batch exceeded the configured event or byte ceiling. */
   activity_batch_too_large: "activity_batch_too_large"
 };
@@ -668,6 +675,7 @@ function tokenHandler(deps) {
     return c.json(response, 200);
   };
 }
+var CLOUD_PROTOCOL_CAPABILITIES = ["result-document"];
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -696,12 +704,20 @@ function eventsHandler(deps) {
       });
       if (page.messages.length > 0) {
         const events = page.messages.map((message) => decodeEnvelope(message.body));
-        const response2 = { events, cursor: page.nextSeq };
+        const response2 = {
+          events,
+          cursor: page.nextSeq,
+          capabilities: CLOUD_PROTOCOL_CAPABILITIES
+        };
         return c.json(response2, 200);
       }
       if (attempt < attempts - 1) await sleep(deps.longPollIntervalMs);
     }
-    const response = { events: [], cursor };
+    const response = {
+      events: [],
+      cursor,
+      capabilities: CLOUD_PROTOCOL_CAPABILITIES
+    };
     return c.json(response, 200);
   };
 }
@@ -1053,7 +1069,8 @@ function boardFailure(c, caught) {
 }
 var PresenceBodySchema = z.object({
   level: z.enum(PRESENCE_LEVELS),
-  detail: z.string().optional()
+  detail: z.string().optional(),
+  configuredToolsets: ConfiguredToolsetsSchema.optional()
 });
 var ActivityBodySchema = z.object({
   taskId: z.string().min(1).max(200),
@@ -1075,6 +1092,7 @@ function presencePublishHandler(deps) {
           deviceId: authenticated.device.deviceId,
           level: parsed.data.level,
           ...parsed.data.detail === void 0 ? {} : { detail: parsed.data.detail },
+          ...parsed.data.configuredToolsets === void 0 ? {} : { configuredToolsets: parsed.data.configuredToolsets },
           ttlMs: deps.ttlMs,
           minimumIntervalMs: deps.minimumIntervalMs
         }),
@@ -1555,6 +1573,50 @@ var CloudRouteRegistry = class {
     return this.#app.fetch;
   }
 };
+function projectTerminalResult(taskId, receipt) {
+  let envelope;
+  try {
+    envelope = decodeEnvelope(receipt.body);
+  } catch (cause) {
+    throw new ByokCloudError(
+      "terminal_receipt_unreadable",
+      `The terminal receipt for task ${taskId} holds a body that is not a decodable envelope.`,
+      { cause }
+    );
+  }
+  switch (envelope.type) {
+    case "task.complete":
+      return {
+        taskId,
+        state: "complete",
+        summary: envelope.payload.summary,
+        sessionRef: envelope.payload.sessionRef,
+        ...envelope.payload.artifactRefs !== void 0 ? { artifactRefs: envelope.payload.artifactRefs } : {},
+        ...envelope.payload.document !== void 0 ? { document: envelope.payload.document } : {},
+        recordedAt: receipt.recordedAt
+      };
+    case "task.fail":
+      return {
+        taskId,
+        state: "failed",
+        reason: envelope.payload.reason,
+        ...envelope.payload.retryable !== void 0 ? { retryable: envelope.payload.retryable } : {},
+        recordedAt: receipt.recordedAt
+      };
+    case "task.cancelled":
+      return {
+        taskId,
+        state: "cancelled",
+        ...envelope.payload.reason !== void 0 ? { reason: envelope.payload.reason } : {},
+        recordedAt: receipt.recordedAt
+      };
+    default:
+      throw new ByokCloudError(
+        "terminal_receipt_unreadable",
+        `The terminal receipt for task ${taskId} holds a ${envelope.type} envelope, which is not a terminal type.`
+      );
+  }
+}
 
 // src/cloud.ts
 var DEFAULT_MAX_BLOB_SIZE_BYTES = 100 * 1024 * 1024;
@@ -1786,6 +1848,12 @@ function createByokCloud(options) {
     readTerminalReceipt(tenant, taskId) {
       return tenantStoresFor(controlPlane(tenant), root).receipts.get(terminalReceiptKey(taskId));
     },
+    async readTaskResult(tenant, taskId) {
+      const receipt = await tenantStoresFor(controlPlane(tenant), root).receipts.get(
+        terminalReceiptKey(taskId)
+      );
+      return receipt === void 0 ? void 0 : projectTerminalResult(taskId, receipt);
+    },
     listDevices(tenant) {
       return tenantStoresFor(controlPlane(tenant), root).devices.list();
     },
@@ -2479,6 +2547,6 @@ var CLOUD_PORT_INTERFACES = {
   rateLimiter: "InboundRateLimiter"
 };
 
-export { ACCESS_TOKEN_TTL_SECONDS, AllowAllRateLimiter, BLOB_URL_TTL_MS, BoardFeedClient, BoardFeedRetryableError, BoardFeedStoppedError, ByokCloudError, CLOUD_CAPABILITIES, CLOUD_ERROR_CODES, CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS, CLOUD_STORE_NAMES, CapabilitiesResponseSchema, CloudRouteRegistry, DEDUP_RING_CAPACITY, DEFAULT_ACTIVITY_BOUNDS, DEFAULT_ACTIVITY_CAPACITY, DEFAULT_ACTIVITY_MAX_BYTES, DEFAULT_ACTIVITY_MAX_EVENTS, DEFAULT_ACTIVITY_TTL_MS, DEFAULT_BOARD_CHANNEL_MAX_BYTES, DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, DEFAULT_BOARD_TITLE_MAX_BYTES, DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS, DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS, DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, DEFAULT_MAX_TRUTH_REQUEST_BYTES, DEFAULT_PRESENCE_DETAIL_MAX_BYTES, DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS, DEFAULT_PRESENCE_TTL_MS, DEFAULT_SKILL_PACK_PAGE_LIMIT, DEVICE_IDENTITY_PROOF_KEY_EPOCH, DEVICE_IDENTITY_PROOF_KEY_ID, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryProofRequestReceiptStore, InMemoryRequestReceiptStore, InMemoryTaskAttemptStore, MAX_DEVICE_PROOF_CLOCK_SKEW_MS, MAX_DEVICE_PROOF_HEADER_BYTES, MAX_DEVICE_PROOF_MAX_LIFETIME_MS, NONCE_TTL_MS, PAIRING_CODE_TTL_MS, ROUTE_CLASSES, ROUTE_METHODS, TASK_ATTEMPT_STATUSES, TRUTH_BATCH_MAX_RECORDS, TRUTH_INLINE_CONTENT_TYPE, TRUTH_LABEL_MAX_LENGTH, TRUTH_MANIFEST_MAX_LIMIT, TRUTH_RECORD_CAPABILITY, TRUTH_RECORD_KEY_MAX_LENGTH, TRUTH_REQUEST_ID_MAX_LENGTH, TruthBodyInputSchema, TruthCommitError, TruthCommitResponseSchema, TruthRecordKeySchema, TruthRecordMetadataSchema, TruthWriteRequestSchema, authenticateBearer, authenticateDeviceProof, createAuthPlane, createByokCloud, createHmacTokenSigner, createInMemoryBlobs, createInMemoryByokCloud, createInMemoryCloudStores, createWebCrypto, declares, extractBearerToken, fullCapabilityDeclaration, handleInboundEnvelope, isCloudError, isTruthCommitError, routeKey, tenantStoresFor, terminalReceiptKey, truthManifestMetadata, truthRecordMetadata, verifyNonceSignature };
+export { ACCESS_TOKEN_TTL_SECONDS, AllowAllRateLimiter, BLOB_URL_TTL_MS, BoardFeedClient, BoardFeedRetryableError, BoardFeedStoppedError, ByokCloudError, CLOUD_CAPABILITIES, CLOUD_ERROR_CODES, CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS, CLOUD_STORE_NAMES, CapabilitiesResponseSchema, CloudRouteRegistry, DEDUP_RING_CAPACITY, DEFAULT_ACTIVITY_BOUNDS, DEFAULT_ACTIVITY_CAPACITY, DEFAULT_ACTIVITY_MAX_BYTES, DEFAULT_ACTIVITY_MAX_EVENTS, DEFAULT_ACTIVITY_TTL_MS, DEFAULT_BOARD_CHANNEL_MAX_BYTES, DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, DEFAULT_BOARD_TITLE_MAX_BYTES, DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS, DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS, DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, DEFAULT_MAX_TRUTH_REQUEST_BYTES, DEFAULT_PRESENCE_DETAIL_MAX_BYTES, DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS, DEFAULT_PRESENCE_TTL_MS, DEFAULT_SKILL_PACK_PAGE_LIMIT, DEVICE_IDENTITY_PROOF_KEY_EPOCH, DEVICE_IDENTITY_PROOF_KEY_ID, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryProofRequestReceiptStore, InMemoryRequestReceiptStore, InMemoryTaskAttemptStore, MAX_DEVICE_PROOF_CLOCK_SKEW_MS, MAX_DEVICE_PROOF_HEADER_BYTES, MAX_DEVICE_PROOF_MAX_LIFETIME_MS, NONCE_TTL_MS, PAIRING_CODE_TTL_MS, ROUTE_CLASSES, ROUTE_METHODS, TASK_ATTEMPT_STATUSES, TRUTH_BATCH_MAX_RECORDS, TRUTH_INLINE_CONTENT_TYPE, TRUTH_LABEL_MAX_LENGTH, TRUTH_MANIFEST_MAX_LIMIT, TRUTH_RECORD_CAPABILITY, TRUTH_RECORD_KEY_MAX_LENGTH, TRUTH_REQUEST_ID_MAX_LENGTH, TruthBodyInputSchema, TruthCommitError, TruthCommitResponseSchema, TruthRecordKeySchema, TruthRecordMetadataSchema, TruthWriteRequestSchema, authenticateBearer, authenticateDeviceProof, createAuthPlane, createByokCloud, createHmacTokenSigner, createInMemoryBlobs, createInMemoryByokCloud, createInMemoryCloudStores, createWebCrypto, declares, extractBearerToken, fullCapabilityDeclaration, handleInboundEnvelope, isCloudError, isTruthCommitError, projectTerminalResult, routeKey, tenantStoresFor, terminalReceiptKey, truthManifestMetadata, truthRecordMetadata, verifyNonceSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map