@vtxmacro/cli 2026.8.52 → 2026.8.53

package/README.md

@@ -64,12 +64,13 @@ and VTX grant. VTX resolves the package-owned pinned Copilot platform runtime
 explicitly and rejects an `auto`-only catalog because it cannot prove the
 effective model.
 
-An explicitly capable Codex model can also control Main in **Agent** mode using
-the same VTX OAuth grant and private Codex login. VTX assigns the running bot but
-does not send a VTX-authored prompt or set the analysis cadence. Codex keeps a
-durable Agent thread, chooses when to wake, requests only the assignment-scoped
-VTX data it needs (or none), and submits the normal structured decision for VTX
-to validate and execute. Review and Screener remain Provider-only.
+An explicitly capable durable Codex or Copilot model can also control Main in
+**Agent** mode using the same VTX OAuth grant and its own private subscription
+login. VTX assigns the running bot but does not send a VTX-authored prompt or set
+the analysis cadence. The assigned runtime keeps a durable Agent thread,
+chooses when to wake, requests only the assignment-scoped VTX data it needs (or
+none), and submits the normal structured decision for VTX to validate and
+execute. Review and Screener remain Provider-only.
 
 Before the first Codex login, enable **Device code authorization for Codex** in
 ChatGPT Security settings. Only enter a device code from a login you initiated,
@@ -192,7 +193,8 @@ vtx inference-host agent-run
 vtx inference-host agent-next --wait-seconds 50 --json
 ```
 
-`agent-next` returns separate exact `system_prompt`, `user_prompt`,
+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,
@@ -211,18 +213,39 @@ Use `not_dispatched` only when no harness inference began,
 `outcome_unknown` when dispatch itself cannot be confirmed. Pipe exactly one
 object to `vtx inference-host agent-fail --json`.
 
+For **Agent** mode on an explicitly capable Main model, VTX supplies only the
+assignment, allowed data contract, and normal decision schema. The foreground
+agent chooses its own cadence and may request zero, one, or many data calls:
+
+```bash
+vtx inference-host agent-assignment-next --wait-seconds 50 --json
+vtx inference-host agent-data-call --json
+vtx inference-host agent-decision-submit --json
+vtx inference-host agent-decision-status --json
+vtx inference-host agent-assignment-heartbeat --json
+vtx inference-host agent-assignment-release --json
+```
+
+`agent-assignment-next` returns the exact `output_schema`, data capabilities,
+wake bounds, and `decision_input` shape. Submit a `candidate` matching that
+schema plus `provenance` with `source: "external_agent"`, a stable
+`agent_run_id`, and the requested and actual model and reasoning effort. Use
+`agent-decision-status` after an uncertain submit response. Use
+`agent-assignment-release` only when intentionally ending the foreground Agent
+session; normal cadence is recorded with `agent-assignment-heartbeat`.
+
 Claude Code, Antigravity, Gemini CLI, Kiro, Grok Build, Cursor, Amp, Auggie,
-Junie, Warp/Oz, Qwen Code, and OpenCode remain on
-the explicit foreground agent loop. Their current subscription routing,
+Junie, Warp/Oz, Qwen Code, and OpenCode remain on the explicit foreground host
+path. Their current subscription routing,
 effective-model identity, schema, usage, or crash-recovery contracts do not yet
 meet every durable VTX acceptance fence. The public Insights matrix records the
 specific limitation instead of treating headless support alone as durability.
 
-Keep `agent-run` open in a separate terminal and keep calling `agent-next`
-while the host should remain available. The independent keeper preserves
-truthful liveness while the harness reasons. This same loop
-supports Main, Review, and Screener in Provider mode;
-and normally running VTX Client Mode or Server Mode bots. Server Mode keeps the
+Keep `agent-run` open in a separate terminal while the foreground host should
+remain available. Use the Provider job loop for Main, Review, or Screener, or the
+Agent assignment loop for an explicitly capable Main model. The independent
+keeper preserves truthful liveness while the harness reasons. Both loops support
+normally running VTX Client Mode or Server Mode bots. Server Mode keeps the
 normal VTX call fee. Client Mode has no VTX platform fee. Neither mode falls back
 to another model when the agent host is unavailable.
 
@@ -234,10 +257,11 @@ running bot.
 
 ## Remove
 
-First uninstall any durable service, stop any foreground run or agent-run process,
-revoke the VTX inference grant, then uninstall the package. Cleanup refuses while
-a foreground host process still owns the host. Automated Codex users should also remove the
-dedicated Codex login:
+First release any foreground Agent assignment, uninstall any durable service,
+stop any foreground run or agent-run process, revoke the VTX inference grant,
+then uninstall the package. Cleanup refuses while a foreground host process
+still owns the host. Automated Codex users should also remove the dedicated
+Codex login:
 
 ```bash
 vtx inference-host service stop