@byok-sdk/protocol 0.19.0 → 0.20.0

package/dist/input-preparation.d.ts

@@ -25,8 +25,41 @@ import { z } from 'zod';
  *    freeze-rule asymmetry. Adding a field post-freeze is therefore a
  *    breaking change, exactly like `PermissionPolicySchema`.
  */
-/** Capability required before a task-free remote input preparation is admitted. */
-export declare const AGENT_INPUT_PREPARATION_CAPABILITY: 'agent-input-preparation';
+/**
+ * The ONE version of the input-preparation contract, shared by this relay wire
+ * (the `agent.input.preparation` payload and the completion receipt summary)
+ * and by the device-local request, receipt and artifact
+ * (`@byok-sdk/client`'s `INPUT_PREPARATION_VERSION`, which is this value).
+ *
+ * The relay wire carries no version field of its own, so a version change is
+ * made visible where admission actually happens: in the capability token
+ * below. See `INPUT_PREPARATION_VERSION` in the client for what each version
+ * changed.
+ */
+export declare const INPUT_PREPARATION_WIRE_VERSION: 5;
+/**
+ * Capability required before a task-free remote input preparation — or a
+ * prepared Execution — is admitted: `agent-input-preparation-v<N>`, where
+ * `<N>` is {@link INPUT_PREPARATION_WIRE_VERSION}.
+ *
+ * The version is IN the token because the relay wire has none. A device
+ * declares exactly the one token of the contract it speaks, and a cloud admits
+ * exactly the one token of the contract it speaks, so a device and a cloud on
+ * different contract versions never exchange a preparation at all: the cloud
+ * refuses at enqueue (`agent_capability_missing`, before any receipt or
+ * mailbox row) instead of relaying a payload the other side would refuse with
+ * a strict-schema 422 and a device would then redeliver forever. There is no
+ * dual token and no accepted older one. The retired unversioned token
+ * `agent-input-preparation` (versions up to 4) is admitted nowhere.
+ *
+ * The token gates NEW admissions only. A row enqueued before a version cut is
+ * still in flight afterwards, and its completion is accepted only by a cloud
+ * on the same version as the device answering it; across the cut it is a 422
+ * and a stalled device cursor. Draining in-flight rows and upgrading cloud and
+ * devices as a pair is the operator precondition for the cut (`docs/spec.md`,
+ * bounded admission); nothing here parses an older receipt.
+ */
+export declare const AGENT_INPUT_PREPARATION_CAPABILITY: "agent-input-preparation-v5";
 /** The preparation surface uses the package-wide lowercase `sha256:<hex>` transport form. */
 export declare const InputPreparationContentHashSchema: z.ZodString;
 /**
@@ -424,13 +457,20 @@ export declare const InputPreparationContextDocumentSchema: z.ZodObject<{
     }, z.core.$strict>], "role">>;
 }, z.core.$strict>;
 export type InputPreparationContextDocument = z.infer<typeof InputPreparationContextDocumentSchema>;
-/** Durable lifecycle state of one local preparation record. */
+/**
+ * Durable lifecycle state of one local preparation record.
+ *
+ * `prepared` is the one successful terminal state: the artifact is compiled,
+ * persisted, and — when the device has an optional counter configured — its
+ * counter answered. A device with no counter reaches `prepared` without ever
+ * entering `counting`.
+ */
 export declare const InputPreparationStateSchema: z.ZodEnum<{
     cancelled: "cancelled";
-    counted: "counted";
     counter_interrupted: "counter_interrupted";
     counting: "counting";
     failed: "failed";
+    prepared: "prepared";
     reserved: "reserved";
 }>;
 export type InputPreparationState = z.infer<typeof InputPreparationStateSchema>;
@@ -440,11 +480,14 @@ export type InputPreparationState = z.infer<typeof InputPreparationStateSchema>;
  *
  * `ready` means the preparation CAN BE CONSUMED — the artifact is intact and
  * unexpired, the native compiler's projection is content-complete, every
- * residual key is ruled by an applicable Host accounting policy, the count is
- * present and bound to that exact projection, and every executor identity is
- * attested. It is deliberately NOT Host budget admission: the device performs
- * no budget arithmetic, so a ready receipt says the evidence holds, never that
- * the spend is allowed.
+ * residual key is ruled by an applicable Host accounting policy, D is text
+ * only, every executor identity is attested, and — only when the device has an
+ * optional counter configured — that count is provider-authoritative and
+ * covered. No count is required: the size evidence is
+ * `artifact.requestBytes`, the exact byte length of the frozen D. It is
+ * deliberately NOT Host budget admission: the device performs no budget
+ * arithmetic, so a ready receipt says the evidence holds, never that the
+ * spend fits a window.
  */
 export declare const InputPreparationReadinessReasonSchema: z.ZodEnum<{
     accounting_policy_inapplicable: "accounting_policy_inapplicable";
@@ -454,11 +497,11 @@ export declare const InputPreparationReadinessReasonSchema: z.ZodEnum<{
     counter_authority_not_production: "counter_authority_not_production";
     counter_coverage_incomplete: "counter_coverage_incomplete";
     counter_interrupted: "counter_interrupted";
-    counter_missing: "counter_missing";
     executor_identity_unproven: "executor_identity_unproven";
     failed: "failed";
-    not_counted: "not_counted";
+    not_prepared: "not_prepared";
     projection_unknown: "projection_unknown";
+    request_content_not_text: "request_content_not_text";
     residual_not_ruled: "residual_not_ruled";
     runtime_contract_superseded: "runtime_contract_superseded";
 }>;
@@ -529,7 +572,9 @@ export declare const InputPreparationCounterProviderEvidenceSchema: z.ZodObject<
     }, z.core.$strict>;
 }, z.core.$strict>;
 /**
- * Counter evidence exactly as the device's adapter reported it.
+ * Counter evidence exactly as the device's OPTIONAL adapter reported it.
+ * Absent when the device has no counter configured, which is a legal, ready-
+ * capable state: the size evidence is `artifact.requestBytes`.
  *
  * `authority: 'test_fixture'` is a first-class value, not a debug flag: a
  * fixture result can never produce a ready receipt, which is what keeps an
@@ -542,10 +587,6 @@ export declare const InputPreparationCounterEvidenceSchema: z.ZodObject<{
         provider: "provider";
         test_fixture: "test_fixture";
     }>;
-    kind: z.ZodEnum<{
-        bound: "bound";
-        count: "count";
-    }>;
     value: z.ZodNumber;
     coverage: z.ZodObject<{
         covered: z.ZodBoolean;
@@ -739,10 +780,10 @@ export declare const InputPreparationReceiptSummarySchema: z.ZodObject<{
     reference: z.ZodString;
     state: z.ZodEnum<{
         cancelled: "cancelled";
-        counted: "counted";
         counter_interrupted: "counter_interrupted";
         counting: "counting";
         failed: "failed";
+        prepared: "prepared";
         reserved: "reserved";
     }>;
     binding: z.ZodObject<{
@@ -825,10 +866,6 @@ export declare const InputPreparationReceiptSummarySchema: z.ZodObject<{
             provider: "provider";
             test_fixture: "test_fixture";
         }>;
-        kind: z.ZodEnum<{
-            bound: "bound";
-            count: "count";
-        }>;
         value: z.ZodNumber;
         coverage: z.ZodObject<{
             covered: z.ZodBoolean;
@@ -860,11 +897,11 @@ export declare const InputPreparationReceiptSummarySchema: z.ZodObject<{
         counter_authority_not_production: "counter_authority_not_production";
         counter_coverage_incomplete: "counter_coverage_incomplete";
         counter_interrupted: "counter_interrupted";
-        counter_missing: "counter_missing";
         executor_identity_unproven: "executor_identity_unproven";
         failed: "failed";
-        not_counted: "not_counted";
+        not_prepared: "not_prepared";
         projection_unknown: "projection_unknown";
+        request_content_not_text: "request_content_not_text";
         residual_not_ruled: "residual_not_ruled";
         runtime_contract_superseded: "runtime_contract_superseded";
     }>>;
@@ -895,7 +932,7 @@ export declare const InputPreparationReferenceSchema: z.ZodString;
  * `artifactDigest` is optional for one structural reason, not as a compatibility
  * seam: a receipt discloses `artifact` only once there is one
  * ({@link InputPreparationArtifactSummarySchema} is optional on the receipt), so
- * a Host holding a not-yet-counted receipt has no envelope digest to re-present.
+ * a Host holding a not-yet-prepared receipt has no envelope digest to re-present.
  * When it is present it is compared like everything else.
  */
 export declare const InputPreparationOfferBindingSchema: z.ZodObject<{
@@ -922,6 +959,7 @@ export declare const InputPreparationRejectionReasonSchema: z.ZodEnum<{
     counter_unavailable: "counter_unavailable";
     deadline_elapsed: "deadline_elapsed";
     durable_write_failed: "durable_write_failed";
+    input_preparation_record_log_unsupported: "input_preparation_record_log_unsupported";
     input_preparation_unconfigured: "input_preparation_unconfigured";
     launch_boundary_unavailable: "launch_boundary_unavailable";
     limit_exceeded: "limit_exceeded";

package/dist/messages.d.ts

@@ -1509,6 +1509,34 @@ export declare const TerminalInferenceUsageSchema: z.ZodObject<{
     reportedAt: z.ZodISODateTime;
 }, z.core.$strip>;
 export type TerminalInferenceUsage = z.infer<typeof TerminalInferenceUsageSchema>;
+/**
+ * The prepared-only terminal observation: what the runtime reported about the
+ * provider calls of ONE prepared Execution, bound to the frozen request it
+ * launched.
+ *
+ * - `requestDigest` — the frozen artifact's own request digest
+ *   (`InputPreparationArtifactSummarySchema.requestDigest`), so the Host
+ *   compares these numbers against exactly the D whose `requestBytes` it
+ *   ruled on.
+ * - `initialPromptTokens` — the prompt tokens of the FIRST provider call. It
+ *   is the only call whose request is D; every later call is an ordinary tool
+ *   continuation. Prompt tokens are the provider's whole prompt, cache reads
+ *   and writes included.
+ * - `maxPromptTokens` — the largest prompt of any provider call of the
+ *   Execution, so `maxPromptTokens >= initialPromptTokens`.
+ *
+ * A separate field, deliberately NOT {@link TerminalInferenceUsageSchema}:
+ * that one is telemetry and never task-state authority, while this one is the
+ * evidence a Host checks its own budget ruling against. The device performs no
+ * budget arithmetic over it. Strict, like every other control shape: an
+ * unrecognized field is rejected, not stripped.
+ */
+export declare const TerminalPreparedObservationSchema: z.ZodObject<{
+    requestDigest: z.ZodString;
+    initialPromptTokens: z.ZodNumber;
+    maxPromptTokens: z.ZodNumber;
+}, z.core.$strict>;
+export type TerminalPreparedObservation = z.infer<typeof TerminalPreparedObservationSchema>;
 /**
  * daemon -> server: task finished successfully.
  *
@@ -1561,6 +1589,11 @@ export declare const TaskCompletePayloadSchema: z.ZodObject<{
         clientVersion: z.ZodString;
         reportedAt: z.ZodISODateTime;
     }, z.core.$strip>>;
+    preparedObservation: z.ZodOptional<z.ZodObject<{
+        requestDigest: z.ZodString;
+        initialPromptTokens: z.ZodNumber;
+        maxPromptTokens: z.ZodNumber;
+    }, z.core.$strict>>;
     agentRef: z.ZodOptional<z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
@@ -1590,6 +1623,11 @@ export declare const TaskFailPayloadSchema: z.ZodObject<{
         clientVersion: z.ZodString;
         reportedAt: z.ZodISODateTime;
     }, z.core.$strip>>;
+    preparedObservation: z.ZodOptional<z.ZodObject<{
+        requestDigest: z.ZodString;
+        initialPromptTokens: z.ZodNumber;
+        maxPromptTokens: z.ZodNumber;
+    }, z.core.$strict>>;
     agentRef: z.ZodOptional<z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
@@ -3183,6 +3221,11 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             clientVersion: z.ZodString;
             reportedAt: z.ZodISODateTime;
         }, z.core.$strip>>;
+        preparedObservation: z.ZodOptional<z.ZodObject<{
+            requestDigest: z.ZodString;
+            initialPromptTokens: z.ZodNumber;
+            maxPromptTokens: z.ZodNumber;
+        }, z.core.$strict>>;
         agentRef: z.ZodOptional<z.ZodObject<{
             agentId: z.ZodString;
             profileRevision: z.ZodString;
@@ -3210,6 +3253,11 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             clientVersion: z.ZodString;
             reportedAt: z.ZodISODateTime;
         }, z.core.$strip>>;
+        preparedObservation: z.ZodOptional<z.ZodObject<{
+            requestDigest: z.ZodString;
+            initialPromptTokens: z.ZodNumber;
+            maxPromptTokens: z.ZodNumber;
+        }, z.core.$strict>>;
         agentRef: z.ZodOptional<z.ZodObject<{
             agentId: z.ZodString;
             profileRevision: z.ZodString;

package/dist/version.d.ts

@@ -107,5 +107,5 @@ export declare const STRICT_AGENT_ONLY_CAPABILITY: 'strict-agent-only';
  * cannot accidentally execute the instruction without the required tools.
  */
 export declare const CUSTOM_HARNESS_CAPABILITY: 'custom-harness';
-export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'result-document', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead"];
+export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'result-document', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v5", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead"];
 export type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/protocol",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "BYOK SDK wire protocol: envelope schema, message types, and codec helpers",
   "type": "module",
   "license": "MIT",