@byok-sdk/cloud 0.17.0 → 0.19.0

package/dist/input-preparations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Durable remote input-preparation facts.
+ *
+ * Exactly the composition `agent-home-projections.ts` uses, for exactly the
+ * same reason: the desired request and the terminal completion are two
+ * IMMUTABLE first-write-wins receipts in the tenant-scoped receipt store, so
+ * this module needs no second mutable authority merely to survive a restart,
+ * and a replayed write is decided by comparing bodies rather than by trusting
+ * whichever writer arrived last.
+ *
+ * The one idempotency key is `(deviceId, agentRef, requestId)`, minted by the
+ * Host and carried unchanged through the cloud receipt, the device's durable
+ * namespace and the completion. A Host that times out therefore RE-READS
+ * status; it never mints a second requestId for the same turn, which is what
+ * keeps a duplicate from becoming a second counter call downstream.
+ */
+import { type AgentInputPreparationPayload, type InputPreparationCompletionRequest, type InputPreparationReadback } from '@byok-sdk/protocol';
+import type { TenantId } from '@byok-sdk/core';
+import type { TenantBoundReceipts } from './tenant-stores';
+/** Exact request identity a host must echo to read back durable preparation status. */
+export interface InputPreparationReceiptInput {
+    readonly requestId: string;
+    readonly agentRef: AgentInputPreparationPayload['agentRef'];
+}
+export declare function inputPreparationRequestKey(deviceId: string, agentRef: AgentInputPreparationPayload['agentRef'], requestId: string): string;
+export declare function inputPreparationCompletionKey(deviceId: string, agentRef: AgentInputPreparationPayload['agentRef'], requestId: string): string;
+/**
+ * Whole-body equality, not a field subset.
+ *
+ * The desired fact is the ENTIRE authorized request — source digest, model
+ * selection, deadline, context and required toolsets alike. Comparing only the
+ * identity fields would let the same requestId silently re-bind to a different
+ * model, a different context or a looser deadline, which is precisely the
+ * substitution the immutable receipt exists to prevent. Both sides are already
+ * schema-parsed, so key order is the only degree of freedom left, and the
+ * stored body is re-serialized from a parse for that reason.
+ */
+export declare function sameInputPreparationRequest(expected: AgentInputPreparationPayload, actual: AgentInputPreparationPayload): boolean;
+export declare function receiptMatchesInputPreparation(request: AgentInputPreparationPayload, receipt: InputPreparationCompletionRequest): boolean;
+export declare function statusInputMatchesInputPreparation(request: AgentInputPreparationPayload, input: InputPreparationReceiptInput): boolean;
+export declare function readInputPreparationStatus(receipts: TenantBoundReceipts, tenant: TenantId, deviceId: string, input: InputPreparationReceiptInput): Promise<InputPreparationReadback | undefined>;
+export declare function recordInputPreparationCompletion(receipts: TenantBoundReceipts, tenant: TenantId, deviceId: string, receiptInput: InputPreparationCompletionRequest): Promise<InputPreparationReadback>;

package/dist/recurring.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+/** Persist this validated input before dispatch; the Host owns Turn/generation and outbox. */
+export declare const RecurringExecutionInputSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    deviceId: z.ZodString;
+    payload: z.ZodObject<{
+        instruction: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            blobRef: z.ZodObject<{
+                blobId: z.ZodString;
+                contentHash: z.ZodString;
+                size: z.ZodNumber;
+                contentType: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strict>]>;
+        policy: z.ZodObject<{
+            mode: z.ZodEnum<{
+                auto: "auto";
+                confirm: "confirm";
+                plan: "plan";
+                readonly: "readonly";
+            }>;
+            allowTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            denyTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            workspaceRoot: z.ZodOptional<z.ZodString>;
+            network: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        agentRef: z.ZodObject<{
+            agentId: z.ZodString;
+            profileRevision: z.ZodString;
+        }, z.core.$strict>;
+        requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        runtime: z.ZodNonOptional<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            pi: "pi";
+        }>>>;
+        harnessId: z.ZodOptional<z.ZodString>;
+        dispatchSelection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            lane: z.ZodLiteral<"subscription">;
+            runtimeId: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+            }>;
+            providerId: z.ZodNull;
+            modelId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            lane: z.ZodLiteral<"byok">;
+            runtimeId: z.ZodLiteral<"pi">;
+            providerId: z.ZodString;
+            modelId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            lane: z.ZodLiteral<"byok-profile">;
+            runtimeId: z.ZodLiteral<"pi">;
+            providerProfile: z.ZodObject<{
+                profileRef: z.ZodString;
+                profileRevision: z.ZodString;
+                profileHash: z.ZodString;
+                modelId: z.ZodString;
+                requiredCapabilities: z.ZodArray<z.ZodEnum<{
+                    "image-input": "image-input";
+                }>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "lane">>;
+        terminalProjection: z.ZodNonOptional<z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"none">;
+        }, z.core.$strict>, z.ZodObject<{
+            mode: z.ZodLiteral<"result-document">;
+            contract: z.ZodString;
+        }, z.core.$strict>], "mode">>>;
+        limits: z.ZodOptional<z.ZodObject<{
+            maxDurationMs: z.ZodOptional<z.ZodNumber>;
+            maxTokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        egressPolicy: z.ZodObject<{
+            policyRevision: z.ZodString;
+            activity: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                mode: z.ZodLiteral<"metadata-status">;
+                delivery: z.ZodLiteral<"latest-value">;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"contentful-trajectory">;
+                delivery: z.ZodLiteral<"latest-value">;
+                maxCoalesceMs: z.ZodNumber;
+                maxEventBytes: z.ZodNumber;
+            }, z.core.$strict>], "mode">;
+            reliable: z.ZodObject<{
+                maxPendingEventsPerAgent: z.ZodNumber;
+                maxPendingBytesPerAgent: z.ZodNumber;
+                maxPendingBytesPerTenant: z.ZodNumber;
+            }, z.core.$strict>;
+            transfers: z.ZodObject<{
+                workspace: z.ZodUnion<readonly [z.ZodLiteral<"disabled">, z.ZodObject<{
+                    maxBytes: z.ZodNumber;
+                    allowedMimeTypes: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>]>;
+                transcript: z.ZodUnion<readonly [z.ZodLiteral<"disabled">, z.ZodObject<{
+                    maxBytes: z.ZodNumber;
+                    allowedMimeTypes: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>]>;
+                artifact: z.ZodUnion<readonly [z.ZodLiteral<"disabled">, z.ZodObject<{
+                    maxBytes: z.ZodNumber;
+                    allowedMimeTypes: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>]>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        messageEgress: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
+            mode: z.ZodLiteral<"required">;
+            contract: z.ZodString;
+            contentType: z.ZodEnum<{
+                "text/markdown": "text/markdown";
+                "text/plain": "text/plain";
+            }>;
+            maxBytes: z.ZodNumber;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    agentMessageContext: z.ZodObject<{
+        destinationBinding: z.ZodString;
+        freshnessCursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RecurringExecutionInput = z.infer<typeof RecurringExecutionInputSchema>;

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

@@ -43,6 +43,10 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
         readonly messageId: string;
         readonly payloadBody: string;
     }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readTaskAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     readAgentMessage(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;

package/dist/stores/ports.d.ts

@@ -331,6 +331,11 @@ export interface TaskAttemptStore {
         readonly messageId: string;
         readonly payloadBody: string;
     }): Promise<'reserved' | 'pending' | 'rejected'>;
+    /** Discover the unique immutable message for a tenant/device/task; caller validates its frozen Agent binding. */
+    readTaskAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     /** Read only an exact reservation; conflicting task/message bindings are not observable. */
     readAgentMessage(tenant: TenantId, input: {
         readonly taskId: string;

package/dist/task-agent-message.d.ts

@@ -0,0 +1,11 @@
+import { type AgentRef, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentMessageDispositionPayload } from '@byok-sdk/protocol';
+import type { TenantStores } from './tenant-stores';
+/** SDK transmission evidence; payload remains untrusted and never authors a Host product message. */
+export interface TaskAgentMessage {
+    readonly payload: AgentMessagePublishPayload;
+    readonly context: AgentMessageServerContext;
+    /** Absent while the exact first-message reservation remains pending. */
+    readonly disposition?: AgentMessageDispositionPayload;
+}
+/** Discover the one durable message without requiring the Host to have received its body. */
+export declare function readTaskAgentMessage(stores: TenantStores, deviceId: string, taskId: string, expectedRef: AgentRef): Promise<TaskAgentMessage | undefined>;

package/dist/tenant-stores.d.ts

@@ -87,6 +87,10 @@ export interface TenantBoundTaskAttempts {
         readonly messageId: string;
         readonly payloadBody: string;
     }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readTaskAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+    }): Promise<import('./stores/ports').AgentMessageAdmission | undefined>;
     readAgentMessage(input: {
         readonly taskId: string;
         readonly deviceId: string;

package/dist/terminal-result.d.ts

@@ -1,5 +1,13 @@
-import { type AgentRef, type BlobRef, type TerminalInferenceUsage, type TaskFailPayload } from '@byok-sdk/protocol';
+import { type AgentRef, type BlobRef, type Envelope, type TerminalInferenceUsage, type TaskFailPayload } from '@byok-sdk/protocol';
 import type { RequestReceipt } from './stores/ports';
+/** Canonical device evidence, independent of the Host cancellation projection. */
+export interface DeviceTerminal {
+    readonly envelope: Extract<Envelope, {
+        type: 'task.complete' | 'task.fail' | 'task.decline' | 'task.cancelled';
+    }>;
+    readonly recordedAt: string;
+}
+export declare function readDeviceTerminalReceipt(taskId: string, receipt: RequestReceipt): DeviceTerminal;
 /**
  * The typed terminal read model — the hosted counterpart of the embedded
  * coordinator's `TaskResult`, projected off the receipt the inbound gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud",
-  "version": "0.17.0",
+  "version": "0.19.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.17.0",
-    "@byok-sdk/protocol": "0.17.0",
+    "@byok-sdk/core": "0.19.0",
+    "@byok-sdk/protocol": "0.19.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }