@specset/cli 1.0.0 → 2.0.1

package/README.md

@@ -33,7 +33,7 @@ Then ask something like _"What mechanical equipment is scheduled on level 2 of m
 npm install -g @specset/cli@latest
 ```
 
-Requires Node.js 20 or newer.
+Requires Node.js 22 or newer. CLI 1.0 is the last release that runs on Node.js 20.
 
 ## Quickstart
 
@@ -60,6 +60,8 @@ specset agent chat --project <projectId> -m "What mechanical equipment is schedu
 
 Run `specset --help` or `specset <command> --help` for the full command reference.
 
+For a drawing coordination project, use `specset projects create 'Project name' --json`, then `projects add-docs --project <id> ./drawings.pdf` and `projects ingest-status --project <id> --wait`. New projects automatically support drawing graphs. This CLI requires the drawing graph GA server schema (`Project.drawingGraphEnabled`); the deprecated graph opt-in flags have been removed.
+
 Source references returned by GraphQL, agent chat, and retrieval tools are shown as clickable `https://app.specbook.ai/go/...` links. The same links can be passed back into tool, GraphQL ID, and download arguments; ordinary GraphQL `id` fields remain UUIDs.
 
 ## Use with Claude, Codex, and ChatGPT
@@ -90,18 +92,41 @@ specset skill print specset-submittals
 
 Updating an agent plugin does not upgrade an existing global CLI. Run `npm install -g @specset/cli@latest`, then re-run `specset skill install --target <agent>` to refresh direct-installed skill copies.
 
+## Local runner
+
+`specset agent serve` connects your machine to Specset. Conversations you switch to **Execute locally** run their model calls through your own Claude Code or Codex, while Specset keeps the agent loop, its tools, approvals and the transcript:
+
+```bash
+specset harness install codex           # once, for Codex; Claude uses the runtime bundled with the CLI
+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. 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
 
 The Codex/Claude plugin uses the local `specset mcp` stdio server. Hosted clients use the server's stateless Streamable HTTP endpoint at `https://<host>/mcp`; OAuth consent selects and binds the organization. Both dispatch through the same allowlisted Specset tool registry.
 
-Local agents can upload with `specset files upload <path>` and download project assets with the entity download commands. The hosted endpoint exposes OpenAI-compatible `uploadFile` and `getFileDownload` tools; uploads stream from the host's short-lived file URL into Specset storage.
+Local agents can upload with `specset files upload <path>`, download project assets with the entity download commands, and pull a whole project's spec sections, drawing sheets, and documents into a directory with `specset projects hydrate <project> --out <dir>`. The hosted endpoint exposes OpenAI-compatible `uploadFile` and `getFileDownload` tools; uploads stream from the host's short-lived file URL into Specset storage.
 
 The hosted endpoint exposes MCP OAuth 2.1 discovery, Client ID Metadata Document support, PKCE authorization, short-lived audience-bound access tokens, and rotating refresh tokens. First-party clients may also use a Specset session bearer token with an explicit organization header.
 
 ## Compatibility
 
+Organization listing, switching, and slug resolution require the me.organizationChoices API from PR #972, first released in CLI 2.0.0.
+
+The managed Codex install pins the native `@openai/codex` runtime beside the managed adapter package (see `HARNESS_CATALOG`), because the adapter's caret range can resolve to a build too old for the current model line. `specset harness list` shows both pins, and `specset harness install codex` updates a drifted native runtime in place.
+
+The CLI trusts the operating system's certificate store in addition to Node's bundled roots (Node 22.19+ / 24.5+), so deployments behind a locally trusted CA (a `*.specset.dev` dev host signed by Caddy's local root, a corporate TLS proxy) work without `NODE_USE_SYSTEM_CA`. A transport failure names its cause (DNS, refused connection, untrusted certificate) instead of a bare `fetch failed`.
+
 CLI 1.x requires a Specset deployment that serves public source links (the `/go` routes, `SearchResultItem.id`, and server-side link translation). Deploy the server before publishing or upgrading to a 1.x CLI; against older deployments, stay on the 0.x line.
 
+CLI 2.0 requires Node.js 22 or newer and a Specset deployment from 2026-10-10 or later, which app.specset.com is. Existing commands depend on the newer server too: `org list`, `org use` and every command's `--org` resolution query `me.organizationChoices` (PR #972), and the new commands (personal runners, project seeding, submittal reviews, the superadmin namespace) call APIs deployed by that date. On Node.js 20, or against an older deployment, stay on CLI 1.0.0 until both are upgraded.
+
+`agent start --type ProjectReview` requires the server's Project Review agent registration. Project Review has no separate project toggle or superadmin launch requirement. These command and skill additions ride the next CLI release; no npm version is bumped here.
+
+Local execution requires this branch's personal-runner and local-inference API, including the `AddRunnerOutputIdentity` migration (run outputs attach with their workspace path and checksum). Deploy these server changes before releasing this CLI. With native tools on, the thread's Permissions setting maps to Claude's permission modes and to Codex's sandbox (Read only, workspace-write for Edits and Auto, full access for Full).
+
 ## Configuration
 
 - Credentials and the active host/org live in `~/.config/specset/config.yml` (mode 0600).
@@ -114,3 +139,31 @@ Questions or issues: [https://specset.com](https://specset.com)
 
 `@specset/cli` is distributed under the Elastic License 2.0 — see `LICENSE`.
 Third-party license attributions are listed in `THIRD_PARTY_NOTICES.md`.
+
+### Personal machine runners
+
+`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.
+
+`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.
+
+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.
+
+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.
+
+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.
+
+File attachments and file tool results share a transport that preserves their bytes, MIME type and optional filename. Claude receives PDFs natively; Codex receives server-rendered PDF pages, capped at 20 pages per request across all PDFs. Both receive images and UTF-8 text files. Other binary formats fail explicitly until a compatible reader or conversion is available.
+
+Requires the personal-runner and local-inference GraphQL operations, first released in CLI 2.0.0.
+
+Inspect registrations with `specset agent runners list --host <deployment> --org <slug> --json`. Revoke an online or offline runner remotely with `specset agent runners revoke <runner-id>`; this stops its outstanding jobs.
+
+The server keeps orchestration, retrieval, tool authorization and persistence. Authorized model calls route through the selected runner, including workflow utilities that previously called cloud providers directly.

package/THIRD_PARTY_NOTICES.md

@@ -4,15 +4,19 @@ The `@specset/cli` distribution bundles the following open-source packages
 into its executable (`dist/main.js`). Their license terms and copyright
 notices are reproduced below. (`open` is installed from npm as a regular
 dependency and is not redistributed in the bundle; its MIT license ships with
-that package.)
+that package. The Claude Code and Codex ACP adapters that `specset harness
+install` fetches are installed from npm into `~/.specset/harness` at the
+user's request and are not part of this distribution.)
 
 | Package | Version | License |
 |---|---|---|
 | `@0no-co/graphql.web` | 1.x | MIT |
+| `@agentclientprotocol/sdk` | 1.x | Apache-2.0 |
 | `@stricli/core` | 1.x | Apache-2.0 |
 | `gql.tada` | 1.x | MIT |
 | `graphql` | 16.x | MIT |
 | `graphql-request` | 7.x | MIT |
+| `graphql-ws` | 6.x | MIT |
 | `yaml` | 2.x | ISC |
 
 ---
@@ -25,6 +29,7 @@ Applies to:
 - `gql.tada` — Copyright (c) 0no.co
 - `graphql` — Copyright (c) GraphQL Contributors
 - `graphql-request` — Copyright (c) 2022 Jason Kuhrt
+- `graphql-ws` — Copyright (c) 2020-2025 Denis Badurina
 
 ```
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -74,6 +79,7 @@ PERFORMANCE OF THIS SOFTWARE.
 
 Applies to:
 
+- `@agentclientprotocol/sdk` — Copyright (c) Agent Client Protocol contributors
 - `@stricli/core` — Copyright (c) Bloomberg Finance L.P.
 
 The full Apache License, Version 2.0 is available at