@byok-sdk/cloud 0.16.0 → 0.18.0

package/README.md

@@ -69,3 +69,16 @@ stored body is not a terminal envelope throws `ByokCloudError` rather than
 returning a best-effort shape.
 
 MIT licensed. Node.js 22.22.0 or newer.
+
+
+## Immutable offer readback
+
+`readTaskOffer(tenant, taskId)` reads the immutable offer receipt using the
+TaskAttempt target and stable message identity. It validates the protocol
+payload, target/Agent binding and delivered marker. Corrupt receipts throw;
+missing attempt or missing offer receipt returns undefined. The returned
+recordedAt is receipt time, not transport time; no mailbox sequence is invented.
+A delivered=false read is not evidence that append never happened. Host-only
+message context is a separate authority, not part of this offer projection.
+The API's persistence is that of the injected receipts store: in-memory restart
+and Postgres generic receipt retention are not upgraded by this read method.

package/dist/cloud.d.ts

@@ -1,3 +1,5 @@
+import { type TaskAgentMessage } from './task-agent-message';
+import { type RecurringExecutionInput } from './recurring';
 /**
  * `createByokCloud` — the hosted device surface, assembled.
  *
@@ -17,7 +19,7 @@
 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 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 Envelope, type TaskOfferType, type AgentRef, type AgentContentReadPayload, type AgentMessageDispositionPayload, 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';
@@ -25,7 +27,7 @@ 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, TaskAttemptListQuery, TaskAttemptPage } from './stores/ports';
-import { type TerminalResult } from './terminal-result';
+import { type DeviceTerminal, type TerminalResult } from './terminal-result';
 import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
 /** Matches the reference server's ceiling (§7). */
 export declare const DEFAULT_MAX_BLOB_SIZE_BYTES: number;
@@ -199,6 +201,22 @@ export interface EnqueuedAgentControl {
 export interface EnqueuedAgentHomeProjection extends EnqueuedAgentControl {
     readonly status: AgentHomeProjectionReadback;
 }
+/** Immutable executable offer authority, independent of mailbox retention. */
+export type TaskOfferReadback = {
+    [T in TaskOfferType]: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly type: T;
+        readonly payload: Extract<Envelope, {
+            type: T;
+        }>['payload'];
+        /** Receipt time, not a transport delivery timestamp. */
+        readonly recordedAt: string;
+        /** The delivered marker is durable; false is not proof append never happened. */
+        readonly delivered: boolean;
+    };
+}[TaskOfferType];
 export interface EnqueuedOffer {
     readonly taskId: string;
     /** The per-(tenant, device) delivery seq — the daemon's redelivery cursor position for this envelope. */
@@ -248,6 +266,8 @@ export interface ByokCloud {
      * mailbox reservation, so older resume-only daemons never receive it.
      */
     enqueueFreshAgentEgressOffer(tenant: TenantId, deviceId: string, input: AgentEgressFreshSessionDispatchInput): Promise<EnqueuedOffer>;
+    /** Strict recurring execution: caller persists the complete input before submission. */
+    submitRecurringExecution(tenant: TenantId, input: RecurringExecutionInput): Promise<EnqueuedOffer>;
     /** Host control plane: request one policy-bound content read without a task fallback. */
     enqueueAgentContentRead(tenant: TenantId, deviceId: string, input: AgentContentReadInput): Promise<EnqueuedAgentControl>;
     /** Durable, task-free projection request for precisely one admitted device. */
@@ -325,6 +345,8 @@ export interface ByokCloud {
      */
     steerTask(tenant: TenantId, taskId: string, payload: TaskSteerPayload): Promise<EnqueuedAgentControl>;
     readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    /** Read the original executable offer; missing/corrupt authority never becomes a guessed payload. */
+    readTaskOffer(tenant: TenantId, taskId: string): Promise<TaskOfferReadback | undefined>;
     /**
      * Host control plane: one bounded page of this tenant's task attempts,
      * keyset-paged by `taskId` — see {@link TaskAttemptListQuery} for why the key
@@ -337,6 +359,16 @@ export interface ByokCloud {
     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>;
+    /** Actual device terminal only; cancellation intent never creates this observation. */
+    readDeviceTerminal(tenant: TenantId, taskId: string): Promise<DeviceTerminal | undefined>;
+    /** Discover first-message transmission evidence from the frozen execution binding, including pending/held without a Host body. */
+    readTaskAgentMessage(tenant: TenantId, deviceId: string, taskId: string, agentRef: AgentRef): Promise<TaskAgentMessage | undefined>;
+    /**
+     * Exact durable message decision, independently of task cancellation/terminal.
+     * Missing or pending admission returns undefined; invalid persisted evidence
+     * throws. The Host supplies the complete original payload, not a Turn ID.
+     */
+    readAgentMessageDisposition(tenant: TenantId, deviceId: string, taskId: string, payload: AgentMessagePublishPayload): Promise<AgentMessageDispositionPayload | 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>;
     /**

package/dist/inbound.d.ts

@@ -83,6 +83,7 @@ export declare function handleAgentMessagePublish(stores: TenantStores, deviceId
 }>;
 /** Reads only a terminal immutable admission; pending rows have no disposition to acknowledge. */
 export declare function readAgentMessageDisposition(stores: TenantStores, deviceId: string, taskId: string, payload: AgentMessagePublishPayload): Promise<AgentMessageDispositionPayload | undefined>;
+export declare function parseAgentMessageDisposition(payload: AgentMessagePublishPayload, terminalBody: string): AgentMessageDispositionPayload;
 /** Receipt key a task's terminal is recorded under — the idempotency seam S3b's journal will share. */
 export declare function terminalReceiptKey(taskId: string): string;
 export declare function handleInboundEnvelope(stores: TenantStores, deviceId: string, envelope: Envelope, activityBounds?: ActivityBounds, agentMessageConsume?: Parameters<typeof handleAgentMessagePublish>[4], observer?: ByokCloudObserver): Promise<InboundOutcome>;

package/dist/index.d.ts

@@ -15,7 +15,8 @@
 export { isTenantId, tenantId } from '@byok-sdk/core';
 export type { TenantId } from '@byok-sdk/core';
 export { createByokCloud } from './cloud';
-export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentEgressFreshSessionDispatchInput, AgentContentReadInput, AgentHomeProjectionInput, AgentHomeProjectionStatusInput, ApproveTaskOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, RejectTaskOptions, EnqueuedAgentControl, EnqueuedAgentHomeProjection, EnqueuedOffer, } from './cloud';
+export type { TaskAgentMessage } from './task-agent-message';
+export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentEgressFreshSessionDispatchInput, AgentContentReadInput, AgentHomeProjectionInput, AgentHomeProjectionStatusInput, ApproveTaskOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, RejectTaskOptions, EnqueuedAgentControl, EnqueuedAgentHomeProjection, EnqueuedOffer, TaskOfferReadback, } from './cloud';
 export { agentHomeProjectionCompletionKey, agentHomeProjectionRequestKey, readAgentHomeProjectionStatus, recordAgentHomeProjectionCompletion, } from './agent-home-projections';
 export type { AgentHomeProjectionReceiptInput } from './agent-home-projections';
 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';
@@ -72,3 +73,5 @@ export { CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS } from './stores/ports-contra
 export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobReadErrorCode, BlobReadResult, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, PairingEnrollment, PairingEnrollmentInput, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptListQuery, TaskAttemptPage, TaskAttemptStatus, TaskAttemptStore, AgentRef, AgentEgressRecord, AgentEgressStore, AgentMessageAdmission, 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';
+export type { DeviceTerminal } from './terminal-result';
+export { RecurringExecutionInputSchema, type RecurringExecutionInput } from './recurring';