@byok-sdk/cloud 0.12.0 → 0.14.0

package/dist/activity.d.ts

@@ -14,12 +14,46 @@ export declare const ActivityAppendRequestSchema: z.ZodObject<{
         tool: z.ZodString;
         input: z.ZodOptional<z.ZodUnknown>;
         toolCallId: z.ZodOptional<z.ZodString>;
+        spill: z.ZodOptional<z.ZodObject<{
+            field: z.ZodEnum<{
+                input: "input";
+                output: "output";
+            }>;
+            totalBytes: z.ZodNumber;
+            omittedBytes: z.ZodNumber;
+            contentType: z.ZodLiteral<"application/json">;
+            blob: z.ZodOptional<z.ZodObject<{
+                blobId: z.ZodString;
+                contentHash: z.ZodString;
+                size: z.ZodNumber;
+                contentType: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            unstoredReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"tool_result">;
         tool: z.ZodString;
         output: z.ZodOptional<z.ZodUnknown>;
         toolCallId: z.ZodOptional<z.ZodString>;
         isError: z.ZodOptional<z.ZodBoolean>;
+        spill: z.ZodOptional<z.ZodObject<{
+            field: z.ZodEnum<{
+                input: "input";
+                output: "output";
+            }>;
+            totalBytes: z.ZodNumber;
+            omittedBytes: z.ZodNumber;
+            contentType: z.ZodLiteral<"application/json">;
+            blob: z.ZodOptional<z.ZodObject<{
+                blobId: z.ZodString;
+                contentHash: z.ZodString;
+                size: z.ZodNumber;
+                contentType: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            unstoredReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"artifact">;
         name: z.ZodString;
@@ -49,6 +83,7 @@ export declare const TimelineEventSchema: z.ZodObject<{
     sourceEnvelopeId: z.ZodString;
     batchSeq: z.ZodNumber;
     eventIndex: z.ZodNumber;
+    sourceDropped: z.ZodOptional<z.ZodNumber>;
     receivedAt: z.ZodISODateTime;
     event: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"progress">;
@@ -58,12 +93,46 @@ export declare const TimelineEventSchema: z.ZodObject<{
         tool: z.ZodString;
         input: z.ZodOptional<z.ZodUnknown>;
         toolCallId: z.ZodOptional<z.ZodString>;
+        spill: z.ZodOptional<z.ZodObject<{
+            field: z.ZodEnum<{
+                input: "input";
+                output: "output";
+            }>;
+            totalBytes: z.ZodNumber;
+            omittedBytes: z.ZodNumber;
+            contentType: z.ZodLiteral<"application/json">;
+            blob: z.ZodOptional<z.ZodObject<{
+                blobId: z.ZodString;
+                contentHash: z.ZodString;
+                size: z.ZodNumber;
+                contentType: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            unstoredReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"tool_result">;
         tool: z.ZodString;
         output: z.ZodOptional<z.ZodUnknown>;
         toolCallId: z.ZodOptional<z.ZodString>;
         isError: z.ZodOptional<z.ZodBoolean>;
+        spill: z.ZodOptional<z.ZodObject<{
+            field: z.ZodEnum<{
+                input: "input";
+                output: "output";
+            }>;
+            totalBytes: z.ZodNumber;
+            omittedBytes: z.ZodNumber;
+            contentType: z.ZodLiteral<"application/json">;
+            blob: z.ZodOptional<z.ZodObject<{
+                blobId: z.ZodString;
+                contentHash: z.ZodString;
+                size: z.ZodNumber;
+                contentType: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            unstoredReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"artifact">;
         name: z.ZodString;
@@ -111,11 +180,23 @@ export interface ActivityAppendInput {
     readonly capacity?: number;
 }
 export interface ActivityStore {
+    /**
+     * `sourceEnvelopeId` is the per-envelope idempotency authority. Repeating
+     * its exact canonical batch returns the existing tail; changing any batch
+     * fact under that identity is rejected rather than appended as a second
+     * observation.
+     */
     append(tenant: TenantId, input: ActivityAppendInput): Promise<ActivityTail>;
     read(tenant: TenantId, taskId: string): Promise<ActivityTail | undefined>;
 }
 export declare function validateActivityAppend(input: ActivityAppendInput): number;
 export declare function projectTimelineEvents(input: ActivityAppendInput, receivedAt: string): readonly TimelineEvent[];
+/**
+ * Whether one live tail already contains this source envelope's canonical
+ * batch. `conflict` includes a partially retained source: its missing events
+ * are not evidence that a different batch may reuse the same source identity.
+ */
+export declare function activitySourceBatchState(entries: readonly TimelineEvent[], input: ActivityAppendInput): 'absent' | 'same' | 'conflict';
 export declare function parseTimelineEvents(value: unknown): readonly TimelineEvent[];
 export declare function compareTimelineEvents(left: TimelineEvent, right: TimelineEvent): number;
 export declare function activityCursor(entries: readonly TimelineEvent[]): ActivityCursor | undefined;

package/dist/agent-home-projections.d.ts

@@ -14,8 +14,8 @@ export interface AgentHomeProjectionReceiptInput {
     readonly agentRef: AgentHomeProjectionPayload['agentRef'];
     readonly projectionHash: AgentHomeProjectionPayload['projectionHash'];
 }
-export declare function agentHomeProjectionRequestKey(deviceId: string, requestId: string): string;
-export declare function agentHomeProjectionCompletionKey(deviceId: string, requestId: string): string;
+export declare function agentHomeProjectionRequestKey(deviceId: string, agentRef: AgentHomeProjectionPayload['agentRef'], requestId: string): string;
+export declare function agentHomeProjectionCompletionKey(deviceId: string, agentRef: AgentHomeProjectionPayload['agentRef'], requestId: string): string;
 export declare function sameAgentHomeProjectionRequest(expected: AgentHomeProjectionPayload, actual: AgentHomeProjectionPayload): boolean;
 export declare function receiptMatchesAgentHomeProjection(request: AgentHomeProjectionPayload, receipt: AgentHomeProjectionCompletionRequest): boolean;
 export declare function statusInputMatchesAgentHomeProjection(request: AgentHomeProjectionPayload, input: AgentHomeProjectionReceiptInput): boolean;

package/dist/agent-reliability.d.ts

@@ -0,0 +1,9 @@
+import { type AgentRef } from '@byok-sdk/protocol';
+/**
+ * Exact, unambiguous storage identity for one Agent-scoped reliability fact.
+ *
+ * The device remains explicit because one Agent is placed on at most one
+ * device today, while one device may run many Agents. JSON supplies a stable
+ * length-delimited encoding without inventing a Placement authority.
+ */
+export declare function agentReliabilityKey(domain: string, deviceId: string, agentRef: AgentRef, id: string): string;

package/dist/approval-control.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Host-side approval resolution: the one rule that decides WHICH approval a
+ * `cloud.approveTask`/`rejectTask` call is allowed to resolve.
+ *
+ * `@byok-sdk/server` keeps this as a single mutable slot on its task record
+ * (`TaskSnapshot.pendingApprovalId`, `packages/server/src/hub.ts`) that
+ * `task.await_approval` overwrites and `task.approval_resolved` clears. Cloud
+ * holds no session state and no second store: the SAME two observations are
+ * already durable in the `ApprovalTimelineStore` tail
+ * (`approval-timeline.ts`), appended by the inbound gate, so the slot is
+ * DERIVED from that tail on each call rather than mirrored into a record that
+ * could then disagree with it.
+ *
+ * The derivation is a fold over the tail's entries in revision order, holding
+ * exactly one slot — deliberately the server's shape, not a set of concurrently
+ * pending approvals:
+ *
+ *   - `approval_requested` SETS the slot, superseding whatever it held. A
+ *     daemon that dispatched a fresh approval without this cloud ever seeing
+ *     the previous one resolved has moved on, and the newest request is what
+ *     an operator is being asked about (`hub.ts:1399`).
+ *   - `approval_resolved(X)` CLEARS the slot when the slot's own id is `X`, or
+ *     when the slot has no id at all (a pre-M5 daemon never reported one, so
+ *     the resolution can only be about the single outstanding request). A
+ *     resolution naming some OTHER id is about an approval already superseded
+ *     and leaves the current slot standing (`hub.ts:1569`).
+ *
+ * Two ways there is legitimately nothing pending: the tail has no unresolved
+ * request, or the tail is gone entirely — it is a bounded, TTL'd observation
+ * ring, not an authority that keeps facts forever. Both answer `undefined`,
+ * and the callers fail closed on it. A dropped-then-expired approval is not
+ * silently approved.
+ */
+import type { ApprovalTimelineTail } from './approval-timeline';
+/**
+ * M5 (approval targeting): thrown by `ByokCloud.approveTask`/`rejectTask` when
+ * the caller supplied an `approvalId` that does NOT match the approval this
+ * task currently has pending — the caller is targeting a SPECIFIC approval the
+ * daemon has already superseded with a newer one.
+ *
+ * Distinct from the `task_not_awaiting_approval` `ByokCloudError` (there
+ * is no pending approval at all, checked FIRST so it still wins when both would
+ * apply): this error means the task genuinely IS awaiting an approval, just not
+ * the one the caller thinks it is. Thrown before any mailbox row is allocated —
+ * a stale-id call has zero side effects.
+ *
+ * A distinct class rather than a `CloudErrorCode`, unlike the rest of
+ * this package's failures, because it carries the two ids the caller needs to
+ * re-target: a code alone cannot say what the pending approval actually is.
+ */
+export declare class StaleApprovalError extends Error {
+    readonly taskId: string;
+    readonly requestedApprovalId: string;
+    readonly currentApprovalId: string | undefined;
+    constructor(taskId: string, requestedApprovalId: string, currentApprovalId: string | undefined);
+}
+/** The one approval a task currently has outstanding. */
+export interface PendingApproval {
+    /**
+     * The daemon's own id for this approval. ABSENT for a pre-M5 daemon that
+     * reported `task.await_approval` without one — the approval is still pending
+     * and still resolvable, it just cannot be targeted, so a caller-supplied
+     * `approvalId` proceeds untargeted exactly as it does on the server.
+     */
+    readonly approvalId?: string;
+    /** Immutable daemon envelope identity for this exact request observation. */
+    readonly sourceEnvelopeId: string;
+    /** Monotonic timeline revision for this exact request observation. */
+    readonly revision: number;
+}
+/**
+ * The task's current pending approval, or `undefined` when it has none — see
+ * this module's own doc comment for the fold and why it holds one slot.
+ */
+export declare function pendingApproval(tail: ApprovalTimelineTail | undefined): PendingApproval | undefined;

package/dist/approval-timeline.d.ts

@@ -3,44 +3,66 @@ import { z } from 'zod';
 export declare const DEFAULT_APPROVAL_TIMELINE_CAPACITY = 50;
 export declare const DEFAULT_APPROVAL_TIMELINE_TTL_MS: number;
 export declare const APPROVAL_SUMMARY_MAX_BYTES: number;
-export declare const ApprovalTimelineEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const ApprovalTimelineEventSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"approval_requested">;
     summary: z.ZodString;
     approvalId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"approval_resolved">;
-    approvalId: z.ZodString;
+    approvalId: z.ZodOptional<z.ZodString>;
     decision: z.ZodEnum<{
         approve: "approve";
         reject: "reject";
     }>;
-    resolvedBy: z.ZodEnum<{
-        local: "local";
-    }>;
+    resolvedBy: z.ZodLiteral<"local">;
+    at: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"approval_resolved">;
+    approvalId: z.ZodOptional<z.ZodString>;
+    decision: z.ZodLiteral<"approve">;
+    resolvedBy: z.ZodLiteral<"host">;
     at: z.ZodISODateTime;
-}, z.core.$strip>], "type">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"approval_resolved">;
+    approvalId: z.ZodOptional<z.ZodString>;
+    decision: z.ZodLiteral<"reject">;
+    resolvedBy: z.ZodLiteral<"host">;
+    reason: z.ZodNullable<z.ZodString>;
+    at: z.ZodISODateTime;
+}, z.core.$strict>]>;
 export type ApprovalTimelineEvent = Readonly<z.infer<typeof ApprovalTimelineEventSchema>>;
 export declare const ApprovalObservationSchema: z.ZodObject<{
     taskId: z.ZodString;
     sourceEnvelopeId: z.ZodString;
     revision: z.ZodNumber;
     receivedAt: z.ZodISODateTime;
-    event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event: z.ZodUnion<readonly [z.ZodObject<{
         type: z.ZodLiteral<"approval_requested">;
         summary: z.ZodString;
         approvalId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"approval_resolved">;
-        approvalId: z.ZodString;
+        approvalId: z.ZodOptional<z.ZodString>;
         decision: z.ZodEnum<{
             approve: "approve";
             reject: "reject";
         }>;
-        resolvedBy: z.ZodEnum<{
-            local: "local";
-        }>;
+        resolvedBy: z.ZodLiteral<"local">;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"approval_resolved">;
+        approvalId: z.ZodOptional<z.ZodString>;
+        decision: z.ZodLiteral<"approve">;
+        resolvedBy: z.ZodLiteral<"host">;
         at: z.ZodISODateTime;
-    }, z.core.$strip>], "type">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"approval_resolved">;
+        approvalId: z.ZodOptional<z.ZodString>;
+        decision: z.ZodLiteral<"reject">;
+        resolvedBy: z.ZodLiteral<"host">;
+        reason: z.ZodNullable<z.ZodString>;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>]>;
 }, z.core.$strip>;
 export type ApprovalObservation = Readonly<z.infer<typeof ApprovalObservationSchema>>;
 export interface ApprovalTimelineTail {
@@ -59,8 +81,31 @@ export interface ApprovalTimelineAppendInput {
     readonly ttlMs?: number;
     readonly capacity?: number;
 }
+/**
+ * One host decision against the exact unresolved request it observed.
+ *
+ * The expected source/revision pair is the durable request identity.  A
+ * resolver must not turn a stale read into a decision for a request which has
+ * since been superseded, and it must not split one logical decision into
+ * several mailbox controls.  Implementations serialize this comparison and
+ * append under the timeline's per-task authority.
+ */
+export interface ApprovalTimelineResolvePendingInput extends ApprovalTimelineAppendInput {
+    readonly expectedSourceEnvelopeId: string;
+    readonly expectedRevision: number;
+}
+/** Result of a conditional host-decision append. Logical conflicts are data, not transport failures. */
+export type ApprovalTimelineResolvePendingResult = {
+    readonly status: 'applied' | 'replayed';
+    readonly tail: ApprovalTimelineTail;
+} | {
+    readonly status: 'conflict' | 'superseded' | 'absent';
+    readonly tail?: ApprovalTimelineTail;
+};
 export interface ApprovalTimelineStore {
     append(tenant: TenantId, input: ApprovalTimelineAppendInput): Promise<ApprovalTimelineTail>;
+    /** Atomically append one host resolution only if its request remains current. */
+    resolvePending(tenant: TenantId, input: ApprovalTimelineResolvePendingInput): Promise<ApprovalTimelineResolvePendingResult>;
     read(tenant: TenantId, taskId: string): Promise<ApprovalTimelineTail | undefined>;
 }
 export interface ValidatedApprovalTimelineAppend {
@@ -69,6 +114,7 @@ export interface ValidatedApprovalTimelineAppend {
     readonly event: ApprovalTimelineEvent;
 }
 export declare function validateApprovalTimelineAppend(input: ApprovalTimelineAppendInput): ValidatedApprovalTimelineAppend;
+export declare function validateApprovalTimelineResolve(input: ApprovalTimelineResolvePendingInput): ValidatedApprovalTimelineAppend;
 export declare function approvalTimelineKey(tenant: TenantId, taskId: string): string;
 export declare function parseApprovalObservations(value: unknown): readonly ApprovalObservation[];
 export declare function approvalTimelineCursor(entries: readonly ApprovalObservation[]): number | undefined;

package/dist/auth/bearer.d.ts

@@ -20,6 +20,23 @@ import type { TokenSigner } from './tokens';
 export interface BearerAuthDeps {
     readonly tokenSigner: TokenSigner;
     readonly devices: DeviceDirectory;
+    /**
+     * The ONE product this deployment serves, when it serves exactly one.
+     *
+     * Two deployment shapes, two explicit authorities — not a default and a
+     * fallback. A multi-product hosted control plane leaves this absent, and the
+     * row is the whole product authority (`device.productId === claims.productId`
+     * below). A single-product instance supplies it — that is the embedded shape,
+     * where `createByokServer({ productId })` always has one — and the token must
+     * then name THAT product as well, so a device paired through a code minted
+     * for another product cannot reach this instance's bearer-authed routes at
+     * all.
+     *
+     * Absent it, a cross-product device whose token and row agree with each other
+     * authenticates on every `device` route the deployment mounts, which is
+     * precisely the drift this closes for the embedded shape.
+     */
+    readonly instanceProductId?: string;
 }
 export declare function extractBearerToken(header: string | undefined): string | undefined;
 export declare function authenticateBearer(header: string | undefined, deps: BearerAuthDeps): Promise<DevicePrincipal | undefined>;

package/dist/cloud.d.ts

@@ -17,13 +17,14 @@
 import { type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type SkillPackStore, type TenantId, type TenantReadiness } from '@byok-sdk/core';
 import type { ActivityTail } from './activity';
 import type { ApprovalTimelineTail } from './approval-timeline';
-import { type Envelope, type AgentContentReadPayload, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionPayload, type AgentHomeProjectionReadback, type AgentMemoryProjectionEraseResult, type TaskOfferPayload, type TaskOfferForAgentPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferForAgentWithEgressFreshPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+import { type Envelope, type AgentRef, type AgentContentReadPayload, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionPayload, type AgentHomeProjectionReadback, type AgentMemoryProjectionEraseResult, type TaskOfferPayload, type TaskSteerPayload, type TaskOfferForAgentPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferForAgentWithEgressFreshPayload, 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 ByokCloudObserver } from './inbound';
 import { type AgentHomeProjectionReceiptInput } from './agent-home-projections';
 import type { AgentMemoryProjectionAuthorizer, AgentMemoryProjectionStore } from './agent-memory-projection';
-import type { BlobContentProxy, CloudStores, DeviceRecord, AgentEgressRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
+import type { BlobContentProxy, CloudStores, DeviceRecord, AgentEgressRecord, PairingCodeInfo, RequestReceipt, TaskAttempt, TaskAttemptListQuery, TaskAttemptPage } from './stores/ports';
 import { type TerminalResult } from './terminal-result';
 import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
 /** Matches the reference server's ceiling (§7). */
@@ -67,7 +68,24 @@ export interface ByokCloudOptions {
     readonly capabilities: CapabilityDeclaration;
     /** Recorded on the control-plane principal every host-side call is made under. */
     readonly operatorId?: string;
-    /** Product-owned consumer; destination lookup is keyed by authenticated task context, never model input. */
+    /**
+     * The ONE product this deployment serves, when it serves exactly one — the
+     * embedded shape. Supplying it makes every bearer-authed route additionally
+     * require the token to name this product; omitting it leaves the device row
+     * as the whole product authority. Two deployment shapes, two explicit
+     * authorities: see `BearerAuthDeps.instanceProductId` (`auth/bearer.ts`).
+     */
+    readonly instanceProductId?: string;
+    /**
+     * Product-owned consumer; destination lookup uses authenticated task context.
+     * Delivery is at least once, including concurrent calls and retries after a
+     * process restart or an uncertain commit. The product must durably deduplicate
+     * the exact tenant/device/task/AgentRef/message identity and payload, producing
+     * one logical effect and the same outcome/reasonCode on every exact replay.
+     * A thrown error leaves admission pending for transport retry; only a returned
+     * outcome is a terminal product decision. Do not use callback invocation count
+     * as execution authority.
+     */
     readonly agentMessage?: {
         consume(input: {
             readonly tenant: TenantId;
@@ -80,6 +98,14 @@ export interface ByokCloudOptions {
             readonly reasonCode?: string;
         }>;
     };
+    /**
+     * Post-commit relay for envelopes this cloud durably accepted. Read-only by
+     * construction: it is told after the write, it returns `void`, and a throw
+     * from it is swallowed — the outcome is already fixed. Distinct from
+     * {@link ByokCloudOptions.agentMessage}, which is admission and runs BEFORE
+     * a write, deciding whether it happens at all.
+     */
+    readonly observer?: ByokCloudObserver;
     /** Embedder-owned grant and consent authority for optional hosted Agent-memory projection. */
     readonly agentMemoryProjectionAuthorizer?: AgentMemoryProjectionAuthorizer;
     /** Durable snapshot + immutable metering receipt authority for optional hosted Agent-memory projection. */
@@ -152,6 +178,20 @@ export interface AgentContentReadInput {
 export type AgentHomeProjectionInput = AgentHomeProjectionPayload;
 /** Exact request identity a host must echo to read back durable projection status. */
 export type AgentHomeProjectionStatusInput = AgentHomeProjectionReceiptInput;
+/** Optional targeting for {@link ByokCloud.approveTask}. */
+export interface ApproveTaskOptions {
+    /**
+     * Resolve THIS specific approval rather than whichever one is pending.
+     * A mismatch against the task's current pending approval throws
+     * {@link StaleApprovalError} instead of resolving the wrong thing.
+     */
+    readonly approvalId?: string;
+}
+/** Optional targeting and refusal cause for {@link ByokCloud.rejectTask}. */
+export interface RejectTaskOptions extends ApproveTaskOptions {
+    /** Carried to the runtime verbatim; absent stays absent on the wire. */
+    readonly reason?: string;
+}
 export interface EnqueuedAgentControl {
     readonly seq: number;
     readonly envelope: Envelope;
@@ -223,11 +263,82 @@ export interface ByokCloud {
     eraseAgentMemoryProjection(tenant: TenantId, agentId: string): Promise<AgentMemoryProjectionEraseResult>;
     /** Host control plane: durably request cancellation by tenant/task id. Idempotent. */
     cancelTask(tenant: TenantId, taskId: string, reason?: string): Promise<TaskAttempt>;
+    /**
+     * Host control plane: resolve the approval a paused task is waiting on, by
+     * enqueueing `task.approve` to the device that claimed it.
+     *
+     * WHICH approval is a derived fact, not a stored one — see
+     * `approval-control.ts` for the fold over the durable timeline that produces
+     * it, and why cloud adds no second authority for it. Gate order mirrors the
+     * reference server (`packages/server/src/hub.ts`), and every gate is
+     * evaluated in full before a mailbox row is allocated, so a refused call has
+     * zero side effects:
+     *
+     *   1. no such task for this tenant -> `task_not_found`;
+     *   2. nothing to resolve -> `task_not_awaiting_approval`, which covers a
+     *      terminal attempt, an unclaimed one, and a timeline with no unresolved
+     *      request (expired or never written). Checked BEFORE targeting, so it
+     *      still wins when both would apply;
+     *   3. `opts.approvalId` names an approval this task has already superseded
+     *      -> {@link StaleApprovalError}. When the daemon never reported an id
+     *      at all, the call proceeds untargeted, exactly as on the server.
+     *
+     * Delivery is a best-effort notification, the same contract the wire message
+     * has always had (`TaskApprovePayloadSchema`, `@byok-sdk/protocol`): the
+     * enqueued envelope is durable, the runtime's response to it is observable
+     * only through that task's own later messages. The outgoing `approvalId` is
+     * the caller's when given, else the pending one, else omitted.
+     */
+    approveTask(tenant: TenantId, taskId: string, opts?: ApproveTaskOptions): Promise<EnqueuedAgentControl>;
+    /**
+     * Host control plane: refuse the approval a paused task is waiting on, by
+     * enqueueing `task.reject` to the device that claimed it. Same gates, same
+     * targeting, and the same best-effort delivery contract as
+     * {@link ByokCloud.approveTask} — `opts.reason` is carried to the runtime
+     * verbatim and is never synthesized when absent.
+     */
+    rejectTask(tenant: TenantId, taskId: string, opts?: RejectTaskOptions): Promise<EnqueuedAgentControl>;
+    /**
+     * Host control plane: inject steering text into a RUNNING task, by enqueueing
+     * `task.steer` to the device that claimed it.
+     *
+     * Gated on the claim-time capability snapshot and on nothing else — see
+     * `steer-control.ts` for why that is the only admissible input and why an
+     * absent snapshot refuses. Gate order mirrors the reference server
+     * (`ConnectionHub.steerTask`, `packages/server/src/hub.ts`), and every gate is
+     * evaluated in full before a mailbox row is allocated, so a refused call has
+     * zero side effects:
+     *
+     *   1. no such task for this tenant -> `task_not_found` ({@link ByokCloudError});
+     *   2. terminal attempt -> {@link SteerRejectedError} `task_terminal`,
+     *      checked BEFORE the running check so a steer racing a terminal
+     *      transition always resolves terminal-first;
+     *   3. not running (or running with no owning device) ->
+     *      {@link SteerRejectedError} `task_not_running`;
+     *   4. the claim snapshot does not positively say `steer: true` ->
+     *      {@link SteerRejectedError} `steer_unsupported_runtime`, including when
+     *      there is no snapshot at all.
+     *
+     * Delivery is the same best-effort notification every control message has:
+     * the enqueued envelope is durable, and whether the runtime acted on it is
+     * observable only through that task's own later messages.
+     */
+    steerTask(tenant: TenantId, taskId: string, payload: TaskSteerPayload): Promise<EnqueuedAgentControl>;
     readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    /**
+     * Host control plane: one bounded page of this tenant's task attempts,
+     * keyset-paged by `taskId` — see {@link TaskAttemptListQuery} for why the key
+     * is the task id and not a timestamp, and why the walk terminates on an
+     * absent `nextCursor` rather than on an empty page.
+     *
+     * A non-positive or non-integer `limit` is rejected
+     * (`coordination_input_invalid`), never defaulted: the host names the bound.
+     */
+    listTaskAttempts(tenant: TenantId, query: TaskAttemptListQuery): Promise<TaskAttemptPage>;
     /** 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>;
-    /** Exact durable egress fact and receipt selected by (tenant, device, event id). */
-    readAgentEgress(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+    /** Exact durable egress fact and receipt selected by (tenant, device, AgentRef, event id). */
+    readAgentEgress(tenant: TenantId, deviceId: string, agentRef: AgentRef, eventId: string): Promise<AgentEgressRecord | undefined>;
     /**
      * Host control plane: the same first terminal, decoded into the typed read
      * model ({@link TerminalResult}) so a host reads result fields, not envelope

package/dist/composition/in-memory.d.ts

@@ -20,6 +20,8 @@ export interface InMemoryByokCloudOptions {
     readonly tokenSigner?: TokenSigner;
     readonly capabilities?: CapabilityDeclaration;
     readonly operatorId?: string;
+    /** Single-product instance authority; absent leaves the device row as the whole product authority. */
+    readonly instanceProductId?: string;
     readonly maxBlobSizeBytes?: number;
     readonly longPollHoldMs?: number;
     readonly longPollIntervalMs?: number;
@@ -51,6 +53,8 @@ export interface InMemoryByokCloudOptions {
     readonly skillPacks?: SkillPackStore;
     readonly skillPackPageLimit?: number;
     readonly agentMessage?: ByokCloudOptions['agentMessage'];
+    /** Post-commit relay; absent means nothing is watching. */
+    readonly observer?: ByokCloudOptions['observer'];
     readonly agentMemoryProjectionAuthorizer?: AgentMemoryProjectionAuthorizer;
     readonly agentMemoryProjectionStore?: AgentMemoryProjectionStore;
 }

package/dist/coordination.d.ts

@@ -21,6 +21,14 @@ export declare function assertBoardLabels(channel: string, title: string, limits
     readonly channelMaxBytes: number;
     readonly titleMaxBytes: number;
 }): void;
+/**
+ * The page bound on {@link TaskAttemptStore.list}. Fail-closed rather than
+ * defaulted or clamped: a caller that asks for `0`, `-1`, `2.5`, or `Infinity`
+ * has a bug, and answering it with a silently substituted limit hides that bug
+ * behind a plausible page. Enforced in the STORE rather than only at the
+ * façade, because the port is reachable directly by a host composition.
+ */
+export declare function assertTaskAttemptListLimit(limit: number): void;
 export declare function validateActivityEvents(events: readonly AgentEventOrUnknown[], dropped: number, bounds: ActivityBounds): void;
 export declare function validateActivityBatch(input: Omit<ActivityAppendInput, 'ttlMs' | 'capacity'>, bounds: ActivityBounds): void;
 export declare function appendActivityEvents(activity: TenantBoundActivity, input: {

package/dist/errors.d.ts

@@ -43,6 +43,15 @@ export declare const CLOUD_ERROR_CODES: {
     readonly activity_batch_too_large: 'activity_batch_too_large';
     /** Host control-plane task lookup is tenant-closed and found no task. */
     readonly task_not_found: 'task_not_found';
+    /**
+     * A host `approveTask`/`rejectTask` names a task with no approval to
+     * resolve: the durable timeline holds no unresolved `approval_requested`
+     * (including a tail that has expired or was never written), the attempt has
+     * already reached a terminal status, or no device ever claimed it so there
+     * is nothing to notify. Fail-closed by construction — cloud never invents a
+     * pending approval to make the call succeed.
+     */
+    readonly task_not_awaiting_approval: 'task_not_awaiting_approval';
     /** Durable target-device capability is absent, revoked, or unavailable. */
     readonly agent_capability_missing: 'agent_capability_missing';
     /** Inbound Agent identity did not exactly match the offered identity. */

package/dist/handlers/events.d.ts

@@ -1,7 +1,7 @@
 /**
  * `GET /byok/events?cursor=N` — the long-poll receive half (§8).
  *
- * Three properties the daemon's transport depends on, reproduced against the
+ * Four properties the daemon's transport depends on, reproduced against the
  * core mailbox rather than an in-process outbox:
  *
  * - **Reading is not acknowledging.** `readAfter` never moves the cursor. The
@@ -19,6 +19,12 @@
  *   registered waiter: a waiter map is exactly the cross-request state a
  *   stateless handler may not keep (S3.5 boxes 14-15), and a second cloud
  *   instance would not see it anyway.
+ * - **A lost cursor fails closed.** A cursor below the mailbox's retained
+ *   window is answered `409 { error: 'cursor_too_old', recoverableFrom }`, the
+ *   same body the reference server returns (`packages/server/src/http.ts:386`)
+ *   and the only one the daemon's transport can turn into a resync. Serving
+ *   such a caller a 200 would hand it a partial tail it has no way to tell
+ *   apart from a complete one.
  */
 import type { Context } from 'hono';
 import { type DeviceRouteDeps } from './shared';

package/dist/handlers/messages.d.ts

@@ -21,6 +21,7 @@
  */
 import type { Context } from 'hono';
 import { type AgentContentReceiptPayload, type AgentMessageDispositionPayload, type AgentMessagePublishPayload } from '@byok-sdk/protocol';
+import { type ByokCloudObserver } from '../inbound';
 import type { ActivityBounds } from '../coordination';
 import type { AgentEgressRecord } from '../stores/ports';
 import type { TenantStores } from '../tenant-stores';
@@ -48,5 +49,11 @@ export interface MessagesRouteDeps extends DeviceRouteDeps {
         }>;
     };
     readonly appendAgentMessageDisposition: (stores: TenantStores, deviceId: string, taskId: string, payload: AgentMessageDispositionPayload) => Promise<void>;
+    /**
+     * Post-commit relay. Batch order IS notification order: the loop below
+     * awaits one envelope's gate before starting the next, so an observer sees
+     * committed envelopes in the order the device sent them.
+     */
+    readonly observer?: ByokCloudObserver;
 }
 export declare function messagesHandler(deps: MessagesRouteDeps): (c: Context) => Promise<Response>;