@byok-sdk/cloud 0.12.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/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/task-attempts.d.ts

@@ -16,7 +16,11 @@
  * unfalsifiable.
  */
 import { type Clock, type TenantId } from '@byok-sdk/core';
-import { type AgentMessageAdmission, type AgentRef, type TaskAttempt, type TaskAttemptStatus, type 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);
@@ -54,9 +58,12 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
     }): 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;
@@ -69,9 +76,10 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
 export declare class InMemoryTaskAttemptState {
     #private;
     readonly attempts: Map<string, TaskAttempt>;
-    readonly messageAdmissions: Map<string, AgentMessageAdmission>;
+    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

@@ -33,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';
@@ -184,12 +184,17 @@ export interface NonceStore {
 }
 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];
@@ -209,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. */
@@ -218,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: {
@@ -240,8 +316,10 @@ export interface TaskAttemptStore {
     /**
      * 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 must fail closed rather than
-     * invoke the consumer again.
+     * 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;
@@ -267,10 +345,28 @@ export interface TaskAttemptStore {
     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: {
@@ -335,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;

package/dist/tenant-stores.d.ts

@@ -22,6 +22,7 @@
  * 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 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';
@@ -99,9 +100,12 @@ export interface TenantBoundTaskAttempts {
     }): 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;
@@ -114,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: {
@@ -131,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.12.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.12.0",
-    "@byok-sdk/protocol": "0.12.0",
+    "@byok-sdk/core": "0.13.0",
+    "@byok-sdk/protocol": "0.13.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }