@specset/cli 2.0.0 → 2.0.1

package/README.md

@@ -101,7 +101,7 @@ specset harness install codex           # once, for Codex; Claude uses the runti
 specset agent serve --host <deployment> --org <slug>
 ```
 
-Turn on **Native tools** in the conversation's Settings to let the harness run shell commands and edit files in a private per-run workspace; every command and edit is mirrored into the conversation, the `specset` CLI is logged in there for downloading project material, and files written under `out/` are attached to the thread. Requires Node.js 22 or newer.
+Turn on **Native tools** in the conversation's Settings to let the harness run shell commands and edit files in a private per-run workspace; every command and edit is mirrored into the conversation, the `specset` CLI is logged in there for downloading project material, and files written under `out/` are attached to the thread. With Permissions Auto or Full, document and drawing reads may also run code over their own attachments (crop and enlarge a detail), sandboxed in a scratch directory holding only those files (plus your temp directory), with no network or credentials; the terminal prints each action. Requires Node.js 22 or newer.
 
 ## MCP transports and files
 
@@ -144,13 +144,19 @@ Third-party license attributions are listed in `THIRD_PARTY_NOTICES.md`.
 
 `specset agent serve --host <deployment>` registers a personal runner while the command is running. Organization selection uses `--org <slug|id>`, the selected organization on that host, or the sole membership. With multiple memberships and no selection, choose an org explicitly. Omitting `--project` makes the runner available throughout that org; `--project <id|link>[,<id|link>…]` restricts it to selected projects. In a local thread, select that machine to authorize the root run and its descendants. Multiple comma-separated project IDs can be allowed; registration is restricted to the signed-in user and organization. `--thread <id>` assigns an existing root immediately; `--message "…" --type DrawingReview` creates an assigned root in a single selected project.
 
-The native runtime is selected once before registration: `--harness` overrides the host’s saved default, otherwise the sole available native runtime is selected. Claude uses the platform binary bundled with the CLI’s Claude SDK, then native `claude` on PATH. Codex uses `CODEX_PATH`, then native `codex` on PATH, then the native runtime provided by `specset harness install codex`. When both native runtimes are available, choose one explicitly. Save a default with `specset harness use codex --host <deployment>` (or `claude`); `specset harness use auto --host <deployment>` clears it. `specset harness list --host <deployment>` reports the managed installations.
+`agent serve` serves from the harness accounts in the `runner:` block of `~/.config/specset/config.yml`; `specset harness list` shows them with the routing below. With none listed it uses the logins this shell would use: the host's harness default saved by older CLIs, else every native runtime that can run (Claude Code at `CLAUDE_CONFIG_DIR` or `~/.claude`, Codex at `CODEX_HOME` or `~/.codex`, Antigravity's `agy`). Add another login with `specset harness add claude2 --harness claude --home ~/.claude2 --preferred` (it signs in once to check the login) and drop one with `specset harness remove <name>`; `--account claude2,codex` limits one run to those accounts. Claude uses the platform binary bundled with the CLI's Claude SDK, then native `claude` on PATH. Codex uses `CODEX_PATH`, then native `codex` on PATH, then the native runtime provided by `specset harness install codex`. Antigravity is opt-in: `agent serve` uses it only after you add an account for it (`specset harness add agy --harness antigravity`), never by detection. It uses `agy` on PATH, then `~/.local/bin/agy`; install it from antigravity.google and run `agy` once to sign in. Its login lives in the macOS keychain, so a machine has one Antigravity account.
 
-Each process serves one host and organization. For separate worktrees, run `specset agent serve --host app2.specset.dev` and `specset agent serve --host app3.specset.dev` in separate terminals. Host precedence is `--host`, a recognized pasted thread/project link, `SPECSET_HOST`, then the active host. Login, selected org, and saved harness default are stored per host. The resolved host, org, harness and scope are printed at startup and stay fixed until exit. Changing the CLI’s active host/org does not retarget a running process. Registrations, run workspaces and cancellation belong to that deployment; concurrency limits apply separately to each runner, while machine resources and provider quotas may be shared.
+Every model call carries its routing tier: conversation, orchestrator, planner, analyst, worker, lite, balanced, query or vision. Each tier names a model, and any account whose harness offers that model serves it. The defaults match the app's cloud routing: sonnet for the conversation, orchestrator and planner (Claude Code); gemini-3.8-flash-medium for analyst and vision (Antigravity); gpt-6-luna for worker and query, gpt-6-luna at low effort for lite, and gpt-6-sol at low effort for balanced (Codex). A tier whose model no account offers runs the same class of model (frontier, standard, fast) on a harness the machine has: opus, sonnet and haiku on Claude Code; gpt-6-astra, gpt-6-sol and gpt-6-luna on Codex; gemini-3.8-flash-high, -medium and -low on Antigravity. Change a tier with `specset harness tier worker haiku` (or `model:effort`, or `default`), a class's model with `specset harness model codex standard gpt-6-sol --effort low`, or one run's tiers with `agent serve --tier conversation=opus,worker=haiku`. A conversation's Settings choice (a class or an exact model) applies to that thread's own steps only; its children and helper calls follow the tiers.
 
-Temporal owns agent execution, workflow fan-out, tool dispatch and approvals. The personal runner executes individual model calls, including drawing-coordination assessments, using the native Claude SDK or Codex app-server. Images and structured output cross the same model boundary. Independent calls use separate native sessions; a session stays alive across a tool batch until the server supplies all authorized results. For a bounded review, `--stopAfterIssues 2` stops the root and its children after two newly filed issues; an in-flight batch can exceed the threshold. `--concurrency` defaults to 5 active model calls. Tool and approval waits release compute capacity, so `--concurrency 1` can process children and nested assessment calls. `--maxThreads` (default 100) and `--maxRunSeconds` (default 3600) bound each authorization. Stop cancels the subtree, queued jobs and workflow tools; it never falls back to cloud execution. A lost native continuation fails instead of replaying possible writes. Restarting the command registers a new machine session and requires a new root assignment.
+The runner chooses each call's account before claiming it. Among the accounts that offer the call's model, the preferred ones (added with `--preferred`, else all of them) take it while one has room, the least busy first; a native session stays on its account. When those are at their limits, `specset harness failover` decides: `sameModel` (the default) lets the other accounts that offer the model take it, `any` also the same class of model on another harness, and `off` nothing. A call that reaches a limit before producing any output moves the same way. A call whose output already reached the thread fails instead, since running it again could replay native actions, and the next call goes to an account with room. When every allowed account is at its limit, the run stops with the earliest reset time.
 
-At startup the runner lists the harness's models (Codex's app-server catalog, Claude's supported models) and reports them with its registration; the conversation's Settings shows that list under the harness model and pins a choice per harness for the thread, with an effort level from the chosen model's reported levels for its agent steps. `--model` on the machine pins one model for every job instead, and Settings then shows it as fixed. Specset's `--autoApprove` message setting controls server tool approval. Specset tools execute on the server, with approvals in the web app; the native harness receives their results through the runner. Native tools are off unless the conversation's **Native tools** setting is on; then the harness may run shell commands and read or edit files in the run's workspace within the thread's Permissions setting, every action is mirrored into the conversation as a local action, and native sub-agents stay off. Each run (root thread and its children) gets one workspace under `--directory` (`~/.specset/personal-runs/<runner>/runs/<thread>/` by default) with `specs/`, `drawings/`, `docs/`, `inputs/` and `out/`; the harness downloads what it needs with the `specset` CLI, which is logged in as you for that host and organization inside the session's private home, and `.specset/manifest.json` records each file's Specset link, version id and checksum so a repeated download is skipped unless the version changed. Files under `out/` are uploaded and attached to the root thread after each turn that used native tools and when the run ends; the workspace is removed once its run has ended (checked when the runner starts and stops and every ten minutes), or after seven untouched days. Jobs receive a minimal environment and private harness configuration. Claude shares the selected native credential store and refresh lock while settings stay private. Codex uses an authentication-only native process for the selected login; inference sessions receive temporary access tokens and never copy refresh credentials. User settings, hooks, plugins, and other MCP servers are not loaded into inference sessions. Log in with `claude auth login` before starting a Claude runner. This is a personal runner executing selected project content as the local OS user, **not an OS sandbox**: native harness permissions and the host remain security boundaries. Use a separate OS account or isolated host when that content is untrusted. Do not treat this as an organization-wide shared runner.
+A tier can fall back to the cloud instead of another provider: `specset harness fallback analyst cloud` (or `all`, or `agent serve --fallback analyst=cloud` for one run; `local`, the default, keeps today's behaviour). Such a tier never runs another harness's model. Its calls run on Specset's cloud model for the tier, billed to the organization like any cloud call, whenever no account here can serve its model: a tier whose model no account offers goes straight to the cloud (the registration tells the server, so no call waits on the machine), and a call whose accounts are at their limits is handed to the cloud before it produces anything. `harness list` and the `agent serve` banner show which tiers fall back to the cloud.
+
+Each process serves one host and organization. For separate worktrees, run `specset agent serve --host app2.specset.dev` and `specset agent serve --host app3.specset.dev` in separate terminals. Host precedence is `--host`, a recognized pasted thread/project link, `SPECSET_HOST`, then the active host. Login and selected org are stored per host; accounts and routing are the machine's. The resolved host, org, accounts, tiers and scope are printed at startup and stay fixed until exit. Changing the CLI’s active host/org does not retarget a running process. Registrations, run workspaces and cancellation belong to that deployment; concurrency limits apply separately to each runner, while machine resources and provider quotas may be shared.
+
+Temporal owns agent execution, workflow fan-out, tool dispatch and approvals. The personal runner executes individual model calls, including drawing-coordination assessments, using the native Claude SDK or Codex app-server. Images and structured output cross the same model boundary. Independent calls use separate native sessions; a session stays alive across a tool batch until the server supplies all authorized results. For a bounded review, `--stopAfterIssues 2` stops the root and its children after two newly filed issues; an in-flight batch can exceed the threshold. `--concurrency` defaults to 5 active model calls. Tool and approval waits release compute capacity, so `--concurrency 1` can process children and nested assessment calls. `--maxThreads` (default 100) and `--maxRunSeconds` (default 3600) bound each authorization. `specset harness limits` saves all three in config.yml, so a plain `agent serve` uses them. Stop cancels the subtree, queued jobs and workflow tools; it never falls back to cloud execution. A lost native continuation fails instead of replaying possible writes. Restarting the command registers a new machine session and requires a new root assignment.
+
+At startup the runner lists each account's models (Codex's app-server catalog, Claude's supported models, `agy models`), which tell it which accounts offer each tier's model, and reports them with its registration, with its accounts and tiers; the conversation's Settings shows them under the harness model and pins a class or one model per harness for the thread, with an effort level from the chosen model's reported levels. Specset's `--autoApprove` message setting controls server tool approval. Specset tools execute on the server, with approvals in the web app; the native harness receives their results through the runner. Native tools are off unless the conversation's **Native tools** setting is on; then the harness may run shell commands and read or edit files in the run's workspace within the thread's Permissions setting, every action is mirrored into the conversation as a local action, and native sub-agents stay off. Each run (root thread and its children) gets one workspace under `--directory` (`~/.specset/personal-runs/<runner>/runs/<thread>/` by default) with `specs/`, `drawings/`, `docs/`, `inputs/` and `out/`; the harness downloads what it needs with the `specset` CLI, which is logged in as you for that host and organization inside the session's private home, and `.specset/manifest.json` records each file's Specset link, version id and checksum so a repeated download is skipped unless the version changed. Files under `out/` are uploaded and attached to the root thread after each turn that used native tools and when the run ends; the workspace is removed once its run has ended (checked when the runner starts and stops and every ten minutes), or after seven untouched days. Jobs receive a minimal environment and private harness configuration. Claude shares the selected native credential store and refresh lock while settings stay private. Codex uses an authentication-only native process for the selected login; inference sessions receive temporary access tokens and never copy refresh credentials. User settings, hooks, plugins, and other MCP servers are not loaded into inference sessions. Log in with `claude auth login` before starting a Claude runner. Antigravity runs `agy` in print mode with a private home: the Specset tools reach it as an MCP server on a loopback port with a per-session token, the instructions as a system message, attachments as files it reads with `view_file`, and a pre-tool hook refuses everything else (shell, edits, browser, web search), so it never takes a call with Native tools on. agy gives up on a tool call after three minutes; a Specset tool still running then answers that it is, and the model waits for it with `specset_wait_for_result`. This is a personal runner executing selected project content as the local OS user, **not an OS sandbox**: native harness permissions and the host remain security boundaries. Use a separate OS account or isolated host when that content is untrusted. Do not treat this as an organization-wide shared runner.
 
 Personal inference sessions set Claude's `persistSession: false` and Codex's `ephemeral: true`, keeping them out of the respective desktop histories. Specset remains the transcript and approval record.