@vtxmacro/cli 2026.9.19 → 2026.9.20

package/README.md

@@ -250,10 +250,22 @@ vtx inference-host agent-next --wait-seconds 50 --json
 That is the **Provider** loop. `agent-next` returns separate exact
 `system_prompt`, `user_prompt`,
 `context_json`, and `output_schema_json` fields. The agent reasons in its own
-session, then writes one JSON object to `agent-complete` stdin. At minimum that
-object contains a `result` string. If the harness exposes exact token usage,
-include the published usage object; otherwise VTX records usage as explicitly
-unavailable. For `agent-fail`, choose the truthful dispatch state and set
+session, then writes one JSON object to `agent-complete` stdin. The CLI reports
+its actual release version and negotiates `foreground_v1` Provider freshness.
+Prewarm the harness before requesting work. For Server Mode jobs, the handoff includes
+`provider_dispatch_not_after`, `provider_dispatch_local_not_after`, and
+`provider_dispatch_freshness_remaining_ms`; the local deadline and remaining
+budget account conservatively for RPC time and pending-request replay. Enforce
+both deadlines immediately before the real provider request. If either expires
+before dispatch, do not send stale work: use `agent-fail` with
+`dispatch_outcome: not_dispatched`, `failure_category: freshness`,
+`failure_code: provider_dispatch_freshness_expired`, and `retryable: false`.
+Completion contains a `result` string; negotiated server jobs also require
+`provider_dispatched_at`, the ISO 8601 timestamp captured at provider request
+entry. This is harness-reported evidence, not provider attestation. If the harness
+exposes exact token usage, include the published usage object; otherwise VTX
+records usage as explicitly unavailable. For `agent-fail`, choose the truthful
+dispatch state and set
 `retryable` true only when a fresh attempt is safe:
 
 ```json

package/bin/vtx-service-bootstrap.js

@@ -16,7 +16,7 @@ import { fileURLToPath } from "node:url";
 // agent-cli-release.json
 var agent_cli_release_default = {
   package_name: "@vtxmacro/cli",
-  package_version: "2026.9.19",
+  package_version: "2026.9.20",
   codex_package_name: "@openai/codex",
   codex_version: "0.153.3",
   copilot_sdk_package_name: "@github/copilot-sdk",

package/bin/vtx.js

@@ -69,7 +69,7 @@ var init_agent_cli_release = __esm({
   "agent-cli-release.json"() {
     agent_cli_release_default = {
       package_name: "@vtxmacro/cli",
-      package_version: "2026.9.19",
+      package_version: "2026.9.20",
       codex_package_name: "@openai/codex",
       codex_version: "0.153.3",
       copilot_sdk_package_name: "@github/copilot-sdk",
@@ -15014,12 +15014,16 @@ var init_external_inference_contract = __esm({
       authenticated_account_plan: safeCodeSchema.nullable().optional(),
       protocol_version: protocolVersionSchema,
       host_runtime_version: protocolVersionSchema.optional(),
+      provider_dispatch_freshness_contract: external_exports.literal("foreground_v1").optional(),
       envelope_public_key: base64Url32BytesSchema,
       health: external_exports.enum(["healthy", "degraded", "draining"]),
       advertised_at: timestampSchema,
       expires_at: timestampSchema,
       models: external_exports.array(advertisedModelSchema).min(1).max(64)
     }).superRefine((value, context) => {
+      if (value.provider_dispatch_freshness_contract !== void 0 && !/^\d+\.\d+\.\d+$/.test(value.host_runtime_version ?? "")) {
+        context.addIssue({ code: "custom", message: "Foreground freshness contract requires a numeric runtime version." });
+      }
       const modelIds = value.models.map((model) => model.model_id);
       if (new Set(modelIds).size !== modelIds.length) {
         context.addIssue({
@@ -15420,12 +15424,17 @@ var init_external_inference_contract = __esm({
       model_id: identifierSchema,
       model_label: displayNameSchema,
       reasoning_effort: reasoningEffortSchema,
-      requested_at: timestampSchema
+      requested_at: timestampSchema,
+      host_runtime_version: external_exports.string().regex(/^\d+\.\d+\.\d+$/).optional(),
+      provider_dispatch_freshness_contract: external_exports.literal("foreground_v1").optional()
+    }).refine((value) => value.host_runtime_version === void 0 === (value.provider_dispatch_freshness_contract === void 0), {
+      message: "Foreground freshness negotiation requires the actual CLI version."
     });
     agentNextRequestSchema = external_exports.strictObject({
       operation_id: operationIdentifierSchema,
       host_id: identifierSchema,
-      requested_at: timestampSchema
+      requested_at: timestampSchema,
+      provider_dispatch_freshness_contract: external_exports.literal("foreground_v1").optional()
     });
     agentHeartbeatRequestSchema = external_exports.strictObject({
       operation_id: operationIdentifierSchema,
@@ -15449,6 +15458,9 @@ var init_external_inference_contract = __esm({
       requested_reasoning_effort: reasoningEffortSchema,
       output_schema_version: protocolVersionSchema,
       deadline_at: timestampSchema,
+      provider_dispatch_freshness_contract: external_exports.literal("foreground_v1").optional(),
+      provider_dispatch_not_after: timestampSchema.optional(),
+      provider_dispatch_freshness_remaining_ms: nonNegativeSafeIntegerSchema.optional(),
       system_prompt: boundedPromptTextSchema,
       system_prompt_sha256: sha256HexSchema,
       user_prompt: boundedPromptTextSchema,
@@ -15458,6 +15470,14 @@ var init_external_inference_contract = __esm({
       output_schema_json: boundedJsonTextSchema,
       output_schema_sha256: sha256HexSchema
     }).superRefine((value, context) => {
+      const freshnessFields = [
+        value.provider_dispatch_freshness_contract,
+        value.provider_dispatch_not_after,
+        value.provider_dispatch_freshness_remaining_ms
+      ];
+      if (freshnessFields.some((field) => field !== void 0) && (freshnessFields.some((field) => field === void 0) || value.execution_mode !== "server")) {
+        context.addIssue({ code: "custom", message: "Foreground freshness handoff is incomplete." });
+      }
       for (const [field, exact, digest] of [
         ["system_prompt", value.system_prompt, value.system_prompt_sha256],
         ["user_prompt", value.user_prompt, value.user_prompt_sha256],
@@ -15489,7 +15509,8 @@ var init_external_inference_contract = __esm({
       time_to_first_token_ms: nonNegativeSafeIntegerSchema.nullable().optional(),
       finish_reason: safeCodeSchema.nullable().optional(),
       refusal_status: external_exports.enum(["none", "refused", "blocked", "unknown"]),
-      completed_at: timestampSchema
+      completed_at: timestampSchema,
+      provider_dispatched_at: timestampSchema.nullable().optional()
     }).superRefine((value, context) => {
       if (value.time_to_first_token_ms !== void 0 && value.time_to_first_token_ms !== null && value.time_to_first_token_ms > value.latency_ms) {
         context.addIssue({
@@ -19850,7 +19871,7 @@ var init_mcp_client = __esm({
           const hasPublicToolErrorMarker = hasStructuredPublicToolErrorMarker || errorText.includes(PUBLIC_TOOL_ERROR_PREFIX);
           const completionEvidenceExpired = name === "inference.job.complete" && (publicToolError ? publicToolError.failure_code === "completion_evidence_expired" && publicToolError.phase === "validation" && publicToolError.retryable === false && publicToolError.terminal_before_execution === true : !hasPublicToolErrorMarker && errorText.includes("External inference completion evidence window expired"));
           const hostNotClaimable = name === "inference.job.claim" && publicToolError?.failure_code === "host_not_claimable" && publicToolError.phase === "admission" && publicToolError.retryable === true && publicToolError.terminal_before_execution === true;
-          const definitivelyNotApplied = (name === "inference.host.register" || name === "inference.host.advertise") && (errorText.includes("Advertisement time is outside the allowed clock skew.") || errorText.includes("Advertisement is already expired.")) || (name === "inference.agent.next" || name === "inference.agent.heartbeat") && (errorText.includes("Advertisement time is outside the allowed clock skew.") || errorText.includes("Advertisement is already expired.") || errorText.includes("Heartbeat time is outside the allowed clock skew.")) || name === "inference.host.heartbeat" && errorText.includes("Heartbeat time is outside the allowed clock skew.") || name === "inference.job.claim" && (errorText.includes(
+          const definitivelyNotApplied = name === "inference.agent.decision.submit" && publicToolError?.phase === "validation" && publicToolError.retryable === false && publicToolError.terminal_before_execution === true && (publicToolError.failure_code === "agent_decision_schema_invalid" || publicToolError.failure_code === "invalid_arguments" && publicToolError.reason_code === "schema_validation") || (name === "inference.host.register" || name === "inference.host.advertise") && (errorText.includes("Advertisement time is outside the allowed clock skew.") || errorText.includes("Advertisement is already expired.")) || (name === "inference.agent.next" || name === "inference.agent.heartbeat") && (errorText.includes("Advertisement time is outside the allowed clock skew.") || errorText.includes("Advertisement is already expired.") || errorText.includes("Heartbeat time is outside the allowed clock skew.")) || name === "inference.host.heartbeat" && errorText.includes("Heartbeat time is outside the allowed clock skew.") || name === "inference.job.claim" && (errorText.includes(
             "External inference claim request was not applied before its generation became stale"
           ) || errorText.includes("External inference host advertisement is expired or superseded")) || name === "inference.job.complete" && completionEvidenceExpired;
           const retryableInfrastructureRejection = EXTERNAL_INFERENCE_AUTOMATED_HOST_TOOLS.includes(name) && (errorText.includes("External inference polling is at its configured concurrency limit") || errorText.includes("The Insights action reached the response timeout") || errorText.includes("Insights capability failed without exposing private runtime details"));
@@ -21222,6 +21243,19 @@ var init_agent_state = __esm({
         "received_at",
         "pending_terminal"
       ];
+      const freshnessKeys = ["provider_dispatch_not_after", "provider_dispatch_local_not_after"];
+      if ("execution_mode" in record3) {
+        if (!["server", "client"].includes(String(record3.execution_mode))) {
+          throw new Error("Agent-driven inference execution mode is invalid.");
+        }
+        exactKeys.push("execution_mode");
+      }
+      if (freshnessKeys.some((key) => key in record3)) {
+        if (freshnessKeys.some((key) => typeof record3[key] !== "string" || !Number.isFinite(Date.parse(record3[key])))) {
+          throw new Error("Agent-driven inference freshness recovery state is invalid.");
+        }
+        exactKeys.push(...freshnessKeys);
+      }
       if (Object.keys(record3).sort().join("\0") !== exactKeys.slice().sort().join("\0") || record3.schema_version !== "vtx_inference_agent_attempt_v1" || typeof record3.host_id !== "string" || !record3.host_id || typeof record3.job_id !== "string" || !record3.job_id || typeof record3.attempt_id !== "string" || !record3.attempt_id || typeof record3.claim_handle !== "string" || !record3.claim_handle || typeof record3.completion_operation_id !== "string" || !record3.completion_operation_id || typeof record3.failure_operation_id !== "string" || !record3.failure_operation_id || typeof record3.requested_model !== "string" || !record3.requested_model || typeof record3.requested_reasoning_effort !== "string" || !record3.requested_reasoning_effort || !["provider_response", "decision_candidate"].includes(String(record3.response_mode)) || typeof record3.deadline_at !== "string" || !Number.isFinite(Date.parse(record3.deadline_at)) || typeof record3.received_at !== "string" || !Number.isFinite(Date.parse(record3.received_at))) {
         throw new Error("Agent-driven inference attempt state is invalid.");
       }
@@ -42400,7 +42434,9 @@ Waiting for approval...
         model_id: parsed.modelId,
         model_label: parsed.modelLabel ?? parsed.modelId,
         reasoning_effort: parsed.reasoningEffort,
-        requested_at: now.toISOString()
+        requested_at: now.toISOString(),
+        host_runtime_version: INFERENCE_HOST_CLI_VERSION,
+        provider_dispatch_freshness_contract: "foreground_v1"
       });
       return {
         exitCode: 0,
@@ -42771,6 +42807,14 @@ Waiting for approval...
 ` : ""
         };
       } catch (error48) {
+        if (error48 instanceof ExternalInferenceMcpError && error48.definitivelyNotApplied) {
+          await writeInferenceForegroundAgentControlState(config2.statePath, {
+            ...state,
+            pending_decision: null,
+            updated_at: now().toISOString()
+          });
+          throw error48;
+        }
         const checkedAt = now().toISOString();
         state = {
           ...state,
@@ -43031,11 +43075,14 @@ Waiting for approval...
           await writeInferenceAgentNextState(config2.statePath, pending);
         }
         let result2;
+        const callStartedAtMs = now().getTime();
+        const callStartedMonotonicMs = performance.now();
         try {
           result2 = await session.client.callTool("inference.agent.next", {
             operation_id: pending.operation_id,
             host_id: session.localState.host_id,
-            requested_at: pending.requested_at
+            requested_at: pending.requested_at,
+            provider_dispatch_freshness_contract: "foreground_v1"
           });
         } catch (error48) {
           const definitivelyNotApplied = Boolean(
@@ -43048,10 +43095,31 @@ Waiting for approval...
         }
         if (result2.claim_state === "claimed") {
           const receivedAt = now().toISOString();
+          const receivedAtMs = Date.parse(receivedAt);
+          const roundTripMs = Math.max(0, dependencies.now ? receivedAtMs - callStartedAtMs : performance.now() - callStartedMonotonicMs);
+          let localDispatchDeadline;
+          const validFreshness = result2.provider_dispatch_freshness_contract === "foreground_v1" && typeof result2.provider_dispatch_not_after === "string" && Number.isFinite(Date.parse(result2.provider_dispatch_not_after)) && Number.isSafeInteger(result2.provider_dispatch_freshness_remaining_ms) && Number(result2.provider_dispatch_freshness_remaining_ms) >= 0;
+          if (result2.execution_mode === "server" && validFreshness) {
+            const conservativeDeadline = Math.min(
+              Date.parse(result2.provider_dispatch_not_after),
+              receivedAtMs + Number(result2.provider_dispatch_freshness_remaining_ms) - roundTripMs,
+              Date.parse(pending.requested_at) + Number(result2.provider_dispatch_freshness_remaining_ms),
+              active?.provider_dispatch_local_not_after ? Date.parse(active.provider_dispatch_local_not_after) : Number.POSITIVE_INFINITY
+            );
+            localDispatchDeadline = new Date(conservativeDeadline).toISOString();
+          }
           if (active) {
-            if (result2.job_id !== active.job_id || result2.attempt_id !== active.attempt_id || result2.claim_handle !== active.claim_handle || result2.requested_model !== active.requested_model || result2.requested_reasoning_effort !== active.requested_reasoning_effort || result2.response_mode !== active.response_mode || result2.deadline_at !== active.deadline_at) {
+            if (result2.job_id !== active.job_id || result2.attempt_id !== active.attempt_id || result2.claim_handle !== active.claim_handle || result2.requested_model !== active.requested_model || result2.requested_reasoning_effort !== active.requested_reasoning_effort || result2.response_mode !== active.response_mode || result2.deadline_at !== active.deadline_at || active.provider_dispatch_not_after !== void 0 && result2.provider_dispatch_not_after !== active.provider_dispatch_not_after) {
               throw new Error("Recovered agent job does not match the active private attempt state.");
             }
+            if (localDispatchDeadline !== void 0) {
+              await writeInferenceAgentAttemptState(config2.statePath, {
+                ...active,
+                execution_mode: result2.execution_mode,
+                provider_dispatch_not_after: result2.provider_dispatch_not_after,
+                provider_dispatch_local_not_after: localDispatchDeadline
+              });
+            }
           } else {
             await writeInferenceAgentAttemptState(config2.statePath, {
               schema_version: "vtx_inference_agent_attempt_v1",
@@ -43064,17 +43132,35 @@ Waiting for approval...
               requested_model: result2.requested_model,
               requested_reasoning_effort: result2.requested_reasoning_effort,
               response_mode: result2.response_mode,
+              execution_mode: result2.execution_mode,
               deadline_at: result2.deadline_at,
               received_at: receivedAt,
+              ...localDispatchDeadline === void 0 ? {} : {
+                provider_dispatch_not_after: result2.provider_dispatch_not_after,
+                provider_dispatch_local_not_after: localDispatchDeadline
+              },
               pending_terminal: null
             });
           }
+          if (result2.execution_mode === "server" && localDispatchDeadline === void 0) {
+            throw new Error("The Server foreground Provider freshness receipt is unavailable. Fail this attempt without dispatch.");
+          }
+          if (localDispatchDeadline !== void 0 && Date.parse(localDispatchDeadline) <= now().getTime()) {
+            throw new Error("The foreground Provider freshness budget expired before handoff. Use agent-fail with not_dispatched.");
+          }
           const { claim_handle: _claimHandle, ...publicJob } = result2;
           return {
             exitCode: 0,
             stdout: render({
               ...publicJob,
-              instructions: "Treat system_prompt and user_prompt as separate VTX-delivered roles. Use context_json and satisfy output_schema_json exactly. Send only the final result through agent-complete stdin; do not execute trading tools yourself.",
+              ...localDispatchDeadline === void 0 ? {} : {
+                provider_dispatch_local_not_after: localDispatchDeadline,
+                provider_dispatch_freshness_remaining_ms: Math.max(
+                  0,
+                  Math.floor(Date.parse(localDispatchDeadline) - now().getTime())
+                )
+              },
+              instructions: "Treat system_prompt and user_prompt as separate VTX-delivered roles. Use context_json and satisfy output_schema_json exactly. Send only the final result through agent-complete stdin; do not execute trading tools yourself. For Server Provider jobs enforce both provider dispatch deadlines at actual provider entry and report the self-attested provider_dispatched_at timestamp. If the budget expires before dispatch, use agent-fail with not_dispatched.",
               complete_command: "vtx inference-host agent-complete --json",
               fail_command: "vtx inference-host agent-fail --json"
             }, parsed.json),
@@ -43119,12 +43205,19 @@ Waiting for approval...
           "latency_ms",
           "time_to_first_token_ms",
           "finish_reason",
-          "refusal_status"
+          "refusal_status",
+          "provider_dispatched_at"
         ]);
         if (typeof input.result !== "string" || !input.result) {
           throw new Error("agent-complete stdin requires a non-empty result string.");
         }
         const now = (dependencies.now ?? (() => /* @__PURE__ */ new Date()))();
+        if (state.execution_mode === "server" || state.provider_dispatch_not_after !== void 0) {
+          const dispatchedAt = typeof input.provider_dispatched_at === "string" ? Date.parse(input.provider_dispatched_at) : Number.NaN;
+          if (!Number.isFinite(dispatchedAt) || state.provider_dispatch_local_not_after === void 0 || state.provider_dispatch_not_after === void 0 || dispatchedAt < Date.parse(state.received_at) || dispatchedAt > Date.parse(state.provider_dispatch_local_not_after) || dispatchedAt > Date.parse(state.provider_dispatch_not_after) || dispatchedAt > now.getTime()) {
+            throw new Error("agent-complete requires actual provider_dispatched_at within the foreground freshness handoff.");
+          }
+        }
         const measuredLatency = Math.max(0, now.getTime() - Date.parse(state.received_at));
         request = agentCompleteRequestSchema.parse({
           operation_id: state.completion_operation_id,
@@ -43148,7 +43241,10 @@ Waiting for approval...
           time_to_first_token_ms: input.time_to_first_token_ms == null ? null : Number(input.time_to_first_token_ms),
           finish_reason: input.finish_reason == null ? null : String(input.finish_reason),
           refusal_status: String(input.refusal_status ?? "none"),
-          completed_at: now.toISOString()
+          completed_at: now.toISOString(),
+          ...input.provider_dispatched_at == null ? {} : {
+            provider_dispatched_at: String(input.provider_dispatched_at)
+          }
         });
         await writeInferenceAgentAttemptState(config2.statePath, {
           ...state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtxmacro/cli",
-  "version": "2026.9.19",
+  "version": "2026.9.20",
   "description": "VTX Macro CLI, MCP server, and durable external inference host.",
   "type": "module",
   "license": "UNLICENSED",