@specset/cli 1.0.0 → 2.0.0

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. 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,25 @@ 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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