@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/vendor/zcode/source/tool/validation-contracts.js

@@ -0,0 +1,8 @@
+export const CoreErrorType = { ToolExecutionFailed: 'tool_execution_failed' };
+export function createCoreError(type, message, options) {
+    return Object.assign(new Error(message), { type, ...options });
+}
+export function isCoreError(error) {
+    return error instanceof Error && 'type' in error && typeof error.type === 'string'
+        && 'recoverable' in error && typeof error.recoverable === 'boolean';
+}

package/docs/README.md

@@ -0,0 +1,36 @@
+# Andorra Code
+
+Andorra Code is a terminal-first coding agent. Run `andorra` in a project folder and it researches the repository, asks what you need, and implements the work with your own model providers. Instead of one opaque agent loop, work runs on a **graph**: visible stages, decisions, and handoffs that you can inspect, edit, and rerun.
+
+```sh
+# after installing (see Getting started)
+cd /path/to/your/project
+andorra
+```
+
+## Where to start
+
+| Page | What it covers |
+| --- | --- |
+| [Getting started](getting-started/README.md) | Install Andorra Code, configure a provider, run your first task |
+| [Give these instructions to an AI agent](agents/install-for-agents.md) | A copy-paste block that lets another coding agent install and set up Andorra Code for you |
+| [Accounts, membership, and hosted Jev](getting-started/accounts.md) | Signing in, free and paid access, the `/jev` routing service |
+| [Concepts](concepts/README.md) | Graphs, agent nodes, providers, memory, limits, and security boundaries |
+| [Guides](guides/README.md) | The TUI, the visual Graph Builder, headless runs, extensions, the browser and desktop clients |
+| [Reference](reference/README.md) | CLI commands and flags, slash commands, configuration files |
+| [For AI agents](agents/README.md) | How an agent should read this documentation |
+
+## The short version
+
+- **CLI-first.** `andorra` opens the TUI. `andorra graph` opens the local browser Graph Builder. There is no required cloud service for the coding loop: it runs on your machine with your providers.
+- **Bring your own models.** OpenAI-compatible endpoints, Anthropic, Codex (ChatGPT subscription sign-in), and local servers such as LM Studio. See [Configure providers](getting-started/configure-providers.md).
+- **The graph is the harness.** Out of the box, `andorra` runs a single Software Engineer agent on the bundled default graph. Free accounts can build one small custom graph; paid members can select the Orchestrator workflow (`/graph` or `--graph :andorra`) and build any number of custom graphs with per-agent models, tools, instructions, typed handoffs, loops, and joins. See [Concepts](concepts/README.md).
+- **Agent-readable.** Every page here is written in Markdown, and [`llms.txt`](/llms.txt) indexes them for AI agents. See [For AI agents](agents/README.md).
+
+## Documentation map
+
+- **Getting started** — install, first run, providers, accounts.
+- **Concepts** — what the runtime actually does: the graph model, context handling, limits, security.
+- **Guides** — task-oriented how-tos for every client and mode.
+- **Reference** — exact CLI and configuration surface.
+- **For AI agents** — machine-facing entry points, including graph authoring over the local MCP server (the supported surface for agents; the Graph Builder is the editor for people).

package/docs/agents/README.md

@@ -0,0 +1,62 @@
+# For AI agents
+
+This page is written for AI agents (and the people who configure them). Andorra Code is an agent-centric tool, so its documentation is designed to be read by machines as well as humans.
+
+## Reading these docs
+
+Every page you are reading is published on the documentation site. The rendered page is at `/docs/<page>`; the same page as plain markdown, exactly as it is written here, is at `/docs-md/<path>`:
+
+```text
+/docs-md/getting-started/README.md
+```
+
+`llms.txt` at the site root is a curated index of every page with a one-line description, following the emerging `llms.txt` convention. Start there, then fetch only the pages you need:
+
+```text
+/llms.txt
+```
+
+## Authoring a graph: use the MCP server
+
+When an agent creates or edits a graph, the MCP server is the surface to use — not the Graph Builder. The Graph Builder is a browser application for people; the MCP server is the documented authoring API for agents, and it needs no browser, no mouse, and no UI state to coordinate.
+
+```text
+andorra mcp-server --stdio
+```
+
+- **It does not run the graph you authored and opens no network listener.** Authoring and running are separate steps: publish a revision over MCP, then run it with `andorra --graph <id>`.
+- **Graph access requires a signed-in paid account.** If the account signs out or switches during a call, the server fails closed with `AUTH_CHANGED` instead of disclosing another account's graphs.
+- **Every Agent node you create must name a provider ID from `andorra_providers_list`.** Never assume the session provider is inherited; `NODE_PROVIDER_MISSING` and `NODE_PROVIDER_INVALID` mean the node, not the call, is wrong.
+- **Read the architecture resource before designing.** `andorra_graph_guide` returns the node types, ports, edge rules, and error contract — including that `agent`, `condition`, `loop`, `approval`, `join`, `parallel`, `action`, and `end` are the node types, and that every declared outcome needs an outgoing edge unless the node sets `completion.requireRoutes: false`. Do not guess at node fields from an example alone, and do not add edges or End nodes just to satisfy a route an agent deliberately left terminal.
+- **Follow the documented sequence and never skip validation.** `andorra_graph_begin` → `andorra_graph_node_upsert` / `andorra_graph_edge_upsert` / `andorra_graph_patch` → `andorra_graph_validate` → `andorra_graph_publish`. Fix every reported issue; do not suppress them by widening schemas or dropping outcomes.
+- **Cycles need a ceiling.** A failure route back to an earlier node is a cycle, so set `limits.maxNodeVisits` (or a wall clock) and make the ceiling large enough for the intended reentries.
+- **Drafts are process-local and expire after an hour of disuse.** Exiting the MCP process discards unpublished work, so finish the sequence in one session.
+- **Publishing is local-first.** A successful `andorra_graph_publish` is durable locally but is **not** cloud confirmation; report the sync state rather than claiming the graph was backed up.
+- **Do not drive the Graph Builder UI to author a graph.** Open it only for human editing or to show a person the result visually. If you do use it, expect an online paid-membership check before it starts.
+
+## What an agent should know
+
+- **Install and setup** — [Give these instructions to an AI agent](install-for-agents.md) is a deterministic, copy-pasteable procedure for installing Andorra Code and configuring a provider. Follow it verbatim; it lists every decision point.
+- **CLI surface** — [Reference: CLI](../reference/cli.md) lists every subcommand and flag; [Reference: slash commands](../reference/slash-commands.md) covers the in-TUI commands.
+- **Headless automation** — `andorra --prompt "..." --json --no-tui` runs one task and prints a machine-readable result object with status, run ID, usage, and tool count. Exit codes: `0` success, `1` failure/exhaustion, `130` cancellation. See [Headless mode](../guides/headless.md).
+- **Workspace instructions** — Andorra reads project-root `ANDORRA.md`, falling back to `AGENTS.md`, then lowercase `agents.md`, only when the preferred file is absent. If you are preparing a repository for Andorra, put workspace instructions in `ANDORRA.md`. See [Workspace instructions](../concepts/workspace-instructions.md).
+- **Driving Andorra over MCP** — The same local stdio MCP server (`andorra mcp-server --stdio`) is how an agent authors and inspects graphs and reports on sessions, whether the agent runs outside Andorra or inside one of its own nodes. See [Agent MCP server](mcp-server.md).
+
+### Choosing a surface
+
+| The task | Use |
+| --- | --- |
+| Create or edit a graph | MCP server (`andorra_graph_*` tools) |
+| Run one task and read a machine-readable result | `andorra --prompt "..." --json` |
+| Watch sessions, find a run that needs input | MCP session tools |
+| Edit a graph by hand, or show one to a person | Graph Builder (`andorra graph`) |
+| Answer an Orchestrator's intake questions | an interactive session; headless returns `needs_clarification` |
+
+## Grounding rules for agents
+
+1. Prefer this documentation over assumptions about CLI behavior; flags and commands change between revisions and the docs track the current `main`.
+2. Do not run interactive TUI commands when automating; use the headless flags or the MCP server.
+3. Author graphs over the MCP server, and read `andorra_graph_guide` before designing one. The Graph Builder is for people, not for agents.
+4. Treat exit code `1` with status `needs_clarification` as a request for human input, not a retryable failure — answer it in an interactive session.
+5. Never put credentials in handoff data, graph JSON, or workspace instruction files; provider keys live in `~/.andorracode/config.json` or environment variables only.
+6. Report what you actually ran and saw. A build that compiles is not evidence that the change works, and a published revision is not evidence that the cloud copy exists.

package/docs/agents/install-for-agents.md

@@ -0,0 +1,55 @@
+# Give these instructions to an AI agent
+
+If you use another AI coding agent (Codex, Claude Code, and so on), paste the block below into it. The agent can then install Andorra Code on your machine, configure a provider, and verify the install without further decisions from you.
+
+Before pasting, fill in the bracketed value: which provider to configure. Everything else is deterministic.
+
+````markdown
+Install Andorra Code (a terminal-first coding agent) on this machine and verify it works.
+
+Prerequisites you must check first:
+- Node.js 22.19 or newer (`node --version`). If missing or older, install the current LTS
+  from nodejs.org (or via the system's package manager) before continuing. npm ships with it.
+- Network access to registry.npmjs.org and to the model provider endpoint below.
+- If the provider preset below is "Codex": the official OpenAI Codex CLI must already be
+  installed and signed in with ChatGPT (install @openai/codex and run `codex login`), or
+  ANDORRA_CODEX_PATH must point at its executable. Without it, configuring the Codex
+  provider fails — check this before step 3 when that preset is chosen.
+
+Steps (run verbatim, stopping to report if any step fails):
+1. npm install -g @andorra-labs/code
+2. Verify: `andorra --version` must print a version number. If `andorra` is not found, the
+   npm global bin directory is not on PATH — report that; do not edit shell profiles silently.
+
+Provider configuration (interactive, needs the human once):
+3. Tell the user to run `andorra` in any folder, type `/providers`, press Enter, choose
+   "Add provider", select the "<provider preset: DeepSeek | Kimi | Kimi For Coding | GLM Coding Plan | OpenAI | Anthropic | local | Codex>"
+   preset, and provide credentials one of these two ways:
+   - Paste their API key into the masked **API key** field (saved locally), or
+   - Enter a variable name (e.g. OPENAI_API_KEY) in the **Environment fallback** field AND
+     export that variable in the shell before starting. Exporting alone does nothing: the
+     fallback field is what tells Andorra to read the environment.
+   Settings save only after choosing "Save changes".
+
+Verification (optional, non-interactive):
+4. `andorra --version`
+5. `andorra auth status` — reports the Andorra account session (signed out is fine;
+   accounts are optional and only needed for hosted Jev and paid graph features).
+
+Notes:
+- To update later: run `andorra update` from any directory. It installs the latest npm
+  release of @andorra-labs/code and never downgrades.
+- Configuration lives in ~/.andorracode (override with ANDORRACODE_HOME). Saved API keys
+  are plaintext in ~/.andorracode/config.json — never commit or share that file.
+````
+
+## What the human still has to do
+
+Two things cannot be automated away:
+
+1. **The API key.** Provider keys are secrets; paste them yourself in the masked field, or export the environment variable yourself.
+2. **The optional account.** Run `andorra login` yourself if you want hosted Jev routing or paid graph features — the browser sign-in is interactive. See [Accounts](../getting-started/accounts.md).
+
+## Installing from source instead
+
+To run unreleased changes, clone and link the repository as [Getting started](../getting-started/README.md#install-from-source) describes. `andorra update` does not update a source checkout: pull and rebuild it yourself, or switch to the npm release with `npm install -g @andorra-labs/code@latest`.

package/docs/agents/mcp-server.md

@@ -0,0 +1,187 @@
+# Agent-centric MCP for Andorra Code
+
+## How it works
+
+Andorra Code ships a **local stdio MCP server** for agents that author and inspect graphs: agents running outside Andorra, such as Hermes and OpenClaw, and agents running inside one of Andorra's own graph nodes. **This is the supported surface for an agent to create or edit a graph.** The [Graph Builder](../guides/graph-builder.md) is the same authoring capability for people, and both write to the same graph store; an agent should not drive that browser UI to author a graph. The server does **not** execute an arbitrary authored graph, and it opens no network listener. It
+does run one fixed graph — the bundled Software Engineer harness — for hosts that want Andorra as
+a subagent (see [Subagent mode](subagent-mode.md)). That fixed harness is the only execution the
+server does: no surface of it selects a graph, and the run it does make permits writes by
+default, so a host that exposes the server to an agent is granting that agent write access to
+the workspace it names.
+
+1. An MCP client starts Andorra with the command below, discovers the tools, and reads the graph architecture resource.
+2. The agent lists valid providers and graphs, starts a new or existing ephemeral graph draft, and creates or edits nodes and links.
+3. Each Agent node authored through MCP must name a configured provider ID. Older published graphs may inherit the session provider; this does not change their persisted semantics.
+4. The agent validates the draft. Missing provider and outcome edges receive named error codes with node IDs and ports.
+5. The agent publishes. Publication saves the next immutable revision locally and then synchronizes to the cloud in the background, so a successful publication is locally durable but is **not** cloud confirmation.
+
+### Installation and MCP clients
+
+Build/install Andorra Code, sign into your paid account to edit graphs, and configure providers from Andorra's /providers screen. The same steps apply whether the client is a separate agent host or an Andorra node that launches the server as a tool:
+
+```bash
+npm install
+npm run build
+andorra login
+andorra
+```
+
+Illustrative client configuration (adapt the field names to the MCP host's format):
+
+```json
+{
+  "mcpServers": {
+    "andorra-code": {
+      "command": "andorra",
+      "args": ["mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+For a repository checkout, an equivalent executable is node <checkout>/dist/src/cli.js mcp-server --stdio. The protocol is stdin/stdout; do not parse the process's stdout as human terminal text. Don't accidentally configure the same server as a recursively self-launched Andorra runtime tool.
+
+## MCP subagent tools
+
+Four tools run Andorra as a subagent for the calling agent. They execute the bundled Software
+Engineer graph and nothing else: no graph is named, offered or selectable.
+
+| Tool | Input | Answers |
+| --- | --- | --- |
+| `andorra_subagent_start` | `prompt` (required), `provider?`, `model?`, `permissions?` (`full-access` or `read-only`), `workspace?` | the run's id, session id, provider, model and permissions |
+| `andorra_subagent_status` | `runId` (required) | the run: state, current node, recent events |
+| `andorra_subagent_result` | `runId` (required), `waitMs?` (0–60000) | the finished result, or `running` |
+| `andorra_subagent_cancel` | `runId` (required) | whether a run was cancelled |
+
+A provider/model is mandatory. Without one the start is refused with `PROVIDER_NOT_SET` and the
+error carries every configured provider with its models, so the calling agent can show the list to
+its user and retry with the choice. The full contract is in [Subagent mode](subagent-mode.md).
+
+## MCP graph tools
+
+| Tool | Purpose |
+| --- | --- |
+| andorra_graph_guide | Returns the architecture, examples, node ports and machine-readable error contract |
+| andorra_providers_list | Provider IDs, models and types, **no credentials** |
+| andorra_graphs_list | List published graph IDs, names and revisions |
+| andorra_graph_get | Read the exact saved latest or selected immutable revision, without editor-only migration |
+| andorra_graph_begin | Begin new or existing graph draft (mode create/edit, id, name for create); returns draftId |
+| andorra_graph_node_upsert | Create/replace a whole node with prompt, provider, completion, permissions and other settings |
+| andorra_graph_node_patch | Change a node's prompt/instruction/systemPrompt, provider, model or completion without replacing unrelated fields |
+| andorra_graph_node_remove | Remove a non-entry node and its edges |
+| andorra_graph_edge_upsert | Create/update an edge source -> target with an explicit named outcome |
+| andorra_graph_edge_remove | Delete an edge by ID |
+| andorra_graph_patch | Set entry, name, limits, schemas, widgets and metadata |
+| andorra_graph_validate | Validate without saving; return all missing-provider and missing-outcome issues, plus structural error |
+| andorra_graph_publish | Validate and save the next immutable revision, or report revision conflict |
+| andorra_graph_discard | Drop an uncommitted draft |
+
+Graph architecture is also exposed as a resource with URI andorra://graph/architecture. A third-party agent should read this before trying to design workflows. Agent completion outcomes may be pass/fail or custom names, Condition uses true/false ports, Loop uses body/done ports and bounded iteration counts, Approval uses approved/rejected, and Join all cannot wait for mutually exclusive branches. All nodes must be reachable from entry and every declared required outcome must route. See the resource for the full node and edge rules.
+
+### Example authoring sequence
+
+1. Call andorra_providers_list and use one of its IDs (the value "local" below is only an example).
+2. Call andorra_graph_begin with:
+
+```json
+{"mode":"create","id":"ci-qa","name":"CI QA"}
+```
+
+3. Call andorra_graph_node_upsert with the returned draftId:
+
+```json
+{
+  "draftId": "<draftId>",
+  "node": {
+    "id": "check",
+    "name": "Run QA",
+    "type": "agent",
+    "provider": "local",
+    "instruction": "Run tests and report pass or fail with evidence.",
+    "completion": {"mode": "outcomes", "outcomes": ["pass", "fail"]}
+  }
+}
+```
+
+4. Create two End nodes (IDs accepted, review). Call andorra_graph_patch with patch {"entry":"check"}.
+5. Call andorra_graph_edge_upsert twice:
+
+```json
+{"draftId":"<draftId>","edge":{"id":"pass-edge","source":"check","outcome":"pass","target":"accepted"}}
+```
+```json
+{"draftId":"<draftId>","edge":{"id":"fail-edge","source":"check","outcome":"fail","target":"review"}}
+```
+
+6. Call andorra_graph_validate. After valid=true, call andorra_graph_publish.
+
+To make a Loop, create a Loop node with loop.maxIterations and link its body and done ports. Node visits are unlimited by default: `graph.limits.maxNodeVisits` is absent, and `0` there means the same thing. A graph with a return connection still needs a ceiling, so set `graph.limits.maxNodeVisits` high enough for each cycle/reentry, or set `graph.limits.wallTimeMs` to bound the run by the clock instead. The existing graph validator remains the authority for reachable links, cycles, schemas and Join dependencies.
+
+### Validation errors
+
+Every MCP tool returns a JSON text payload with ok/data or ok/error. A failed call sets MCP isError=true. For example, omitting a fail branch yields:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "NODE_ROUTE_MISSING",
+    "nodeId": "check",
+    "port": "fail",
+    "message": "Node check: fail does not have a valid path. Please set a valid path for fail.",
+    "issues": [
+      {"code":"NODE_ROUTE_MISSING","nodeId":"check","port":"fail","message":"Node check: fail does not have a valid path. Please set a valid path for fail."}
+    ]
+  }
+}
+```
+
+Creating or modifying an Agent node without a provider returns NODE_PROVIDER_MISSING with nodeId and the text "Provider not set. Please select a valid provider." Untouched Agent nodes in previously saved graphs can continue to inherit the session provider; renaming the graph or changing an edge does not require backfilling their providers. Invalid explicit provider IDs return NODE_PROVIDER_INVALID. Other distinct errors include GRAPH_NOT_FOUND (unknown published graph ID/revision), EDGE_SOURCE_MISSING, EDGE_TARGET_MISSING, EDGE_OUTCOME_INVALID, EDGE_DUPLICATE, NODE_NOT_FOUND, ENTRY_NOT_FOUND, DRAFT_NOT_FOUND, AUTH_CHANGED (account switched during entitlement verification), and REVISION_CONFLICT. The latter is corrected by reopening latest, replaying the changes and publishing again: no silent overwrite. `GRAPH_INVALID` is reserved for actual graph-validator failures. Failures reading installation data instead return `STORAGE_ERROR` (filesystem access) or `BACKEND_ERROR` (unexpected backend/configuration failure), including for non-graph MCP tools; these errors do not instruct an agent to repair a graph.
+
+Drafts belong to the MCP process and expire after one hour since last use; a maximum of 24 are permitted. Exiting the MCP process discards any unpublished work. Cloud save and other GUI edits are reconciled by expected revision when publishing.
+
+## MCP sessions and monitoring
+
+| Tool | Function |
+| --- | --- |
+| andorra_projects_list | List registered projects and workspaces discovered from saved sessions |
+| andorra_sessions_list | Filter all local saved sessions by projectName, projectPath, status, lookbackMinutes, updatedAfter, updatedBefore, includeArchived, offset and limit |
+| andorra_session_get | Fetch one session's status and bounded recent turn excerpts (historyLimit max 20) |
+| andorra_sessions_attention | Find required_input and incomplete sessions for a supervising agent |
+
+Session status values:
+- **completed** — latest saved attempt succeeded; missing completion status means normal success
+- **pending** — empty session with no attempted turn
+- **running** — an active run with a living owner and no currently pending interaction
+- **required_input** — a live approval or question, or a stopped needs_clarification attempt
+- **incomplete** — cancelled/interrupted/exhausted/infrastructure failure, or a saved running marker with no live owner
+
+Examples:
+- Sessions for a project: {"projectName":"SparkAccel"}
+- Sessions updated in the last 15 minutes: {"lookbackMinutes":15}
+- Human feedback needed for a project: andorra_sessions_attention with {"projectName":"SparkAccel","lookbackMinutes":120}
+- All incomplete sessions: andorra_sessions_list with {"status":"incomplete"}
+- Latest 25 completed sessions in one workspace: {"projectPath":"/path/to/project","status":"completed","limit":25}
+
+Filtering by projectName uses an exact case-insensitive display-name match, and resolves an unregistered workspace by its folder name. Duplicate display names fail with AMBIGUOUS_PROJECT so an agent can specify projectPath instead. Result pages include total and nextOffset, limit max 100. Archived records are included by default; set includeArchived=false to exclude them.
+
+The app-server persists a minimal per-run sidecar during a pending **question** or **approval**, then removes it once settled. It contains the kind, a bounded prompt, IDs and timestamp, never tool arguments or provider credentials. A sidecar only signals live required input when the run claim is active; a stale file does not create a false request. A terminal-only CLI prompt does not currently use this app-server sidecar, so those live waits may be reported as running until an outcome is saved.
+
+A Hermes/OpenClaw supervisor can poll andorra_sessions_attention and notify the user when session ID/status/run ID changes. **Andorra MCP does not itself schedule polling or send alerts.** That belongs to the external agent. The server only inspects sessions persisted in the local ANDORRACODE_HOME. It does not aggregate histories from other remote-workspace hosts, and does not expose an MCP tool for automatically approving or answering a user question.
+
+## Behavior guarantees
+
+- **Revisions are immutable.** `andorra_graph_get` returns the unchanged published snapshot for the selected revision. Older schema revisions are not automatically migrated in read results; only `andorra_graph_begin mode=edit` produces an editor-ready draft for modification. This prevents an external agent from reasoning about an Orchestrator or route that did not exist in the requested immutable revision.
+- **The account is rechecked.** `andorra_graphs_list`, `andorra_graph_get`, and graph draft initialization recheck the current authenticated account after their storage reads. If you sign out or switch accounts in that window, the call fails closed with `AUTH_CHANGED` instead of disclosing the former account's graphs. A `revision` passed to `andorra_graph_get` must be a positive safe integer: invalid values such as `"1"`, `null`, fractions, and zero return `INVALID_ARGUMENTS` rather than silently selecting the latest revision.
+- **A crashed run is reported as such.** A run that dies before its turn is saved is reported as `incomplete` with a `crashedAttempt` run ID and timestamp, instead of continuing to show the older `completed` turn. Crash markers hold IDs and timestamps only, never task data or credentials, and only the newest unresolved marker per session is kept.
+- **Providers are rechecked before publishing.** A removed provider profile cannot be published, and a graph published after a provider reload still names the provider that was checked.
+
+## Security and limitations
+
+- Only trusted local MCP clients should launch the server. Session names, tasks and summarized content may reveal confidential project details.
+- Graph access enforces signed-in paid account membership with a verdict bound to the **same account subject** that owns the graph directory; an account switch during verification or pre-publish synchronization fails closed. Provider credentials are not returned. Providers are rechecked after pre-publish synchronization so a removed profile cannot be published.
+- Edits are drafts until publication. Graph revisions are immutable and conflict-protected. The graph authoring tools never execute submitted code.
+- The subagent tools execute only the bundled Software Engineer graph, and only with a provider and model the caller named (or the saved `externalSubagent` setting). They never edit a graph, never select one, and never run a paid or custom workflow.
+- Graph publication is local-first; cloud sync can be delayed. The returned sync state describes whether it is pending/offline.
+- Open interactive inputs are recognized from the app-server sidecars, not every possible terminal prompt.
+- Session scope is local; remote-workspace/global session aggregation and streaming notifications are future extensions.

package/docs/agents/subagent-mode.md

@@ -0,0 +1,146 @@
+# Subagent mode: Andorra as a subagent for another agent
+
+Claude CLI, Codex CLI and any other agent that speaks MCP (or can run a command) can run Andorra as
+a **subagent**: the host names a provider/model, gives a task, and receives the result of one
+Andorra Software Engineer run.
+
+Two surfaces, one behaviour:
+
+| Surface | For hosts that | Run it with |
+| --- | --- | --- |
+| MCP tools | speak MCP (Claude CLI, Codex CLI) | `andorra mcp-server --stdio` |
+| CLI command | spawn a process (Bash, a script, CI) | `andorra subagent --prompt "…"` |
+
+Both run **only the built-in Software Engineer graph** — the single-agent harness. There is no
+graph selection: a subagent run is one Software Engineer, working in one workspace, on one task.
+
+## The provider/model is mandatory
+
+A subagent run names the provider and model it uses. There are three ways to supply them:
+
+1. **Per call** — `provider` and `model` on the call (`andorra subagent --provider local --model
+   my-model`). The call's pick wins.
+2. **The saved setting** — `/subagent` in the TUI, or Settings → Runtime → External subagent in
+   the desktop app. It names one provider and one model, and every subagent run uses it.
+3. **Neither** — the run does not start. The reply is a `PROVIDER_NOT_SET` error carrying every
+   configured provider with its models:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "PROVIDER_NOT_SET",
+    "message": "No provider/model is set for Andorra external subagent runs. Ask the user which provider and model to use from the list, then retry with provider and model.",
+    "providers": [
+      { "id": "local", "type": "openai-compatible", "models": ["my-model", "other-model"] },
+      { "id": "anthropic", "type": "anthropic", "models": ["claude-sonnet-4-6"] }
+    ]
+  }
+}
+```
+
+**The host's job.** The agent that called the tool is the one that asks its own user: show the
+list, ask which provider and model to use, and call again with the pair. The user's answer is
+either sent with the retry (per call) or saved in Andorra's settings once, for every later run.
+
+## MCP tools
+
+Register the server with the host (field names vary by client):
+
+```json
+{
+  "mcpServers": {
+    "andorra-code": {
+      "command": "andorra",
+      "args": ["mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+For a checkout, the command is `node <checkout>/dist/src/cli.js mcp-server --stdio`.
+
+| Tool | Input | Answers |
+| --- | --- | --- |
+| `andorra_subagent_start` | `prompt` (required), `provider?`, `model?`, `permissions?` (`full-access` \| `read-only`), `workspace?` | `{ runId, sessionId, provider, model, permissions }` |
+| `andorra_subagent_status` | `runId` (required) | the run: state, current node, recent events |
+| `andorra_subagent_result` | `runId` (required), `waitMs?` (0–60000) | the finished result, or `running` |
+| `andorra_subagent_cancel` | `runId` (required) | `{ cancelled }` |
+
+The run is asynchronous on purpose: a Software Engineer run takes minutes, and a host's MCP tool
+timeout is usually shorter. Start it, poll `andorra_subagent_status` with the `runId` the start
+returned, and collect it with `andorra_subagent_result` and the same id. Every control call names
+the run it is about, so a call that arrives late cannot report or stop the run that replaced it.
+
+Only one subagent run is live per Andorra process; a second start is refused with
+`RUN_IN_PROGRESS` until the first finishes or is cancelled.
+
+## CLI command
+
+```sh
+andorra subagent --prompt "Fix the failing test" --provider local --model my-model
+andorra subagent --prompt "Add the missing endpoint" --provider local --model my-model --read-only
+```
+
+Stdout carries exactly one JSON line: the run result, or the `PROVIDER_NOT_SET` envelope. Progress
+notes go to stderr. `--graph` is not accepted — the graph is always the Software Engineer harness.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | The run succeeded. |
+| `1` | The run failed, or no provider/model was set. |
+| `130` | Cancelled (Ctrl+C). |
+| `143` | Terminated (SIGTERM), including a termination that arrived while the run's records were being written. |
+
+## What the run may do
+
+- **The workspace is the working directory** (or the `workspace` argument). The run reads, writes
+  and runs commands there, exactly as it would in the terminal.
+- **Writes are allowed by default.** A subagent is a Software Engineer; a run that cannot write
+  cannot do the work. Pass `permissions: "read-only"` (or `--read-only`) to deny every mutation.
+  The host is the one that decides to spawn it.
+- **The permission is one of two values.** `full-access` and `read-only` are the whole
+  vocabulary, and a value outside them is refused rather than rounded up to full access: a
+  caller that tried to restrict a run must not be handed the mutations it was withholding.
+- **The permission outlives the run.** The permission the host chose is recorded with the attempt,
+  so a read-only subagent that is later resumed — from the desktop, after a crash — is read-only
+  again, whatever the workspace's own permission is set to. A resume that names a permission of
+  its own still wins.
+- **One run at a time, and one graph.** A subagent run never edits graphs, never spawns further
+  subagents, and never selects a graph. The slot is the process's rather than a connection's: an
+  embedded host that builds several backends still gets one run per workspace, because two of them
+  working the same files would write over each other.
+- **A task is bounded.** A run accepts a task of up to 100,000 characters, the same bound the
+  engine's own run path applies. A longer one is refused before anything is written, whichever
+  surface asked for it.
+- **A model identifier is bounded.** A model named by the call is held to the same 500 characters
+  a saved model identifier is, and it is refused before the run record is written.
+
+## Where the run is recorded
+
+Every subagent run is an ordinary Andorra run: it writes a run record and a session under the
+installation home, so the work is visible in the Runs view and in the session list, and a crash is
+classified by the same recovery as any other attempt. The run record carries `subagent: true` and
+the permission the run was bound to.
+
+A finished run leaves no conversation behind: the checkpoint a stopped attempt needs is deleted
+once the attempt succeeds, because a successful run has nothing to resume. An attempt whose
+journal or checkpoint could not be written is marked as one no resume may replay — the resume
+would re-enter the node from its opening task and repeat the tool calls it had already made — and
+a resume of it is refused with a message that says so.
+
+The run's own record is durable as it goes: an event is on disk before the run moves on, and the
+checkpoint is written before the run advances past the tool call it describes. A process killed
+mid-run therefore leaves a record that says what had already happened, and a resume of it does
+not repeat the work.
+
+The reported totals are the attempt's whole spend: the preflight that probes the model before the
+first node runs is a model call too, so its requests and tokens are counted beside the graph's
+own calls — including when the probe reached the provider and failed.
+
+## See also
+
+- [MCP server](mcp-server.md) — the graph-authoring tools of the same server.
+- [Headless mode](../guides/headless.md) — one-shot runs without a subagent contract.
+- [ADR 0020](../../design/decisions/0020-external-subagent-mode.md) — why the provider is mandatory
+  and why the graph is fixed.

package/docs/concepts/README.md

@@ -0,0 +1,47 @@
+# Concepts
+
+## The graph is the harness
+
+Andorra Code does not hide your work inside one opaque agent loop. A task runs on a **graph** you can see and edit: nodes that do work, and typed edges that route results.
+
+```text
+andorra
+    ↓
+TUI coding client             ───┐
+                                  │
+andorra graph                     ├──► Andorra Code Runtime ───► pinned harness graph
+    ↓                             │
+Browser Graph Builder         ───┤
+                                  │
+andorra mcp-server --stdio    ───┘
+```
+
+Three surfaces drive the same runtime: the `andorra` TUI, the browser Graph Builder, and the local MCP server. All operate on the same graph store, node definitions, provider/model registry, and execution semantics. The Graph Builder is the editor for people; the MCP server is the editor for agents (see [Agent MCP server](../agents/mcp-server.md)).
+
+### Agent nodes
+
+Each Agent node is a full autonomous ReAct loop: it receives a task, thinks, calls tools, and finishes with a validated completion object `{ "summary": "...", "tests": [] }`. Every Agent owns an independent executor invocation with its own instruction, model, tool permissions, and completion outcomes (such as `pass`/`fail` or custom names).
+
+### The Orchestrator
+
+Graphs can start with an optional Orchestrator. It researches the codebase, asks you about requirements and design choices, then hands the confirmed task — with relevant files, acceptance criteria, and verification requirements — to its configured successor. Routing is expressed as named outcomes with written criteria, not keyword matching. In headless mode an Orchestrator run returns `needs_clarification` because the intake answer is interactive.
+
+### Control flow
+
+Condition routes on output fields (true/false ports), Loop repeats until an outcome or output matches (bounded by Maximum attempts; exhaustion stops instead of reporting success), and Parallel runs downstream Agents concurrently or as isolated read-only copies. Join all/any synchronizes branches. Cycles require a finite graph visit limit. Ordinary top-level stages run serially.
+
+### Typed handoffs
+
+Edges carry explicit input mappings — `$source.output.field` or `$run.input.task` references, or constants — instead of forwarding raw transcripts. Conversation reuse between Agent stages is a separate, explicit setting.
+
+### Revisions
+
+Saved graphs are immutable revisions. A published revision is never rewritten: a pinned run keeps describing the graph it started with, and editing produces the next revision. Selecting `default` always runs the single Software Engineer harness, signed in or not; the Orchestrator → Software Engineer workflow is the paid `:andorra` graph, and older bundled default revisions (`default@1`–`default@4`) remain available for compatibility.
+
+## How a task actually runs
+
+- **Tools.** Provider-visible coding tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, and `PowerShell`. CodeGraph/`repo_explore` is attempted before `Grep` for source-discovery tasks; native text search is the fallback. Shell handles Git, package managers, and tests.
+- **Approvals.** Writes and shell calls ask for approval unless YOLO is enabled for the session. See [Security and permissions](security.md).
+- **Context.** Reads, searches, and output are bounded; stale discovery output shrinks deterministically; older exchanges compact semantically under context pressure. Every ReAct iteration resends the whole conversation, so cumulative token totals measure repeated context, not one giant prompt.
+- **Memory.** Optional persistent project memory (Graphiti) survives across runs; CodeGraph indexes current code structure. See [Memory](memory.md).
+- **Workspace instructions.** `ANDORRA.md` at the project root steers every agent. See [Workspace instructions](workspace-instructions.md).