@byok-sdk/cloud 0.11.0 → 0.13.0

package/dist/steer-control.d.ts

@@ -0,0 +1,81 @@
+/**
+ * GAP-2: why a `cloud.steerTask` call was refused, and the one input that
+ * decides it.
+ *
+ * The reference server (`ConnectionHub.steerTask`, `packages/server/src/hub.ts`)
+ * reaches this decision from `TaskSnapshot.claimedRuntimeCapabilities` — the
+ * capability block the CLAIMING adapter reported for itself on its own
+ * `task.claim`, frozen at the `Offered -> Claimed` transition. Cloud keeps the
+ * same single source: {@link TaskAttempt.claimedRuntimeCapabilities}, written by
+ * the claim that wins the ownership CAS (`stores/ports.ts`) and never again.
+ *
+ * The gap this closes is not cosmetic: only pi's adapter implements steering,
+ * and Claude's and Codex's THROW on receiving `task.steer`, which stalls that
+ * device's redelivery cursor at that seq forever. So the refusal has to happen
+ * before an envelope exists, from a fact that shares a lifecycle with the
+ * task-to-runtime binding.
+ *
+ * Fail-closed on unknown, deliberately: `steer_unsupported_runtime` covers both
+ * "the claiming adapter reported `steer: false`" and "this attempt carries no
+ * capability snapshot at all" (a daemon whose claim predates the field, an
+ * attempt claimed before migration `0018`). Refusing an unknown is a
+ * recoverable, operator-visible error; guessing "supported" reintroduces the
+ * permanent cursor stall this gate exists to prevent. There is deliberately NO
+ * runtime-id allow-list here either — a table mapping `pi -> steerable` would be
+ * a second capability authority in the coordination plane, drifting the moment a
+ * runtime gains or loses the feature, and the daemon already reports the truth.
+ *
+ * SINGLE SOURCE, deliberately: the gate reads the claim snapshot and NOTHING
+ * from the connection layer. Cloud's connection-level equivalent is
+ * `DeviceRecord.capabilities`, written from a bearer-authenticated `conn.hello`
+ * (`inbound.ts`) — discovery data describing a device BUILD, not the adapter
+ * that took this task. A device can reconnect later with a different adapter
+ * set; a task already running must keep being judged against what was true when
+ * it was claimed. Same pin the reference server holds in
+ * `packages/server/src/__tests__/steer-runtime-capability-gate.test.ts`.
+ */
+import type { RuntimeId } from '@byok-sdk/protocol';
+import type { TaskAttemptStatus } from './stores/ports';
+/**
+ * Stable strings a caller switches on (an operator UI, an HTTP surface mapping
+ * this to a status code) rather than matching error text. Byte-identical to the
+ * reference server's `SteerRejectionCode` (`packages/server/src/hub.ts`), so a
+ * host that moves from the embedded server to the hosted kernel keeps its own
+ * mapping unchanged.
+ *
+ * - `task_terminal` — the attempt already reached `complete`/`failed`/
+ *   `cancelled`. Checked FIRST, so a terminal attempt that is also (obviously)
+ *   not running reports the more specific truth, and a steer racing a terminal
+ *   transition always resolves terminal-first.
+ * - `task_not_running` — the attempt exists and is live, but is `offered`/
+ *   `claimed`/`cancel_requested`; there is no running turn to steer yet.
+ * - `steer_unsupported_runtime` — the runtime that CLAIMED this attempt cannot
+ *   be steered, per the claim-time capability snapshot. A MISSING snapshot
+ *   rejects under this same code: unknown is not supported.
+ */
+export type SteerRejectionCode = 'steer_unsupported_runtime' | 'task_not_running' | 'task_terminal';
+/**
+ * Thrown by `ByokCloud.steerTask` instead of a generic `Error`, so a caller can
+ * tell WHY a steer was refused without matching on message text — the same
+ * typed-error idiom as `StaleApprovalError` (`approval-control.ts`).
+ *
+ * A distinct class rather than a `CloudErrorCode`, for the same reason as
+ * `StaleApprovalError`: it carries the state and the runtime the caller needs to
+ * explain the refusal, and a code alone cannot.
+ *
+ * Thrown before any mailbox row is allocated — a refused steer is a NON-EVENT,
+ * exactly like a refused approval.
+ */
+export declare class SteerRejectedError extends Error {
+    readonly taskId: string;
+    readonly code: SteerRejectionCode;
+    /** The attempt's status at the moment the steer was refused. */
+    readonly status: TaskAttemptStatus;
+    /** {@link TaskAttempt.claimedRuntime} — `undefined` when nothing was ever recorded, which is itself a reason `steer_unsupported_runtime` can fire. */
+    readonly runtime: RuntimeId | undefined;
+    constructor(taskId: string, code: SteerRejectionCode, 
+    /** The attempt's status at the moment the steer was refused. */
+    status: TaskAttemptStatus, 
+    /** {@link TaskAttempt.claimedRuntime} — `undefined` when nothing was ever recorded, which is itself a reason `steer_unsupported_runtime` can fire. */
+    runtime: RuntimeId | undefined);
+}

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

@@ -8,5 +8,5 @@ export declare class InMemoryAgentEgressStore implements AgentEgressStore {
         readonly record: AgentEgressRecord;
         readonly created: boolean;
     }>;
-    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+    get(tenant: TenantId, deviceId: string, agentRef: AgentEgressRecord['payload']['agentRef'], eventId: string): Promise<AgentEgressRecord | undefined>;
 }

package/dist/stores/in-memory/approval-timeline.d.ts

@@ -1,9 +1,10 @@
 import type { Clock, TenantId } from '@byok-sdk/core';
-import { type ApprovalTimelineAppendInput, type ApprovalTimelineStore, type ApprovalTimelineTail } from '../../approval-timeline';
+import { type ApprovalTimelineAppendInput, type ApprovalTimelineResolvePendingInput, type ApprovalTimelineResolvePendingResult, type ApprovalTimelineStore, type ApprovalTimelineTail } from '../../approval-timeline';
 export declare class InMemoryApprovalTimelineStore implements ApprovalTimelineStore {
     #private;
     private readonly clock;
     constructor(clock: Clock);
     append(tenant: TenantId, input: ApprovalTimelineAppendInput): Promise<ApprovalTimelineTail>;
+    resolvePending(tenant: TenantId, input: ApprovalTimelineResolvePendingInput): Promise<ApprovalTimelineResolvePendingResult>;
     read(tenant: TenantId, taskId: string): Promise<ApprovalTimelineTail | undefined>;
 }

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

@@ -77,6 +77,7 @@ export declare class InMemoryBlobContentProxy implements BlobContentProxy {
     #private;
     constructor(registry: InMemoryBlobRegistry);
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
+    expectedUploadBytes(blobId: string): Promise<bigint | undefined>;
     writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
     /**
      * Never returns `{ok:false}`: this composition holds the bytes in the same

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

@@ -1,17 +1,20 @@
 /**
  * In-memory {@link InboundDedupStore} (N3).
  *
- * A bounded ring per (tenant, device), not an unbounded set: the wire is
- * at-least-once (§9), so this makes processing at-most-once without letting a
- * chatty device grow memory without limit. Check-and-record is one call, so a
- * composition cannot accidentally split it into a racy read-then-write.
+ * A bounded ring per physical (tenant, device) or strict (tenant, device,
+ * AgentRef) fact, not an unbounded set: the wire is at-least-once (§9), so
+ * this makes processing at-most-once without letting a chatty device or Agent
+ * grow memory without limit. Check-and-record is one call, so a composition
+ * cannot accidentally split it into a racy read-then-write.
  */
 import { type TenantId } from '@byok-sdk/core';
+import type { AgentRef } from '@byok-sdk/protocol';
 import type { InboundDedupStore } from '../ports';
-/** Ids retained per device. Same order of magnitude as the reference server's ring. */
+/** Ids retained per physical or Agent-bound key. Same depth as the reference server's ring. */
 export declare const DEDUP_RING_CAPACITY = 1024;
 export declare class InMemoryInboundDedupStore implements InboundDedupStore {
     #private;
     constructor(capacity?: number);
     checkAndRecord(tenant: TenantId, deviceId: string, envelopeId: string): Promise<boolean>;
+    checkAndRecordAgent(tenant: TenantId, deviceId: string, agentRef: AgentRef, envelopeId: string): Promise<boolean>;
 }

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

@@ -17,6 +17,5 @@ export declare class InMemoryNonceStore implements NonceStore {
     /** Number of records currently held (post-sweep). Test-facing only. */
     get size(): number;
     issue(tenant: TenantId, deviceId: string): Promise<string>;
-    validate(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
-    markUsed(tenant: TenantId, nonce: string): Promise<void>;
+    consumeIfValid(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
 }

package/dist/stores/in-memory/pairing-codes.d.ts

@@ -2,17 +2,21 @@
  * In-memory {@link PairingCodeStore}: single-use codes bound to the tenant and
  * product they were minted for.
  *
- * `redeem` answers `undefined` for unknown, expired, and already-used alike.
+ * Enrollment answers `undefined` for unknown, expired, and already-used alike.
  * The reference server distinguishes those three in its 401 text; a hosted,
  * multi-tenant surface deliberately does not — the code is a bearer credential
  * addressable across every tenant, and "already used" versus "never existed"
  * is exactly the difference an attacker enumerating codes would pay for.
+ *
+ * Code issuance and enrollment project this one authority into separate ports.
+ * The enrollment path serializes each code through registration and flips
+ * `used` only after its shared device directory has accepted the row.
  */
 import type { Clock, TenantId } from '@byok-sdk/core';
-import type { PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '../ports';
-export declare class InMemoryPairingCodeStore implements PairingCodeStore {
+import type { DeviceDirectory, DeviceRecord, PairingEnrollment, PairingEnrollmentInput, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '../ports';
+export declare class InMemoryPairingCodeStore implements PairingCodeStore, PairingEnrollment {
     #private;
-    constructor(clock: Clock);
+    constructor(clock: Clock, devices: DeviceDirectory);
     issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
-    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+    redeemAndRegister(input: PairingEnrollmentInput): Promise<DeviceRecord | undefined>;
 }

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

@@ -16,7 +16,11 @@
  * unfalsifiable.
  */
 import { type Clock, type TenantId } from '@byok-sdk/core';
-import type { AgentRef, TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '../ports';
+import type { RuntimeCapabilities, RuntimeId } from '@byok-sdk/protocol';
+import { type AgentMessageAdmission, type AgentRef, type TaskAttempt, type TaskAttemptListQuery, type TaskAttemptPage, type TaskAttemptStatus, type TaskAttemptStore } from '../ports';
+interface StoredAgentMessageAdmission extends AgentMessageAdmission {
+    readonly deviceId: string;
+}
 export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
     #private;
     constructor(clock: Clock, state?: InMemoryTaskAttemptState);
@@ -33,11 +37,33 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    reserveAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    finalizeAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
+    list(tenant: TenantId, query: TaskAttemptListQuery): Promise<TaskAttemptPage>;
     claim(tenant: TenantId, input: {
         taskId: string;
         deviceId: string;
+        runtime?: RuntimeId;
+        capabilities?: RuntimeCapabilities;
     }): Promise<TaskAttempt | undefined>;
     recordStatus(tenant: TenantId, input: {
         readonly taskId: string;
@@ -50,8 +76,10 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
 export declare class InMemoryTaskAttemptState {
     #private;
     readonly attempts: Map<string, TaskAttempt>;
+    readonly messageAdmissions: Map<string, StoredAgentMessageAdmission>;
     constructor(clock: Clock);
     now(): string;
     /** Serialize every state-changing operation for one tenant/task key. */
     mutate<T>(key: string, operation: () => T | Promise<T>): Promise<T>;
 }
+export {};

package/dist/stores/ports.d.ts

@@ -13,20 +13,18 @@
  * 1. **Async.** Every method returns a `Promise`, so a SQL or KV composition
  *    can implement the same contract the in-memory reference does.
  * 2. **Tenant-first.** Every method's first parameter is a required
- *    `TenantId` — with exactly two documented exceptions below, each of
- *    which is pre-tenant *by construction* because the credential it is
- *    handed is itself what resolves the tenant.
+ *    `TenantId` — with one documented lookup exception below. Pairing code
+ *    consumption is a separate composition-owned enrollment operation: its
+ *    bearer code resolves the tenant internally and it returns only the
+ *    resulting device row.
  *
- * The two exceptions:
+ * The lookup exception:
  *
  * - {@link DeviceDirectory.resolveByDeviceId} — `POST /byok/challenge` and
  *   `POST /byok/token` carry only a deviceId (the pinned wire contract), and
  *   the row is what tells the deployment which tenant to mint for.
- * - {@link PairingCodeStore.redeem} — the code IS the tenant lookup; it was
- *   minted against a tenant that only the host's control plane knew.
- *
- * Neither is reachable through {@link TenantStores} (see `tenant-stores.ts`),
- * so a device-facing handler cannot call them.
+ * It is not reachable through {@link TenantStores} (see `tenant-stores.ts`),
+ * so a device-facing handler cannot call it.
  *
  * The byte-proxy trio that used to be a third pre-tenant exception is no
  * longer part of this bundle at all: it moved to {@link BlobContentProxy},
@@ -35,7 +33,7 @@
  * 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';
+import type { AgentEgressReliablePayload, AgentRef, RuntimeCapabilities, RuntimeId } from '@byok-sdk/protocol';
 export type { AgentEgressReliablePayload, AgentRef } from '@byok-sdk/protocol';
 import type { ActivityStore } from '../activity';
 import type { ApprovalTimelineStore } from '../approval-timeline';
@@ -151,33 +149,61 @@ export interface PairingCodeIssueInput {
 }
 export interface PairingCodeStore {
     issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
-    /**
-     * Validate and CONSUME a code, returning the claims it was minted with, or
-     * `undefined` when it is unknown, expired, or already used — one answer for
-     * all three, so a redeem attempt is never an existence oracle. Single-use is
-     * what makes the caller's "redeem, then register the device row" sequence
-     * exclusive: a second redeem can never reach the registration step.
-     */
-    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+}
+/**
+ * The pre-tenant facts a pairing request carries into enrollment. Tenant and
+ * product are deliberately absent: the guarded pairing-code row is their sole
+ * authority, and no caller can choose the registration scope.
+ */
+export interface PairingEnrollmentInput {
+    readonly pairingCode: string;
+    readonly deviceId: string;
+    readonly deviceName: string;
+    readonly devicePublicKey: string;
+    readonly proofKeyId: string;
+    readonly proofKeyEpoch: number;
+    readonly machineId?: string;
+}
+/**
+ * The only pairing-code consumption operation. Implementations atomically
+ * consume a valid code, apply machine supersession/state cleanup, and register
+ * the device; failures leave the code retryable. Unknown, expired, and already
+ * consumed codes all return `undefined`.
+ */
+export interface PairingEnrollment {
+    redeemAndRegister(input: PairingEnrollmentInput): Promise<DeviceRecord | undefined>;
 }
 export interface NonceStore {
     issue(tenant: TenantId, deviceId: string): Promise<string>;
-    /** `true` iff the nonce exists for this (tenant, device), is unexpired, and has not been consumed. Never mutates. */
-    validate(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
-    /** Consume the nonce. Called only after every other check on the request has passed. */
-    markUsed(tenant: TenantId, nonce: string): Promise<void>;
+    /**
+     * Atomically consume a nonce only when it belongs to this exact (tenant,
+     * device), is unexpired, and has not already been consumed. Returns `true`
+     * for the sole winner; every other case returns `false`.
+     */
+    consumeIfValid(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
 }
 export interface InboundDedupStore {
     /**
-     * `true` when `envelopeId` was already seen for this (tenant, device);
-     * otherwise records it and returns `false`. Bounded per device — the wire is
-     * at-least-once (§9); this makes processing at-most-once without an
-     * unbounded set.
+     * Device-physical envelope ledger (`conn.hello` and facts with no Agent
+     * binding). `true` when `envelopeId` was already seen for this (tenant,
+     * device); otherwise records it and returns `false`.
      */
     checkAndRecord(tenant: TenantId, deviceId: string, envelopeId: string): Promise<boolean>;
+    /**
+     * Agent-bound envelope ledger. The AgentRef is required: a same-device
+     * second Agent must never resolve or suppress this Agent's completed fact.
+     * Retention remains bounded per exact (tenant, device, AgentRef).
+     */
+    checkAndRecordAgent(tenant: TenantId, deviceId: string, agentRef: AgentRef, envelopeId: string): Promise<boolean>;
 }
 export declare const TASK_ATTEMPT_STATUSES: readonly ['offered', 'claimed', 'running', 'cancel_requested', 'complete', 'failed', 'cancelled'];
 export type TaskAttemptStatus = (typeof TASK_ATTEMPT_STATUSES)[number];
+/** The durable first-message reservation and, once present, its terminal disposition. */
+export interface AgentMessageAdmission {
+    readonly messageId: string;
+    readonly payloadBody: string;
+    readonly terminalBody?: string;
+}
 export interface TaskAttempt {
     readonly tenantId: TenantId;
     readonly taskId: string;
@@ -188,6 +214,40 @@ export interface TaskAttempt {
     /** 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;
+    /**
+     * The runtime the CLAIMING daemon reported for itself on its own
+     * `task.claim` (`TaskClaimPayload.runtime`), snapshotted at the
+     * `offered -> claimed` transition and never written again — a redelivered or
+     * losing claim leaves it exactly as the winning claim left it.
+     *
+     * ADR-028 forbids cloud holding EXECUTION state (a live `running`/`thinking`
+     * phase, a turn, a PID, the current tool call) — quantities that keep
+     * changing while an attempt runs. This is not one: it is written once, at
+     * the moment ownership is decided, and is an attribution fact about the
+     * attempt. Byte-for-byte the same semantics as the reference server's
+     * `TaskSnapshot.claimedRuntime` (`packages/server/src/types.ts`).
+     *
+     * Absent for a daemon whose `task.claim` carried no `runtime` at all.
+     */
+    readonly claimedRuntime?: RuntimeId;
+    /**
+     * The capability block the CLAIMING adapter reported for ITSELF on that same
+     * `task.claim` (`TaskClaimPayload.capabilities`), snapshotted under exactly
+     * the same write-once rule as {@link TaskAttempt.claimedRuntime}.
+     *
+     * This is the ONLY input to the steer gate (`steer-control.ts`,
+     * `ByokCloud.steerTask`). The connection-level snapshot cloud keeps —
+     * `DeviceRecord.capabilities`, written from `conn.hello`
+     * (`inbound.ts`) — describes a device BUILD and never feeds it: a device can
+     * reconnect later with a different adapter set, while a task that is already
+     * running must keep being judged against what was true when it was claimed.
+     * Same single-source rule the reference server pins
+     * (`packages/server/src/__tests__/steer-runtime-capability-gate.test.ts`).
+     *
+     * Absent for a daemon that predates the field, which the gate reads as
+     * "unknown" and refuses — unknown is not supported.
+     */
+    readonly claimedRuntimeCapabilities?: RuntimeCapabilities;
     /** Runtime-reported terminal cause from the first winning terminal. */
     readonly terminalCause?: string;
     /** Durable host cancellation authority. Its presence outranks later device terminal receipts. */
@@ -197,6 +257,43 @@ export interface TaskAttempt {
     };
     readonly updatedAt: string;
 }
+/**
+ * One bounded page request over a tenant's task attempts.
+ *
+ * Keyset-paged by `taskId` ASCENDING, deliberately, and NOT chronologically: an
+ * attempt carries no monotonic sequence, and `updatedAt` moves under an
+ * in-flight page (a status transition would re-order rows mid-walk and let a
+ * caller skip or repeat one). `taskId` is `task_<uuid>` — stable, unique per
+ * tenant, and never rewritten — so it is the only column that gives a walk the
+ * exactly-once property. The order is therefore arbitrary but TOTAL, which is
+ * what a paged read model needs; a caller that wants recency sorts a page
+ * itself.
+ *
+ * Adding a sequence column to get chronological order was rejected: it is a
+ * migration across every composition to serve a read-model nicety, and a second
+ * ordering authority to keep consistent with the row it decorates.
+ */
+export interface TaskAttemptListQuery {
+    /** Maximum attempts in the page. Required and fail-closed: a non-positive or non-integer limit is rejected, never silently defaulted or clamped. */
+    readonly limit: number;
+    /**
+     * The `nextCursor` from the previous page — opaque to the caller, and an
+     * EXCLUSIVE lower bound on `taskId`. Absent starts at the beginning. A cursor
+     * naming a task that has since been deleted still resolves: it is a bound,
+     * not a lookup.
+     */
+    readonly cursor?: string;
+}
+export interface TaskAttemptPage {
+    readonly attempts: readonly TaskAttempt[];
+    /**
+     * Pass as the next request's `cursor`. ABSENT means this page is the end of
+     * the walk — not "start over" — so a caller stops on absence rather than on
+     * an empty page, and a page that exactly fills `limit` with nothing after it
+     * still terminates.
+     */
+    readonly nextCursor?: string;
+}
 export interface TaskAttemptStore {
     /** Called when an offer is enqueued: records the pending attempt with no owner yet. */
     open(tenant: TenantId, input: {
@@ -216,13 +313,60 @@ export interface TaskAttemptStore {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    /**
+     * Atomically binds one message payload to a live task before an external
+     * consumer can run. `pending` is an existing exact reservation whose terminal
+     * receipt has not been recorded yet; callers retry the same product consumer
+     * contract so its own durable idempotency can reconcile a commit whose local
+     * finalization failed. Exact pending lookup precedes the live-task gate, while
+     * every new reservation remains lifecycle-gated.
+     */
+    reserveAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    /** Read only an exact reservation; conflicting task/message bindings are not observable. */
+    readAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    /** CAS the exact reservation to one immutable terminal disposition body. */
+    finalizeAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     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[]>;
-    /** First claim wins the ownership; a later claim by the same device is idempotent. No-op (returns `undefined`) for a task this tenant never offered. */
+    /**
+     * One bounded page of this tenant's attempts, keyset-paged by `taskId` — see
+     * {@link TaskAttemptListQuery} for why that key and not a timestamp.
+     * Implementations must read one page in one query (`taskId > cursor ORDER BY
+     * taskId LIMIT limit + 1`), never the whole tenant filtered in memory.
+     */
+    list(tenant: TenantId, query: TaskAttemptListQuery): Promise<TaskAttemptPage>;
+    /**
+     * First claim wins the ownership; a later claim by the same device is
+     * idempotent. No-op (returns `undefined`) for a task this tenant never
+     * offered.
+     *
+     * `runtime`/`capabilities` are the claiming daemon's self-report, written
+     * ONLY by the claim that actually wins the ownership CAS — an idempotent
+     * re-claim (and a losing one) must leave the recorded snapshot untouched,
+     * including when it carries a different or absent value.
+     */
     claim(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly runtime?: RuntimeId;
+        readonly capabilities?: RuntimeCapabilities;
     }): Promise<TaskAttempt | undefined>;
     /** Record a lifecycle transition. No-op (returns `undefined`) for an unknown task — same shape as the reference server's per-type handlers. */
     recordStatus(tenant: TenantId, input: {
@@ -287,7 +431,8 @@ export interface AgentEgressStore {
         readonly record: AgentEgressRecord;
         readonly created: boolean;
     }>;
-    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+    /** Exact reliable fact lookup; device plus event id alone is ambiguous. */
+    get(tenant: TenantId, deviceId: string, agentRef: AgentRef, eventId: string): Promise<AgentEgressRecord | undefined>;
 }
 export interface ProofRequestReceipt {
     readonly tenantId: TenantId;
@@ -411,6 +556,8 @@ export interface CloudBlobStore {
  */
 export interface BlobContentProxy {
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
+    /** Authoritative declared size for a signed PUT; no byte buffering precedes this lookup. */
+    expectedUploadBytes(blobId: string): Promise<bigint | undefined>;
     writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
     /** `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>;
@@ -436,6 +583,7 @@ export interface CloudStores {
     readonly approvals: ApprovalTimelineStore;
     readonly devices: DeviceDirectory;
     readonly pairingCodes: PairingCodeStore;
+    readonly pairing: PairingEnrollment;
     readonly nonces: NonceStore;
     readonly dedup: InboundDedupStore;
     readonly tasks: TaskAttemptStore;
@@ -447,5 +595,5 @@ export interface CloudStores {
     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', 'egress', 'proofReceipts', 'blobs', 'rateLimiter'];
+export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'pairing', 'nonces', 'dedup', 'tasks', 'cancellations', 'receipts', 'egress', 'proofReceipts', 'blobs', 'rateLimiter'];
 export type CloudStoreName = (typeof CLOUD_STORE_NAMES)[number];

package/dist/tenant-stores.d.ts

@@ -21,7 +21,8 @@
  * presigned blob calls) are deliberately absent from this surface: a
  * device-facing handler must not be able to reach them.
  */
-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 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 MailboxRecordDeliveryInput, type Principal, type PresenceHint, type PresenceHintInput, type TenantReadiness, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type TenantId } from '@byok-sdk/core';
+import type { AgentRef, RuntimeCapabilities, RuntimeId } from '@byok-sdk/protocol';
 import type { ActivityAppendInput, ActivityTail } from './activity';
 import type { ApprovalTimelineAppendInput, ApprovalTimelineTail } from './approval-timeline';
 import type { BlobObservation, CloudStores, DeviceRecord, AgentEgressRecord, RequestReceipt, TaskCancellationMutation, TaskCancellationRequest, TaskAttempt, TaskAttemptStatus } from './stores/ports';
@@ -29,6 +30,7 @@ export interface TenantBoundMailbox {
     append(input: MailboxAppendInput): Promise<MailboxMessage>;
     /** Pure read. Never advances the cursor — the daemon's next poll is the only ack. */
     readAfter(query: MailboxReadQuery): Promise<MailboxPage>;
+    recordDelivery(input: MailboxRecordDeliveryInput): Promise<MailboxCursorState>;
     advanceCursor(input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
     readCursor(deviceId: string): Promise<MailboxCursorState>;
 }
@@ -77,11 +79,33 @@ export interface TenantBoundTaskAttempts {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    reserveAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<import('./stores/ports').AgentMessageAdmission | undefined>;
+    finalizeAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<import('./stores/ports').AgentMessageAdmission | undefined>;
     get(taskId: string): Promise<TaskAttempt | undefined>;
     getMany(taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
+    list(query: import('./stores/ports').TaskAttemptListQuery): Promise<import('./stores/ports').TaskAttemptPage>;
     claim(input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly runtime?: RuntimeId;
+        readonly capabilities?: RuntimeCapabilities;
     }): Promise<TaskAttempt | undefined>;
     recordStatus(input: {
         readonly taskId: string;
@@ -94,7 +118,10 @@ export interface TenantBoundTaskCancellations {
     request(input: TaskCancellationRequest): Promise<TaskCancellationMutation | undefined>;
 }
 export interface TenantBoundDedup {
+    /** Device-physical envelope ledger. */
     checkAndRecord(deviceId: string, envelopeId: string): Promise<boolean>;
+    /** Strict Agent-bound envelope ledger. */
+    checkAndRecordAgent(deviceId: string, agentRef: AgentRef, envelopeId: string): Promise<boolean>;
 }
 export interface TenantBoundReceipts {
     record(input: {
@@ -111,7 +138,7 @@ export interface TenantBoundAgentEgress {
         readonly record: AgentEgressRecord;
         readonly created: boolean;
     }>;
-    get(deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+    get(deviceId: string, agentRef: AgentRef, eventId: string): Promise<AgentEgressRecord | undefined>;
 }
 export interface TenantBoundBlobs {
     createUpload(reservation: StorageReservation): Promise<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud",
-  "version": "0.11.0",
+  "version": "0.13.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.11.0",
-    "@byok-sdk/protocol": "0.11.0",
+    "@byok-sdk/core": "0.13.0",
+    "@byok-sdk/protocol": "0.13.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }