@byok-sdk/cloud 0.18.0 → 0.20.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/terminal-result.d.ts

@@ -1,4 +1,4 @@
-import { type AgentRef, type BlobRef, type Envelope, type TerminalInferenceUsage, type TaskFailPayload } from '@byok-sdk/protocol';
+import { type AgentRef, type BlobRef, type Envelope, type TerminalInferenceUsage, type TerminalPreparedObservation, type TaskFailPayload } from '@byok-sdk/protocol';
 import type { RequestReceipt } from './stores/ports';
 /** Canonical device evidence, independent of the Host cancellation projection. */
 export interface DeviceTerminal {
@@ -39,6 +39,14 @@ export interface TerminalResult {
      * or entitlement authority.
      */
     readonly usage?: TerminalInferenceUsage;
+    /**
+     * The prepared-only observation copied verbatim from a prepared Execution's
+     * winning `task.complete` / `task.fail`: the frozen request digest, the
+     * first provider call's prompt tokens and the largest. Unlike `usage` it is
+     * evidence the Host checks its own budget ruling against; the cloud performs
+     * no arithmetic over it.
+     */
+    readonly preparedObservation?: TerminalPreparedObservation;
     readonly reason?: string;
     /** Terminal cause projection; currently the protocol's terminal reason. */
     readonly terminalCause?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud",
-  "version": "0.18.0",
+  "version": "0.20.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.18.0",
-    "@byok-sdk/protocol": "0.18.0",
+    "@byok-sdk/core": "0.20.0",
+    "@byok-sdk/protocol": "0.20.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }