@byok-sdk/cloud 0.6.0 → 0.7.0

package/dist/stores/in-memory/agent-egress.d.ts

@@ -0,0 +1,12 @@
+import { type Clock, type TenantId } from '@byok-sdk/core';
+import type { AgentEgressRecord, AgentEgressStore } from '../ports';
+/** Reference egress fact store. Duplicate event ids return, never overwrite, the first receipt. */
+export declare class InMemoryAgentEgressStore implements AgentEgressStore {
+    #private;
+    constructor(clock: Clock);
+    record(tenant: TenantId, input: Omit<AgentEgressRecord, 'tenantId' | 'recordedAt'>): Promise<{
+        readonly record: AgentEgressRecord;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+}

package/dist/stores/in-memory/blobs.d.ts

@@ -28,7 +28,7 @@
  */
 import { type Clock, type ContentHash, type ObjectStore, type StorageReservation, type TenantId } from '@byok-sdk/core';
 import type { CloudCrypto } from '../../crypto/port';
-import type { BlobContent, BlobContentProxy, BlobObservation, BlobWriteResult, CloudBlobStore } from '../ports';
+import type { BlobContentProxy, BlobObservation, BlobReadResult, BlobWriteResult, CloudBlobStore } from '../ports';
 /** How long a presigned upload/download URL stays valid. */
 export declare const BLOB_URL_TTL_MS: number;
 interface BlobRecord {
@@ -78,7 +78,13 @@ export declare class InMemoryBlobContentProxy implements BlobContentProxy {
     constructor(registry: InMemoryBlobRegistry);
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
     writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
-    readContent(blobId: string): Promise<BlobContent | undefined>;
+    /**
+     * Never returns `{ok:false}`: this composition holds the bytes in the same
+     * process, so there is no upstream to be unreachable and no stream to be
+     * interrupted. Both `BlobReadErrorCode`s are structurally unreachable here
+     * — a proxy that fetches from object storage is where they become live.
+     */
+    readContent(blobId: string): Promise<BlobReadResult | undefined>;
 }
 /** Both halves over one registry. The only way to obtain either. */
 export interface InMemoryBlobs {

package/dist/stores/in-memory/device-directory.d.ts

@@ -14,6 +14,10 @@ export declare class InMemoryDeviceDirectory implements DeviceDirectory {
     register(tenant: TenantId, input: DeviceRegistration): Promise<DeviceRecord>;
     get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
     revoke(tenant: TenantId, deviceId: string): Promise<void>;
+    recordCapabilities(tenant: TenantId, input: {
+        readonly deviceId: string;
+        readonly capabilities: readonly string[];
+    }): Promise<DeviceRecord | undefined>;
     list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
     readiness(tenant: TenantId, presence: PresenceStore): Promise<TenantReadiness>;
     resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;

package/dist/stores/in-memory/index.d.ts

@@ -22,6 +22,7 @@ export { InMemoryTaskAttemptStore } from './task-attempts';
 export { InMemoryTaskCancellationStore } from './task-cancellations';
 export { InMemoryActivityStore } from './activity';
 export { InMemoryApprovalTimelineStore } from './approval-timeline';
+export { InMemoryAgentEgressStore } from './agent-egress';
 /**
  * The port bundle plus the byte proxy, in the shape `createInMemoryCoreStores`
  * already uses: the composition is an object with a `stores` field, not the

package/dist/stores/in-memory/task-attempts.d.ts

@@ -16,14 +16,23 @@
  * unfalsifiable.
  */
 import { type Clock, type TenantId } from '@byok-sdk/core';
-import type { TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '../ports';
+import type { AgentRef, TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '../ports';
 export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
     #private;
     constructor(clock: Clock, state?: InMemoryTaskAttemptState);
     open(tenant: TenantId, input: {
-        taskId: string;
-        deviceId: string;
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly agentRef?: AgentRef;
     }): Promise<TaskAttempt>;
+    reserveAgentOffer(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly agentRef: AgentRef;
+    }): Promise<{
+        readonly attempt: TaskAttempt;
+        readonly created: boolean;
+    }>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(tenant: TenantId, input: {
@@ -31,8 +40,10 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
         deviceId: string;
     }): Promise<TaskAttempt | undefined>;
     recordStatus(tenant: TenantId, input: {
-        taskId: string;
-        status: TaskAttemptStatus;
+        readonly taskId: string;
+        readonly status: TaskAttemptStatus;
+        readonly agentRef?: AgentRef;
+        readonly terminalCause?: string;
     }): Promise<TaskAttempt | undefined>;
 }
 /** Shared mutable state for the task and cancellation reference ports. */

package/dist/stores/ports.d.ts

@@ -35,6 +35,8 @@
  * bytes (see the blobs section below).
  */
 import type { MailboxBody, MailboxMessage, PresenceStore, StorageReservation, TenantId, TenantReadiness } from '@byok-sdk/core';
+import type { AgentEgressReliablePayload, AgentRef } from '@byok-sdk/protocol';
+export type { AgentEgressReliablePayload, AgentRef } from '@byok-sdk/protocol';
 import type { ActivityStore } from '../activity';
 import type { ApprovalTimelineStore } from '../approval-timeline';
 export interface DeviceRecord {
@@ -49,6 +51,12 @@ export interface DeviceRecord {
     /** Current proof signing-key rotation generation. */
     readonly proofKeyEpoch: number;
     readonly revoked: boolean;
+    /**
+     * The latest capability snapshot written by an authenticated device
+     * handshake. This is deliberately separate from core presence: presence is
+     * lossy/TTL-bounded and cannot authorize Agent dispatch.
+     */
+    readonly capabilities?: readonly string[];
 }
 /** Everything `POST /byok/pair` knows at registration time. `tenantId` is the store's first parameter; `revoked` is the store's own to set. */
 export interface DeviceRegistration {
@@ -67,6 +75,15 @@ export interface DeviceDirectory {
     list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
     /** Set-wise tenant observation; revoked devices never contribute presence. */
     readiness(tenant: TenantId, presence: PresenceStore): Promise<TenantReadiness>;
+    /**
+     * Persist a capability snapshot obtained from an authenticated device
+     * message. Implementations may return `undefined` for an unknown/revoked
+     * device; callers must fail closed in that case.
+     */
+    recordCapabilities(tenant: TenantId, input: {
+        readonly deviceId: string;
+        readonly capabilities: readonly string[];
+    }): Promise<DeviceRecord | undefined>;
     /** Pre-tenant. Two callers only: `POST /byok/challenge` and `POST /byok/token`. Never exposed through the tenant facade. */
     resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;
 }
@@ -124,9 +141,13 @@ export interface TaskAttempt {
     readonly taskId: string;
     /** The device the offer was addressed to. */
     readonly deviceId: string;
-    /** Set by `task.claim`, and only by the first one. Until then the task has no owner and the gate lets any of this tenant's devices through, matching the reference server. */
+    /** Exact Agent identity sealed when the strict Agent offer was opened. */
+    readonly agentRef?: AgentRef;
+    /** Set by `task.claim`, and only by the first one. Legacy attempts remain claimable by any tenant device until then; strict Agent attempts are target-device bound before this field is consulted. */
     readonly ownerDeviceId?: string;
     readonly status: TaskAttemptStatus;
+    /** Runtime-reported terminal cause from the first winning terminal. */
+    readonly terminalCause?: string;
     /** Durable host cancellation authority. Its presence outranks later device terminal receipts. */
     readonly cancellation?: {
         readonly requestedAt: string;
@@ -139,7 +160,20 @@ export interface TaskAttemptStore {
     open(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly agentRef?: AgentRef;
     }): Promise<TaskAttempt>;
+    /**
+     * Atomically reserve one strict Agent offer. `created: false` means the task
+     * id already had durable authority and no caller may append another offer.
+     */
+    reserveAgentOffer(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly agentRef: AgentRef;
+    }): Promise<{
+        readonly attempt: TaskAttempt;
+        readonly created: boolean;
+    }>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     /** Batch lookup used by mailbox projection; implementations must not turn one poll into N queries. */
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
@@ -152,6 +186,8 @@ export interface TaskAttemptStore {
     recordStatus(tenant: TenantId, input: {
         readonly taskId: string;
         readonly status: TaskAttemptStatus;
+        readonly agentRef?: AgentRef;
+        readonly terminalCause?: string;
     }): Promise<TaskAttempt | undefined>;
 }
 export interface TaskCancellationRequest {
@@ -195,6 +231,22 @@ export interface RequestReceiptStore {
     }>;
     get(tenant: TenantId, key: string): Promise<RequestReceipt | undefined>;
 }
+export interface AgentEgressRecord {
+    readonly tenantId: TenantId;
+    readonly deviceId: string;
+    readonly payload: AgentEgressReliablePayload;
+    /** Stable cloud-generated receipt identity echoed on every exact replay. */
+    readonly receiptId: string;
+    readonly recordedAt: string;
+}
+export interface AgentEgressStore {
+    /** First event-id write wins; callers reject mismatches rather than updating. */
+    record(tenant: TenantId, input: Omit<AgentEgressRecord, 'tenantId' | 'recordedAt'>): Promise<{
+        readonly record: AgentEgressRecord;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+}
 export interface ProofRequestReceipt {
     readonly tenantId: TenantId;
     readonly deviceId: string;
@@ -241,6 +293,35 @@ export interface BlobContent {
     readonly data: Uint8Array;
     readonly contentType: string;
 }
+/**
+ * How a byte-proxying read can fail while the blob itself is known to exist.
+ *
+ * The split is about WHERE the failure landed relative to the upstream
+ * response, because that is the only part a proxy can observe and the only
+ * part an operator can act on: `blob_upstream_unavailable` means nothing came
+ * back at all (the upstream was unreachable/refused before its response
+ * started), so a retry may succeed unchanged; `blob_upstream_stream_interrupted`
+ * means the response HAD started and died mid-transfer, so whatever the caller
+ * already has is a truncated prefix, not a short blob.
+ *
+ * Both are 502 on the wire (see `BLOB_READ_ERROR_HTTP_STATUS` in
+ * `handlers/blobs.ts`) — the CODE carries the distinction, not the status.
+ */
+export declare const BLOB_READ_ERROR_CODES: readonly ['blob_upstream_unavailable', 'blob_upstream_stream_interrupted'];
+export type BlobReadErrorCode = (typeof BLOB_READ_ERROR_CODES)[number];
+/**
+ * The result of {@link BlobContentProxy.readContent}, in the same union idiom
+ * as {@link BlobWriteResult}. Note what is NOT in here: not-found stays
+ * `undefined` at the method's return type, so "no such blob" keeps its
+ * existing 404 meaning and never has to be spelled as a failure code.
+ */
+export type BlobReadResult = {
+    readonly ok: true;
+    readonly content: BlobContent;
+} | {
+    readonly ok: false;
+    readonly code: BlobReadErrorCode;
+};
 /**
  * The capability-minting half of blobs: what EVERY composition can honestly
  * provide, whoever holds the bytes.
@@ -289,7 +370,8 @@ export interface CloudBlobStore {
 export interface BlobContentProxy {
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
     writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
-    readContent(blobId: string): Promise<BlobContent | undefined>;
+    /** `undefined` = no such blob (404); a `{ok:false}` result = the blob exists but its bytes could not be proxied (502, distinguished by {@link BlobReadErrorCode}). */
+    readContent(blobId: string): Promise<BlobReadResult | undefined>;
 }
 /**
  * Step 0 of the inbound gate. S3a ships an allow-all reference (a hosted
@@ -317,10 +399,11 @@ export interface CloudStores {
     readonly tasks: TaskAttemptStore;
     readonly cancellations: TaskCancellationStore;
     readonly receipts: RequestReceiptStore;
+    readonly egress: AgentEgressStore;
     readonly proofReceipts: ProofRequestReceiptStore;
     readonly blobs: CloudBlobStore;
     readonly rateLimiter: InboundRateLimiter;
 }
 /** Names of every port in {@link CloudStores}, in contract order. */
-export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'nonces', 'dedup', 'tasks', 'cancellations', 'receipts', 'proofReceipts', 'blobs', 'rateLimiter'];
+export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'nonces', 'dedup', 'tasks', 'cancellations', 'receipts', 'egress', 'proofReceipts', 'blobs', 'rateLimiter'];
 export type CloudStoreName = (typeof CLOUD_STORE_NAMES)[number];

package/dist/tenant-stores.d.ts

@@ -24,7 +24,7 @@
 import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardUnclaimInput, type CoreStores, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type Principal, type PresenceHint, type PresenceHintInput, type TenantReadiness, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type TenantId } from '@byok-sdk/core';
 import type { ActivityAppendInput, ActivityTail } from './activity';
 import type { ApprovalTimelineAppendInput, ApprovalTimelineTail } from './approval-timeline';
-import type { BlobObservation, CloudStores, DeviceRecord, RequestReceipt, TaskCancellationMutation, TaskCancellationRequest, TaskAttempt, TaskAttemptStatus } from './stores/ports';
+import type { BlobObservation, CloudStores, DeviceRecord, AgentEgressRecord, RequestReceipt, TaskCancellationMutation, TaskCancellationRequest, TaskAttempt, TaskAttemptStatus } from './stores/ports';
 export interface TenantBoundMailbox {
     append(input: MailboxAppendInput): Promise<MailboxMessage>;
     /** Pure read. Never advances the cursor — the daemon's next poll is the only ack. */
@@ -57,13 +57,26 @@ export interface TenantBoundDevices {
     get(deviceId: string): Promise<DeviceRecord | undefined>;
     list(): Promise<readonly DeviceRecord[]>;
     revoke(deviceId: string): Promise<void>;
+    /** Persist the authenticated device's own capability snapshot. */
+    recordCapabilities(input: {
+        readonly capabilities: readonly string[];
+    }): Promise<DeviceRecord | undefined>;
     readiness(): Promise<TenantReadiness>;
 }
 export interface TenantBoundTaskAttempts {
     open(input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly agentRef?: TaskAttempt['agentRef'];
     }): Promise<TaskAttempt>;
+    reserveAgentOffer(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly agentRef: NonNullable<TaskAttempt['agentRef']>;
+    }): Promise<{
+        readonly attempt: TaskAttempt;
+        readonly created: boolean;
+    }>;
     get(taskId: string): Promise<TaskAttempt | undefined>;
     getMany(taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(input: {
@@ -73,6 +86,8 @@ export interface TenantBoundTaskAttempts {
     recordStatus(input: {
         readonly taskId: string;
         readonly status: TaskAttemptStatus;
+        readonly agentRef?: TaskAttempt['agentRef'];
+        readonly terminalCause?: TaskAttempt['terminalCause'];
     }): Promise<TaskAttempt | undefined>;
 }
 export interface TenantBoundTaskCancellations {
@@ -91,6 +106,13 @@ export interface TenantBoundReceipts {
     }>;
     get(key: string): Promise<RequestReceipt | undefined>;
 }
+export interface TenantBoundAgentEgress {
+    record(input: Omit<AgentEgressRecord, 'tenantId' | 'recordedAt'>): Promise<{
+        readonly record: AgentEgressRecord;
+        readonly created: boolean;
+    }>;
+    get(deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+}
 export interface TenantBoundBlobs {
     createUpload(reservation: StorageReservation): Promise<{
         readonly blobId: string;
@@ -121,6 +143,7 @@ export interface TenantStores {
     readonly cancellations: TenantBoundTaskCancellations;
     readonly dedup: TenantBoundDedup;
     readonly receipts: TenantBoundReceipts;
+    readonly egress: TenantBoundAgentEgress;
     readonly blobs: TenantBoundBlobs;
     readonly quota: TenantBoundQuota;
     readonly rateLimiter: TenantBoundRateLimiter;

package/dist/terminal-result.d.ts

@@ -1,4 +1,4 @@
-import { type BlobRef, type TerminalInferenceUsage } from '@byok-sdk/protocol';
+import { type AgentRef, type BlobRef, type TerminalInferenceUsage } from '@byok-sdk/protocol';
 import type { RequestReceipt } from './stores/ports';
 /**
  * The typed terminal read model — the hosted counterpart of the embedded
@@ -10,6 +10,8 @@ import type { RequestReceipt } from './stores/ports';
 export interface TerminalResult {
     readonly taskId: string;
     readonly state: 'complete' | 'failed' | 'cancelled';
+    /** Exact Agent identity echoed by the winning terminal, when Agent-bound. */
+    readonly agentRef?: AgentRef;
     readonly summary?: string;
     readonly sessionRef?: string;
     readonly artifactRefs?: readonly BlobRef[];
@@ -27,6 +29,8 @@ export interface TerminalResult {
      */
     readonly usage?: TerminalInferenceUsage;
     readonly reason?: string;
+    /** Terminal cause projection; currently the protocol's terminal reason. */
+    readonly terminalCause?: string;
     readonly retryable?: boolean;
     /** When the receipt store wrote the terminal fact — the first one, by its own first-write-wins rule. */
     readonly recordedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "BYOK SDK hosted device surface: stateless frozen-v1 HTTP handlers over tenant-first @byok-sdk/core ports",
   "type": "module",
   "license": "MIT",
@@ -44,8 +44,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@byok-sdk/core": "0.6.0",
-    "@byok-sdk/protocol": "0.6.0",
+    "@byok-sdk/core": "0.7.0",
+    "@byok-sdk/protocol": "0.7.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }