@byok-sdk/cloud 0.5.0 → 0.6.1

package/dist/cloud.d.ts

@@ -14,14 +14,14 @@
  * quietly undo that — a Running/session map — is asserted absent by
  * `src/__tests__/constraints.test.ts`.
  */
-import { type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type SkillPackStore, type TenantId } from '@byok-sdk/core';
+import { type 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 TaskOfferPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+import { type Envelope, type AgentContentReadPayload, type TaskOfferPayload, type TaskOfferForAgentPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
 import type { TokenSigner } from './auth/tokens';
 import type { CloudCrypto } from './crypto/port';
 import { type RouteDescriptor } from './router/registry';
-import type { BlobContentProxy, CloudStores, DeviceRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
+import type { BlobContentProxy, CloudStores, DeviceRecord, AgentEgressRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
 import { type TerminalResult } from './terminal-result';
 import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
 /** Matches the reference server's ceiling (§7). */
@@ -32,6 +32,8 @@ export declare const DEFAULT_LONG_POLL_HOLD_MS = 50000;
 export declare const DEFAULT_LONG_POLL_INTERVAL_MS = 250;
 /** Rows per `GET /byok/events` response. */
 export declare const DEFAULT_EVENTS_PAGE_LIMIT = 50;
+/** Device capability required by the strict Agent offer path. */
+export declare const AGENT_HOME_CONTRACT_CAPABILITY = "agent-home-contract";
 export interface ByokCloudOptions {
     readonly core: CoreStores;
     readonly cloud: CloudStores;
@@ -95,6 +97,31 @@ export interface EnqueueToolsetOfferInput {
     /** Strict control payload containing logical ids only; executable MCP definitions are not part of this type. */
     readonly payload: TaskOfferWithToolsetsPayload;
 }
+/**
+ * Strict Agent dispatch input. The device path is intentionally a separate
+ * argument on {@link ByokCloud.enqueueAgentOffer}; no legacy offer field is
+ * interpreted as an Agent placement hint.
+ */
+export interface AgentDispatchInput {
+    /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
+    readonly taskId?: string;
+    /** Strict Agent payload carrying the exact opaque AgentRef. */
+    readonly payload: TaskOfferForAgentPayload;
+}
+/** Strict Agent dispatch that supplies the policy consumed by the typed egress lanes. */
+export interface AgentEgressDispatchInput {
+    /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
+    readonly taskId?: string;
+    readonly payload: TaskOfferForAgentWithEgressPayload;
+}
+/** A task-free, independently capability-gated Agent content read. */
+export interface AgentContentReadInput {
+    readonly payload: AgentContentReadPayload;
+}
+export interface EnqueuedAgentControl {
+    readonly seq: number;
+    readonly envelope: Envelope;
+}
 export interface EnqueuedOffer {
     readonly taskId: string;
     /** The per-(tenant, device) delivery seq — the daemon's redelivery cursor position for this envelope. */
@@ -127,17 +154,33 @@ export interface ByokCloud {
     enqueueOffer(tenant: TenantId, deviceId: string, input: EnqueueOfferInput): Promise<EnqueuedOffer>;
     /** Host control plane: enqueue the additive fail-closed offer variant that requires local MCP toolsets. */
     enqueueToolsetOffer(tenant: TenantId, deviceId: string, input: EnqueueToolsetOfferInput): Promise<EnqueuedOffer>;
+    /**
+     * Host control plane: enqueue a strict Agent offer to an explicit device.
+     * Capability admission is read from the durable authenticated device row
+     * before either the mailbox append or task-attempt open.
+     */
+    enqueueAgentOffer(tenant: TenantId, deviceId: string, input: AgentDispatchInput): Promise<EnqueuedOffer>;
+    /**
+     * Host control plane: enqueue the typed egress-policy Agent offer. Missing
+     * egress/reliable-ack capabilities reject before a mailbox row is allocated.
+     */
+    enqueueAgentEgressOffer(tenant: TenantId, deviceId: string, input: AgentEgressDispatchInput): Promise<EnqueuedOffer>;
+    /** Host control plane: request one policy-bound content read without a task fallback. */
+    enqueueAgentContentRead(tenant: TenantId, deviceId: string, input: AgentContentReadInput): Promise<EnqueuedAgentControl>;
+    /** Host control plane: durably request cancellation by tenant/task id. Idempotent. */
+    cancelTask(tenant: TenantId, taskId: string, reason?: string): Promise<TaskAttempt>;
     readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     /** The recorded terminal for a task — the first one, re-encoded canonically under the frozen v1 codec (see `recordTerminal`, `inbound.ts`: the stored body is `encodeEnvelope` of the zod-parsed envelope, not the device's original byte sequence). */
     readTerminalReceipt(tenant: TenantId, taskId: string): Promise<RequestReceipt | undefined>;
+    /** Exact durable egress fact and receipt selected by (tenant, device, event id). */
+    readAgentEgress(tenant: TenantId, deviceId: string, 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
-     * prose. `undefined` ONLY means no terminal fact is recorded yet:
-     * first-terminal-wins is inherited from the receipt store
-     * ({@link ByokCloud.readTerminalReceipt} reads the same row), and a declined
-     * task records no terminal at all — use {@link ByokCloud.readTaskAttempt}
-     * for that attempt status. An absent `document` covers both a legacy
+     * prose. An accepted host cancellation tombstone outranks a later device
+     * receipt; the raw receipt remains readable as device evidence through
+     * {@link ByokCloud.readTerminalReceipt}. `undefined` means neither fact
+     * exists. An absent `document` covers both a legacy
      * pre-`result-document` daemon build and a daemon with no `resultDocument`
      * extractor; a receipt whose body is not a terminal envelope throws rather
      * than returning a best-effort shape.
@@ -151,6 +194,8 @@ export interface ByokCloud {
     /** Human review authority. Device routes cannot produce `done`. */
     acceptBoardItem(tenant: TenantId, itemId: string): Promise<BoardItem>;
     listPresence(tenant: TenantId): Promise<readonly PresenceHint[]>;
+    /** SDK-owned observation only; never a scheduler or execution authority. */
+    readTenantReadiness(tenant: TenantId): Promise<TenantReadiness>;
     readActivity(tenant: TenantId, taskId: string): Promise<ActivityTail | undefined>;
     readApprovalTimeline(tenant: TenantId, taskId: string): Promise<ApprovalTimelineTail | undefined>;
 }

package/dist/errors.d.ts

@@ -41,6 +41,18 @@ export declare const CLOUD_ERROR_CODES: {
     readonly terminal_receipt_unreadable: 'terminal_receipt_unreadable';
     /** A progress/activity batch exceeded the configured event or byte ceiling. */
     readonly activity_batch_too_large: 'activity_batch_too_large';
+    /** Host control-plane task lookup is tenant-closed and found no task. */
+    readonly task_not_found: 'task_not_found';
+    /** 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. */
+    readonly agent_ref_mismatch: 'agent_ref_mismatch';
+    /** A strict Agent task id already names a durable attempt and cannot be re-enqueued. */
+    readonly agent_task_already_exists: 'agent_task_already_exists';
+    /** A first-write-wins Agent control record was replayed with a different body. */
+    readonly agent_content_request_mismatch: 'agent_content_request_mismatch';
+    /** A durable mailbox receipt id resolved to an envelope other than its exact acknowledgement. */
+    readonly mailbox_receipt_mismatch: 'mailbox_receipt_mismatch';
 };
 export type CloudErrorCode = (typeof CLOUD_ERROR_CODES)[keyof typeof CLOUD_ERROR_CODES];
 export declare class ByokCloudError extends Error {

package/dist/handlers/messages.d.ts

@@ -20,9 +20,20 @@
  * `duplicate` for whatever already landed.
  */
 import type { Context } from 'hono';
+import { type AgentContentReceiptPayload } from '@byok-sdk/protocol';
 import type { ActivityBounds } from '../coordination';
+import type { AgentEgressRecord } from '../stores/ports';
+import type { TenantStores } from '../tenant-stores';
 import { type DeviceRouteDeps } from './shared';
 export interface MessagesRouteDeps extends DeviceRouteDeps {
     readonly activityBounds: ActivityBounds;
+    /**
+     * The egress fact is committed by the inbound gate first. This callback then
+     * puts the exact receipt acknowledgement in the durable core mailbox, so a
+     * transport retry cannot turn a committed reliable event into an unacked one.
+     */
+    readonly appendReliableEgressAck: (stores: TenantStores, record: AgentEgressRecord) => Promise<void>;
+    /** Content receipt rows share the reliable spool/ack protocol but preserve their own exact payload authority. */
+    readonly appendContentReceiptAck: (stores: TenantStores, deviceId: string, payload: AgentContentReceiptPayload) => Promise<void>;
 }
 export declare function messagesHandler(deps: MessagesRouteDeps): (c: Context) => Promise<Response>;

package/dist/inbound.d.ts

@@ -9,9 +9,10 @@
  *    else, so a flood of garbage-typed envelopes costs the same budget as a
  *    flood of well-formed ones. S3a's reference limiter allows everything; the
  *    seam is what matters at this position.
- * 1. **type-allow** — only `DAEMON_TO_SERVER_TYPES` may pass. A server ->
- *    daemon type arriving inbound, or anything unrecognized, is rejected
- *    before it is dispatched or counted accepted.
+ * 1. **type-allow** — only `DAEMON_TO_SERVER_TYPES` may pass, plus the
+ *    authenticated long-poll `conn.hello` capability snapshot handled below.
+ *    A server -> daemon type arriving inbound, or anything unrecognized, is
+ *    rejected before it is dispatched or counted accepted.
  * 2. **ownership** — an envelope for a task already owned by a DIFFERENT
  *    device is dropped, never force-failed: force-failing on an authz mismatch
  *    would let an attacker who merely guesses a `taskId` kill the real owner's

package/dist/index.d.ts

@@ -15,8 +15,8 @@
 export { isTenantId, tenantId } from '@byok-sdk/core';
 export type { TenantId } from '@byok-sdk/core';
 export { createByokCloud } from './cloud';
-export type { ByokCloud, ByokCloudOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, EnqueuedOffer, } from './cloud';
-export { DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, } from './cloud';
+export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentContentReadInput, EnqueueOfferInput, EnqueueToolsetOfferInput, EnqueuedAgentControl, EnqueuedOffer, } from './cloud';
+export { AGENT_HOME_CONTRACT_CAPABILITY, DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, } from './cloud';
 export { DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, } from './handlers/board';
 export { DEFAULT_SKILL_PACK_PAGE_LIMIT } from './handlers/skill-packs';
 export { createInMemoryByokCloud } from './composition/in-memory';
@@ -59,8 +59,8 @@ export { DEFAULT_MAX_TRUTH_REQUEST_BYTES, DEVICE_PROOF_HEADER, MAX_DEVICE_PROOF_
 export type { PreparedTruthWrite, TruthBodyInput, TruthCommitInput, TruthCommitResponse, TruthCommitResult, TruthCommitter, TruthObjectDownloads, TruthRecordMetadata, TruthWriteRequest, } from './truth/contract';
 export { TruthCommitError, isTruthCommitError } from './truth/errors';
 export type { TruthCommitErrorCode } from './truth/errors';
-export { CLOUD_STORE_NAMES, TASK_ATTEMPT_STATUSES } from './stores/ports';
+export { BLOB_READ_ERROR_CODES, CLOUD_STORE_NAMES, TASK_ATTEMPT_STATUSES } from './stores/ports';
 export { CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS } from './stores/ports-contract';
-export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptStatus, TaskAttemptStore, } from './stores/ports';
-export { AllowAllRateLimiter, BLOB_URL_TTL_MS, DEDUP_RING_CAPACITY, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryActivityStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryRequestReceiptStore, InMemoryProofRequestReceiptStore, InMemoryTaskAttemptStore, NONCE_TTL_MS, createInMemoryBlobs, createInMemoryCloudStores, } from './stores/in-memory/index';
+export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobReadErrorCode, BlobReadResult, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptStatus, TaskAttemptStore, AgentRef, AgentEgressRecord, AgentEgressStore, TaskCancellationMutation, TaskCancellationRequest, TaskCancellationStore, } from './stores/ports';
+export { AllowAllRateLimiter, BLOB_URL_TTL_MS, DEDUP_RING_CAPACITY, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryActivityStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryRequestReceiptStore, InMemoryAgentEgressStore, InMemoryProofRequestReceiptStore, InMemoryTaskAttemptStore, InMemoryTaskCancellationStore, NONCE_TTL_MS, createInMemoryBlobs, createInMemoryCloudStores, } from './stores/in-memory/index';
 export type { InMemoryBlobStoreOptions, InMemoryBlobs, InMemoryCloudComposition, } from './stores/in-memory/index';