@vtxmacro/cli 2026.8.52 → 2026.8.54

package/README.md

@@ -10,7 +10,8 @@ vtx --version
 ```
 
 The host supports Windows x64 and Linux x64, including WSL. The package installs
-the exact supported OpenAI Codex runtime and GitHub Copilot SDK. The VTX host
+the exact supported OpenAI Codex runtime, GitHub Copilot SDK, and official
+DeepSeek Harness package wave. The VTX host
 verifies the Codex runtime's version and digest before use; it does not borrow a
 Codex binary from PATH or an editor extension.
 For Windows-login auto-start, install and configure the CLI from native Windows;
@@ -52,7 +53,7 @@ Both paths use a separate least-privilege `insights:inference` OAuth grant.
 VTX never receives an agent vendor password, OAuth token, or subscription
 credential.
 
-### Durable subscription hosts
+### Durable inference hosts
 
 Codex remains the reference implementation and its existing App Server,
 authentication, quota, recovery, and provider-mode path are unchanged. GitHub
@@ -64,12 +65,14 @@ 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, Copilot, or DeepSeek Harness model can also
+control Main in **Agent** mode using the same VTX OAuth grant and its own local
+adapter-specific vendor credential: ChatGPT or Copilot login, or a DeepSeek API
+key. 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,
@@ -105,6 +108,27 @@ vtx inference-host doctor --adapter copilot --instance copilot-1 --json
 vtx inference-host service install --adapter copilot --instance copilot-1
 ```
 
+For DeepSeek Harness, import the API key through stdin so it never appears in
+process arguments, then install a distinct durable instance:
+
+```bash
+vtx inference-host login --instance deepseek-1
+vtx inference-host deepseek-login --instance deepseek-1 < /private/path/deepseek.key
+vtx inference-host doctor --adapter deepseek-harness --instance deepseek-1 --json
+vtx inference-host service install --adapter deepseek-harness --instance deepseek-1
+```
+
+The DeepSeek key remains in the local OS credential store or the explicitly
+selected private-file fallback; it is never written to the service manifest or
+sent to VTX. Provider mode is tool-less. Main Agent mode uses a durable Harness
+session with only the three assignment-scoped VTX tools. Review and Screener
+remain Provider-only. An Agent dispatch whose provider outcome cannot be proved
+is durably fenced and is not repeated after a service restart. Inspect
+`status --json`, `doctor --json`, and service logs; revoke and relink the exact
+instance after reconciling an ambiguous fence. An authentication fence clears
+only after a successful replacement key import. Quota and rate-limit failures
+honor their provider retry time or a bounded local cooldown.
+
 To connect another Codex subscription to the same VTX account, repeat the
 login and service-install commands with a stable local name such as
 `--instance codex-2`. Each named instance has an isolated VTX grant, Codex
@@ -131,26 +155,31 @@ The command never kills an arbitrary process, logs either account out, changes
 VTX profile settings, or controls a Trader. If any package-owned VTX automation
 is still live, recovery fails closed and preserves its evidence.
 
-For each VTX profile and lane, **Host #1** is tried first and later compatible
-hosts follow in the saved Host cascade order. Distinct computers may use the
-same authenticated subscription; provider quota remains account-level.
-Quota/credits exhaustion can advance only to a later host reporting a different
-account identity. Unusable authentication and exhausted recoverable host failures
+For each VTX profile and lane, **Host #1** is selected. Provider-mode calls may
+continue through later compatible hosts in the saved Host cascade order. Agent
+mode keeps its durable thread and assignment on Host #1 and fences a failure
+instead of automatically transferring it. Distinct computers may use the same
+authenticated subscription; when account identity is reported, provider quota
+remains account-level and quota exhaustion skips only positively matching
+identities. Unusable authentication and exhausted recoverable Provider failures
 can advance the same logical call. VTX never changes
 provider, model, effort, or response mode, and never cascades a bad request,
 policy rejection, or uncertain dispatch outcome.
 
-Automated hosts do not impose a subscription-specific profile-count or
+Automated hosts do not impose a provider-specific profile-count or
 concurrency limit by default. Set an explicit positive integer with
-`--max-concurrency` when you want a local limit. Every active turn shares the live subscription
-rate-limit gate and cooldown; unlimited local admission does not guarantee
-capacity beyond the authenticated account's current entitlement. Updating from
+`--max-concurrency` when you want a local limit. Every active turn still
+consumes capacity from its adapter-specific provider account or API key;
+unlimited local admission does not guarantee provider capacity. Codex uses its
+reported live subscription gate and cooldown. DeepSeek Harness is API-billed and
+does not claim a stable account identity or provider rate-limit window. Updating from
 an older bounded host removes its previous numeric limit; run
 `service install --max-concurrency <positive-integer>` only to add one back.
 
 Every durable host uses a separate least-privilege `insights:inference`
 OAuth grant. Codex additionally keeps its ChatGPT subscription login in a dedicated
-private Codex home; Copilot uses its official cached user login.
+private Codex home; Copilot uses its official cached user login; DeepSeek Harness
+keeps its API key in the local VTX credential boundary.
 No vendor credential is written to the VTX service manifest. The per-user OS service starts immediately, starts again at login, and
 reconnects after sleep, network loss, or a worker exit. Stopping a VTX bot leaves
 the provider online and idle. Use `vtx inference-host run` only for foreground
@@ -176,7 +205,7 @@ confirmation page was blocked; the grant succeeded.
 
 ### Any compatible agent harness
 
-Codex, Claude Code, Cursor, GitHub Copilot, Antigravity, and other agents that can
+Codex, DeepSeek Harness, Claude Code, Cursor, GitHub Copilot, Antigravity, and other agents that can
 run shell commands can use their existing first-party session without a
 VTX-owned vendor adapter:
 
@@ -192,7 +221,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 +241,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 +285,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