@byok-sdk/cloud 0.2.0 → 0.4.0

package/README.md

@@ -4,6 +4,49 @@ 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:
+
+```ts
+await cloud.enqueueToolsetOffer(tenantId, deviceId, {
+  taskId,
+  payload: {
+    instruction: 'Research the account and prepare the next sales action.',
+    runtime: 'claude',
+    policy: { mode: 'auto' },
+    requiredToolsets: ['salesko.prospecting'],
+  },
+});
+```
+
+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`. `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.
+
+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.19.0 or newer.

package/dist/auth/verify.d.ts

@@ -1,22 +1,3 @@
-/**
- * The one nonce-signature check on the hosted surface (docs/protocol.md §6.2).
- *
- * S1 (GAP-004): a device signs `byok-nonce-v1\n` + nonce, never the bare
- * nonce. The device key is a long-lived identity key that later planes (S6
- * device proof) also sign structured messages with; without a domain tag, a
- * signature produced for one purpose is a valid signature for another.
- *
- * Applying the domain HERE rather than at the call site is the point: there
- * is exactly one place that decides what a device signature over a nonce
- * means, so no route can be written that accepts the undomained form. There
- * is deliberately no dual mode and no grace window — a device on the old
- * encoding re-pairs.
- *
- * The literal is byte-identical to `@byok-sdk/server`'s `NONCE_SIGNING_DOMAIN`
- * and to what the daemon signs (`packages/client/src/daemon/device-keys.ts`),
- * because the daemon must not be able to tell self-hosted from hosted. Parity
- * is asserted by behavior tests, never by importing the server.
- */
 import type { CloudCrypto } from '../crypto/port';
-export declare const NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+export { NONCE_SIGNING_DOMAIN } from '@byok-sdk/core';
 export declare function verifyNonceSignature(crypto: CloudCrypto, devicePublicKey: string, nonce: string, signature: string): Promise<boolean>;

package/dist/capabilities.d.ts

@@ -49,6 +49,18 @@ export declare const CLOUD_CAPABILITIES: {
     readonly activityTail: 'activity.tail';
     /** Request-bound device proof record manifest/read/write surface (S6). */
     readonly truthRecords: 'truth.records';
+    /**
+     * Tenant-scoped skill pack distribution: the manifest list plus the per-file
+     * content route a paired device installs from.
+     *
+     * Hosted HTTP on purpose. A pack is DECLARATIVE CONTENT a device pulls after
+     * reading this declaration — not a message — so `@byok-sdk/protocol` gains
+     * nothing from it and the frozen v1 envelope stays untouched. Composition-
+     * bound like `truth.records`: a deployment that declares it without supplying
+     * a `SkillPackStore` is refused at construction rather than publishing two
+     * routes it would then 404.
+     */
+    readonly skillPacks: 'skills.pack';
 };
 export type CloudCapability = (typeof CLOUD_CAPABILITIES)[keyof typeof CLOUD_CAPABILITIES];
 /** The wire DTO for `GET /byok/capabilities` — core's shape, bound to a cloud-owned route. */
@@ -65,6 +77,12 @@ export interface FullCapabilityDeclarationOptions {
      * composition cannot truthfully promise a cross-store atomic commit.
      */
     readonly includeTruthRecords?: boolean;
+    /**
+     * `skills.pack` is omitted for the same reason: the standard composition is
+     * given no `SkillPackStore`, and a default-on declaration would make every
+     * existing deployment refuse to construct.
+     */
+    readonly includeSkillPacks?: boolean;
 }
 /** Every capability the standard composition can serve, plus explicitly wired composition-bound ones. */
 export declare function fullCapabilityDeclaration(version?: number, options?: FullCapabilityDeclarationOptions): CapabilityDeclaration;

package/dist/cloud.d.ts

@@ -14,12 +14,13 @@
  * quietly undo that — a Running/session map — is asserted absent by
  * `src/__tests__/constraints.test.ts`.
  */
-import { type ActivityTail, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type TenantId } from '@byok-sdk/core';
-import { type Envelope, type TaskOfferPayload } from '@byok-sdk/protocol';
+import { type ActivityTail, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type SkillPackStore, type TenantId } from '@byok-sdk/core';
+import { type Envelope, type TaskOfferPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
 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;
@@ -45,6 +46,14 @@ export interface ByokCloudOptions {
     readonly truthCommitter?: TruthCommitter;
     /** Content-hash keyed object GET grants for object-backed truth bodies. */
     readonly truthObjectDownloads?: TruthObjectDownloads;
+    /**
+     * Tenant-scoped skill pack catalogue. OPTIONAL, and absent is a first-class
+     * answer: a deployment that distributes no declarative content supplies
+     * nothing here and declares no `skills.pack`. Supplying it is necessary but
+     * not sufficient for the routes to exist — the deployment must also declare
+     * the capability (ADR-010), the same asymmetry the byte proxy above has.
+     */
+    readonly skillPacks?: SkillPackStore;
     readonly crypto: CloudCrypto;
     readonly tokenSigner: TokenSigner;
     readonly clock: Clock;
@@ -71,12 +80,19 @@ export interface ByokCloudOptions {
     readonly activityCapacity?: number;
     readonly activityTtlMs?: number;
     readonly maxTruthRequestBytes?: number;
+    readonly skillPackPageLimit?: number;
 }
 export interface EnqueueOfferInput {
     /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
     readonly taskId?: string;
     readonly payload: TaskOfferPayload;
 }
+export interface EnqueueToolsetOfferInput {
+    /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
+    readonly taskId?: string;
+    /** Strict control payload containing logical ids only; executable MCP definitions are not part of this type. */
+    readonly payload: TaskOfferWithToolsetsPayload;
+}
 export interface EnqueuedOffer {
     readonly taskId: string;
     /** The per-(tenant, device) delivery seq — the daemon's redelivery cursor position for this envelope. */
@@ -107,9 +123,24 @@ export interface ByokCloud {
     }): Promise<PairingCodeInfo>;
     /** Host control plane: hand a device a frozen-v1 `task.offer`. The hosted replacement for `dispatch()` — a function, not a handle. */
     enqueueOffer(tenant: TenantId, deviceId: string, input: EnqueueOfferInput): Promise<EnqueuedOffer>;
+    /** Host control plane: enqueue the additive fail-closed offer variant that requires local MCP toolsets. */
+    enqueueToolsetOffer(tenant: TenantId, deviceId: string, input: EnqueueToolsetOfferInput): Promise<EnqueuedOffer>;
     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/composition/in-memory.d.ts

@@ -7,7 +7,7 @@
  * cannot tell this from `@byok-sdk/server`, and nothing in the path needs a
  * database to prove it.
  */
-import { type Clock, type CapabilityDeclaration, type CoreStores } from '@byok-sdk/core';
+import { type CapabilityDeclaration, type Clock, type CoreStores, type SkillPackStore } from '@byok-sdk/core';
 import { type TokenSigner } from '../auth/tokens';
 import type { CloudCrypto } from '../crypto/port';
 import { type ByokCloud } from '../cloud';
@@ -41,6 +41,14 @@ export interface InMemoryByokCloudOptions {
     readonly truthCommitter?: TruthCommitter;
     readonly truthObjectDownloads?: TruthObjectDownloads;
     readonly maxTruthRequestBytes?: number;
+    /**
+     * Host/test supplied skill pack catalogue. Absent by default, and
+     * `fullCapabilityDeclaration()` withholds `skills.pack` to match — a
+     * composition that declared a channel it has no store for would be refused at
+     * construction, which would break every existing in-memory deployment.
+     */
+    readonly skillPacks?: SkillPackStore;
+    readonly skillPackPageLimit?: number;
 }
 export interface InMemoryByokCloud {
     readonly cloud: ByokCloud;

package/dist/errors.d.ts

@@ -13,11 +13,9 @@ export declare const CLOUD_ERROR_CODES: {
     /** The composition handed a device row whose tenant is not a mintable `TenantId`. */
     readonly device_tenant_invalid: 'device_tenant_invalid';
     /**
-     * The mailbox assigned a row `seq` that disagrees with the delivery `seq`
-     * baked into the enqueued envelope. Loud rather than silent: those two
-     * numbers ARE the daemon's redelivery cursor, and a composition whose
-     * mailbox numbers rows differently from `DeviceSequenceStore` would
-     * mis-deliver every subsequent poll.
+     * The mailbox committed a row `seq` that disagrees with the delivery `seq`
+     * its body factory baked into the envelope. Loud rather than silent: those
+     * two numbers ARE the daemon's redelivery cursor.
      */
     readonly mailbox_seq_mismatch: 'mailbox_seq_mismatch';
     /** A capability declaration the host supplied that core refused. */
@@ -34,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/handlers/skill-packs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `GET /byok/skill-packs` and `GET /byok/skill-packs/:name/files/:path` — the
+ * hosted half of the skill-pack delivery channel.
+ *
+ * Two device-class reads, and nothing else. There is no publish route here on
+ * purpose: a device is a CONSUMER of packs, and a device-bearer-authed write
+ * would let any paired device in a tenant publish content to every other device
+ * in it. Publication is a host control-plane action against the store directly,
+ * exactly as board item creation is.
+ *
+ * Both routes answer 404 for a pack this tenant does not have — the same answer
+ * a name that never existed anywhere gets — so the surface is not a
+ * cross-tenant existence oracle. The store is tenant-first, so that property
+ * comes from the lookup key rather than from a comparison a handler could
+ * forget.
+ *
+ * Bytes travel as UTF-8 text inside JSON. A pack carries Markdown, YAML and
+ * static text; there is no archive to unpack and no binary channel to
+ * negotiate, which is the same reason the manifest has no exec surface — the
+ * format cannot express the thing we do not want it to express.
+ */
+import { type SkillPackStore } from '@byok-sdk/core';
+import type { Context } from 'hono';
+import { type BearerAuthDeps } from '../auth/bearer';
+/** Rows per `GET /byok/skill-packs` response. A tenant's pack catalogue is small by design. */
+export declare const DEFAULT_SKILL_PACK_PAGE_LIMIT = 50;
+export interface SkillPackRouteDeps {
+    readonly bearer: BearerAuthDeps;
+    readonly skillPacks: SkillPackStore;
+    readonly pageLimit: number;
+}
+export declare function skillPackListHandler(deps: SkillPackRouteDeps): (c: Context) => Promise<Response>;
+export declare function skillPackFileHandler(deps: SkillPackRouteDeps): (c: Context) => Promise<Response>;

package/dist/handlers/truth.d.ts

@@ -1,7 +1,8 @@
+import { DEVICE_PROOF_HEADER } from '@byok-sdk/core';
 import type { Context } from 'hono';
 import { type DeviceProofAuthDeps } from '../auth/device-proof';
 import { type TruthCommitter, type TruthObjectDownloads } from '../truth/contract';
-export declare const DEVICE_PROOF_HEADER = "x-byok-device-proof";
+export { DEVICE_PROOF_HEADER };
 export declare const DEFAULT_MAX_TRUTH_REQUEST_BYTES: number;
 export declare const MAX_DEVICE_PROOF_HEADER_BYTES: number;
 export interface TruthRouteDeps {

package/dist/index.d.ts

@@ -15,9 +15,10 @@
 export { isTenantId, tenantId } from '@byok-sdk/core';
 export type { TenantId } from '@byok-sdk/core';
 export { createByokCloud } from './cloud';
-export type { ByokCloud, ByokCloudOptions, EnqueueOfferInput, EnqueuedOffer } from './cloud';
+export type { ByokCloud, ByokCloudOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, EnqueuedOffer, } from './cloud';
 export { DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, } from './cloud';
 export { DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, } from './handlers/board';
+export { DEFAULT_SKILL_PACK_PAGE_LIMIT } from './handlers/skill-packs';
 export { createInMemoryByokCloud } from './composition/in-memory';
 export type { InMemoryByokCloud, InMemoryByokCloudOptions } from './composition/in-memory';
 export { ByokCloudError, CLOUD_ERROR_CODES, isCloudError } from './errors';
@@ -39,8 +40,10 @@ 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, TenantBoundSequence, TenantBoundTaskAttempts, TenantStores, } 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';
 export type { ActivityBounds } from './coordination';
 export { BoardFeedClient, BoardFeedRetryableError, BoardFeedStoppedError } from './coordination-client';
@@ -52,6 +55,6 @@ export { TruthCommitError, isTruthCommitError } from './truth/errors';
 export type { TruthCommitErrorCode } from './truth/errors';
 export { CLOUD_STORE_NAMES, TASK_ATTEMPT_STATUSES } from './stores/ports';
 export { CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS } from './stores/ports-contract';
-export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, DeviceSequenceStore, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptStatus, TaskAttemptStore, } from './stores/ports';
-export { AllowAllRateLimiter, BLOB_URL_TTL_MS, DEDUP_RING_CAPACITY, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryDeviceDirectory, InMemoryDeviceSequenceStore, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryRequestReceiptStore, InMemoryProofRequestReceiptStore, InMemoryTaskAttemptStore, NONCE_TTL_MS, createInMemoryBlobs, createInMemoryCloudStores, } from './stores/in-memory/index';
+export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptStatus, TaskAttemptStore, } from './stores/ports';
+export { AllowAllRateLimiter, BLOB_URL_TTL_MS, DEDUP_RING_CAPACITY, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryRequestReceiptStore, InMemoryProofRequestReceiptStore, InMemoryTaskAttemptStore, NONCE_TTL_MS, createInMemoryBlobs, createInMemoryCloudStores, } from './stores/in-memory/index';
 export type { InMemoryBlobStoreOptions, InMemoryBlobs, InMemoryCloudComposition, } from './stores/in-memory/index';