@amd-gaia/gaia 0.2.0 → 0.3.2

package/SPEC.md

@@ -135,6 +135,10 @@ failure anywhere: it is a 404 on a user's first run.
 | `linux-arm64`  |  **no**   |  yes  |
 | `win32-arm64`  |  **no**   |  yes  |
 
+The `linux-x64` sidecar is built on a glibc 2.34 floor (#5545), so it needs
+glibc 2.34 or newer at run time (Ubuntu 22.04, Debian 12, RHEL 9 or later).
+On an older distro it fails at launch.
+
 `terminal-hub` publishes all six. The sidecar is a PyInstaller freeze, produced on
 the platform it targets, and there is no arm64 Linux or arm64 Windows freeze.
 Resolving `sidecar` on those two keys raises `PlatformError` naming the platform
@@ -254,7 +258,7 @@ the header.
 | ------------------ | --------------------------------------- |
 | Default port       | `8141` (`DEFAULT_PORT` in `server.py`)  |
 | Reserved port      | `4001` — refused with a `RangeError`    |
-| Contract version   | `API_VERSION = "2.12"`                  |
+| Contract version   | `API_VERSION = "2.24"`                  |
 | Agent id / prefix  | `gaia` → `/v1/gaia/...`                 |
 
 ### 5.1 Endpoints
@@ -265,13 +269,204 @@ the header.
 | `GET`  | `/version`                       | Contract probe. `{ "apiVersion", "agentVersion" }` |
 | `GET`  | `/v1/gaia/version`               | The TUI's negotiation probe                    |
 | `GET`  | `/v1/gaia/init`                  | Readiness detail (Lemonade, model, connectors) |
+| `GET`  | `/v1/gaia/memory`                | The `/memory` snapshot (contract ≥ 2.13)       |
+| `GET`  | `/v1/gaia/skills`                | The skills the agent can load (contract ≥ 2.17) |
 | `POST` | `/v1/gaia/query`                 | The streaming surface (`text/event-stream`)    |
 | `POST` | `/v1/gaia/query/{run_id}/cancel` | Cancel a run by its host-minted `run_id`       |
 | `POST` | `/v1/gaia/query/{run_id}/respond`| Answer a mid-run question                      |
+| `POST` | `/v1/gaia/query/{run_id}/tool_decision` | Answer a confirmation-gated tool (≥ 2.14) |
+| `POST` | `/v1/gaia/sessions/{session_id}/bypass` | Stop the prompts for gated tools in one session (≥ 2.14); the shell gates stay on, so a gated shell command still answers `needs_confirmation` |
+| `POST` | `/v1/gaia/sessions/{session_id}/internet` | Turn one session's internet on or off from its next tool call, including in a turn already running (≥ 2.23) |
+| `POST` | `/v1/gaia/query/{run_id}/followup`| Add to a run already in flight (contract ≥ 2.15) |
+
+#### `/query` request body
+
+The full, machine-readable contract — every field, type, and which are
+required — is the committed
+[`openapi.gaia.json`](https://github.com/amd/gaia/blob/main/hub/agents/gaia/python/openapi.gaia.json),
+regenerated from the live routes by `python -m gaia_agent.export_openapi` and
+checked for drift in CI — the same pattern as the email agent's own
+`openapi.email.json`. Required: **`query`**, **`run_id`**,
+**`context`** — `additionalProperties: false`, so an unrecognized field or a
+missing required one is `422` before the agent runs. `run_id` must parse as a
+UUID (`uuid.UUID(v)`); a non-UUID string is also `422`. Everything else
+(`model`, `provider`, `max_steps`, `session_id`, `can_answer_questions`,
+`documents`, `allowed_paths`, `working_directory`, `memory`, `internet_off`,
+`changes_turn_id`, `surface`) is optional.
+
+`context` is the transcript you push. It replaces the agent's history for the
+turn. If it doesn't fit beside the agent's prompt and tools in the model's
+window, the agent drops the oldest whole turns until it does, and streams a
+`status` event saying older messages are out of the model's view. A single turn
+bigger than the whole budget is kept, not dropped: its longest messages are cut
+with a note saying how many characters are missing, so its answer stays in view.
+
+`documents` (contract ≥ 2.16) carries the absolute paths of the files the user
+attached to the conversation. Send the whole set on every turn. Before the turn
+runs, the agent indexes the ones it has not indexed yet, so a file attached
+mid-conversation is read on the next turn. Each path is granted as that exact
+file, never its folder. A relative path is a `422`. A missing file, a folder, or
+a secret the path policy refuses is reported as not indexed in the turn's
+`index_documents` step, and the turn still runs. Pre-2.16 binaries `422` the
+field, so probe `/version` before sending it.
+
+`allowed_paths` (contract ≥ 2.18) carries the conversation's file scope as the
+caller computed it, so the agent works in the folders the caller's UI shows. A
+new session is built with exactly that scope; a retained session gains any
+entry it lacks and drops none until the session ends — neither what the user
+granted mid-chat nor an entry the caller has since stopped sending. `GAIA_ALLOWED_PATHS`
+still narrows it, and a path outside it is asked about, never silently
+granted. Omit it for the agent's default scope. Pre-2.18 binaries `422` the
+field. Whatever the scope, its existing folders are named in the system prompt
+once, when the session is built, with GAIA's documents folder first; a folder
+added to a retained session later is usable but not named. A caller that omits
+the field, like the TUI, gets the default scope (the user's home folder) named.
+
+`working_directory` (contract ≥ 2.24) is the absolute chat workspace used as the
+base for relative file paths. It is separate from `allowed_paths`: the latter is
+an access allowlist, while this field determines where a bare `notes.txt` lands.
+New and retained sessions use it for relative reads, writes, edits and approval
+prompts, so the path shown to the user matches the file that is actually changed.
+A relative or empty value is a `422`; send it only when `/version` reports 2.24 or
+later.
+
+`memory` (contract ≥ 2.18) is `"on"`, `"private"` (a private chat) or `"off"`
+(memory turned off in the caller's settings). Under `"private"` or `"off"` the
+turn saves nothing to memory, including the errors and lessons the agent saves
+on its own. A retained session keeps the last value, so send it every turn;
+omit it to leave memory as the agent has it. `"on"` never turns memory on when
+the agent has none (no store, or `GAIA_MEMORY_DISABLED=1`). Pre-2.18 binaries
+`422` the field.
+
+`internet_off` (contract ≥ 2.23) is `true` when the caller's chat has the
+Internet switched off and `false` when it is on. With `true` the turn refuses
+web search and page fetches, the browser, connector (MCP), mailbox and Agent
+Hub tools and any call or shell command that contacts a host other than the agent's own machine, and
+the refusal tells the model the internet is off for this chat. A retained
+session keeps the last value, so send it every turn; omit it to leave the
+agent as it is. Pre-2.23 binaries `422` the field, so a caller whose chat has
+the internet off should check `/version` and refuse the turn on an older
+binary rather than answer it online, and cancel an older binary's running
+turn when the switch goes off.
+
+`internet_off` is read when a turn starts. To change it for a turn already
+running, `POST /v1/gaia/sessions/{session_id}/internet` with
+`{ "internet_off": true }` (or `false`): the session's next tool call follows
+it, and so do later turns until a `/query` sends another value. An unknown
+session is a **404** rather than a new one.
+
+Send it only once `/query` has answered. The response starts after the turn's
+own `internet_off` is applied, so a switch posted earlier is replaced by the
+body's value, and on a session's first turn it is a **404** because the
+session does not exist yet. A caller whose user can flip the switch while a
+turn starts re-reads it when `/query` answers and posts it if it changed.
+
+`changes_turn_id` (contract ≥ 2.19) asks the agent to record the turn's file
+changes for undo. Before a tool writes, edits, creates or deletes a file, the
+agent saves a copy of it under `<GAIA home>/snapshots/<session_id>/<changes_turn_id>/`,
+the store the Agent UI's Changes view, Outputs and Undo read. The recording is
+complete before the terminal `final` or `error` event is sent, even while the
+agent finishes post-answer work, so a caller may read or restore it as soon as
+the stream ends. It needs `session_id` (`422` without one) and must look like
+`file_snapshots.new_turn_id()` makes it — 14 digits of local time, a hyphen and
+8 hex digits — so a session's turns sort in the order they ran; anything else
+is a `422`. Work the agent cannot copy, such as a shell command, is noted in
+the turn as untracked. Omit the field to record nothing. Pre-2.19 binaries
+`422` it.
+
+`surface` (contract ≥ 2.20) is the front-end the turn comes from: `"agent_ui"`,
+`"tui"` or `"cli"`. With `"agent_ui"` the agent points recurring requests at the
+Agent UI's **Scheduled tasks** page instead of saying it cannot schedule. It is
+read when a session is built and kept for that session. It also picks where a
+model-provider error tells the user to fix it: each front-end gets its own
+settings screen, and a headless caller, which omits it, is pointed at the model
+server the GAIA host uses (`LEMONADE_BASE_URL`). A failed model request also
+names the `host:port` it went through; on a base URL the user set, a local
+model's failure reads "the model server at `host:port`", not "Lemonade on this
+machine". Pre-2.20 binaries `422` the field and word every such error for the
+TUI.
+
+`reasoning` (contract ≥ 2.22), when `true`, streams the model's reasoning as
+`reasoning` events, `{ "type": "reasoning", "delta": "…" }`, so a client can
+show it apart from `status` lines and from the answer's `token`s. Each delta
+keeps its own spacing: join them as they arrive. Without the field, reasoning
+folds into `status` lines as before. Pre-2.22 binaries `422` it.
+
+```json
+{
+  "query": "What's in this directory?",
+  "run_id": "5b1f6e2a-7c34-4b4d-9b3e-2b6d9a7a1c3e",
+  "context": [],
+  "session_id": "my-session-1",
+  "can_answer_questions": true
+}
+```
+
+#### `needs_confirmation` arguments
+
+A `needs_confirmation` event carries the gated call in `args`: exactly the
+arguments the model sent, each value capped at 64,000 characters with a note
+saying how much was cut, and `args_truncated: true` when any was. `summary`
+shortens long code, so show `args` when the user should read all of it; a
+policy client matches its rules on `args` and should not auto-approve a call
+with `args_truncated`. The agent never adds a key to `args`. What it adds to
+its own prompt is in `prompt_context`: `working_directory` (where a shell call
+runs, when the model's arguments don't say it), `risk_note` (why the
+agent's checks don't cover the call, which is then approved once) and
+`file_path` (the absolute path a write lands at, when the model gave a relative
+one). A prompt
+the agent raises on its own, such as `allow_path_access`, has the path it asks
+about in `args`.
 
 `/health` is liveness only. It says nothing about whether Lemonade is up or a
 model is loaded — `/v1/gaia/init` answers that.
 
+`GET /v1/gaia/memory` returns the read-only snapshot behind the TUI's
+`/memory` view: `{ "available", "reason", "stats", "contexts", "shown",
+"total", "items" }`. `available: false` means the session has no live memory
+store (Lemonade down, embedding model not pulled, disabled via env) — `reason`
+names why, so an outage never renders as "you have no memories". This is the
+daemon-transport counterpart of the stdio `MEMORY_DUMP_QUERY` sentinel; both
+paths call the same `build_memory_dump()` and return the identical shape.
+
+`GET /v1/gaia/skills` (contract ≥ 2.17) lists the skills the agent can load:
+`{ "skills": [{ "name", "description", "version", "tier", "tools", "path",
+"source" }], "invalid": { "<folder>": "<why it failed to parse>" } }`. It reads
+the same roots the agent does — its bundled skills, `~/.gaia/skills`, Claude
+Code skill folders — so a host without the Python package (the bundled skills
+live inside the binary) can still show them. `source` names the root a skill
+came from: `agent-bundled`, `user` or `claude-import`, or `null` for any other
+root. An agent that predates `source` omits the field; a host must treat a list
+where any skill lacks it as ungrouped and show it flat, not drop the skill. A skill root that cannot be read is a `500`
+naming it.
+
+`/query` streams the answer as `token` events before its terminal `final`. A
+run cancelled mid-answer (`/cancel`, or a dropped connection) ends with an
+empty `final` and sends no `token` after the cancel, so a host keeps the text
+the `token` events already delivered. Answer text the model produced but the
+stream had not yet sent when the cancel landed is discarded with the
+half-written tail.
+
+`final` carries `context` (contract ≥ 2.21): what the next model call holds
+if the caller pushes this turn back as history — the same payload the Agent
+UI's Context panel shows. `window` is the model's context window in tokens,
+`used` the tokens taken, and `system`, `tools`, `documents`, `history` split it
+by kind; `categories` lists the panel's rows (their tokens add up to `used`),
+`tool_loading` which tools ride every request, and `tokenizer.exact` whether
+the counts came from the loaded model's own tokenizer or the shared estimate.
+A turn that was stopped or ended on a model failure carries no `context`; a
+measurement that failed carries `context_error`, one sentence saying why, and
+the answer still stands. Older binaries send neither, so read `context` only
+when `/version` reports 2.21 or later.
+
+`final` also carries `performance`: the turn's step timings, as
+`{ "timing_summary", "conversation" }`. `timing_summary` holds the run's model
+and tool seconds and its model call count; `conversation` holds one
+`{ "role": "system", "content": { "type": "stats", ... } }` entry per model
+call, with that call's token counts and speed. The Agent UI turns it into the
+Context panel's "Under the hood" figures. A run that timed nothing
+carries none, and older binaries never send it, so read it only when present.
+
 ### 5.2 `session_id` and agent retention
 
 `POST /v1/gaia/query` accepts an optional `session_id` in the request body.
@@ -279,27 +474,48 @@ model is loaded — `/v1/gaia/init` answers that.
 whole conversation.** Contract ≥ 2.12 resolves `session_id` to a *retained*
 agent instead of a throwaway built fresh per call — indexed documents and
 `load_skill` state only survive between turns when the same `session_id`
-threads them together.
+threads them together. A `session_id` must be 1–128 characters from
+`A-Z a-z 0-9 . _ -`, not only dots (a UUID works); any other value is a **400**
+naming the allowed characters, on `/query`, `/sessions/{session_id}/bypass` and
+`/sessions/{session_id}/internet`.
+Omitting it is a valid, explicit one-shot: nothing persists past that single
+turn, and the agent is not told otherwise.
+
+Internal explicit deletion follows the same idle-only rule as eviction: it returns
+`False` for an absent or busy session and preserves a running agent. Successful
+deletion claims the turn lock before removal and closes outside the registry lock.
+
+A skill **captured** in-conversation (the `capture_skill` tool — itself
+confirmation-gated, so over `/query` it needs a session that can answer) loads
+**instruction-only** until a human runs `gaia skill promote <name>` in a
+terminal: `load_skill` injects its body but defers registering any tools it
+declares, and reports the deferral in its result. Integrators must not expect
+a captured skill's `<skill>/<tool>` names to exist before that promote.
 
 A retained skill stays *loaded* but its body is not necessarily in the prompt
 every turn: the agent selects per turn which loaded bodies match the query and
 collapses the rest to a one-line menu entry (re-activated by calling
 `load_skill` again). `GAIA_DYNAMIC_SKILLS=0` disables the selection;
 `GAIA_DYNAMIC_SKILLS_TAU=<float>` overrides its threshold; an embedder outage
-disables it for the session and every body renders. Omitting it is a valid, explicit one-shot: nothing
-persists past that single turn, and the agent is not told otherwise.
+disables it for the session and every body renders.
 
 A retained session also carries a **project map** — up to 600 prompt tokens of
 directory shape, entry points, installed commands and platform quirks, present
 whenever the agent's working directory resolves to a code repository (a VCS
 directory or a recognised manifest at its root). `GAIA_PROJECT_ROOT=<path>`
 picks the project when the working directory is not it. If that repository has
-no code index, the first turn starts one in a background thread;
-`GAIA_PROJECT_MAP_AUTO_INDEX=0` disables that. Neither affects the wire
-contract — they change what the agent knows and what the first turn costs.
+no code index, the first `search_code_index` builds one;
+`GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in a background thread at task start
+instead. The same repository check also
+makes `run_shell_command` always-on for the session instead of semantically
+selected. Neither affects the wire contract — they change what the agent
+knows, what tools it is offered, and what the first turn costs.
 
 A second `/query` for a `session_id` that already has a turn in flight gets
-`409 Conflict` — cancel the running turn or wait for it, then retry. A
+`409 Conflict` — cancel the running turn or wait for it, then retry. Once that
+turn has been cancelled, the new `/query` is held until it finishes its
+in-flight model call (up to **240 s**) and then runs, instead of getting `409`;
+only a cancelled turn that outlasts the wait still gets `409`. A
 `/query` that needs a **new** session while every retained slot is busy and
 none is idle enough to evict gets `503` with the reason in `detail` — a
 temporary, retryable condition, not a bug: wait for a turn to finish (or
@@ -317,10 +533,24 @@ not survive and should be reloaded.
 A second `/query` reusing a `run_id` that is still in flight gets `409` —
 `run_id` is caller-minted, so mint a fresh UUID per request; reusing one would
 leave the earlier run with no way to be cancelled. A `/query` supplying a `model`
-that differs from the one its `session_id` was built with also gets `409`: only
-agent construction reads a model, so the request cannot be honoured on the
-retained agent. Omit `model` to continue on the session's current one, or start a
-new `session_id` to switch.
+that differs from the one its `session_id` was built with **switches the retained
+agent in place** (≥ 2.14), so the conversation and any loaded skills survive the
+change; the same machinery the stdio transport's `/model` uses. A switch that
+fails — a missing Claude credential, an unknown local model — is a `409` naming
+the reason, and leaves the session on its previous model. The session records its
+`provider` too: a turn naming a different `provider` switches it the same way,
+onto that turn's `model` or, if it names none, the provider's default model. A
+`model` from the other provider than the one named (a `claude-*` id with
+`"lemonade"`, or a non-Claude id with `"claude"`) is a `400` on a new session and
+an existing one alike, before anything is built or switched.
+
+`provider` is optional, and an omitted one is **not** read as `"lemonade"` — it
+means "whatever the `model` implies", so a `claude-*` id alone reaches Anthropic
+and any other id runs locally. The `400` above therefore fires only when a
+request names a `provider` that disagrees with its `model`; there is no pair to
+disagree when only one is given. On a retained session, omitting both leaves the
+session on the provider it is already using, so an ordinary follow-up turn never
+moves a Claude conversation back to Lemonade.
 
 ### 5.3 Version gate
 
@@ -367,6 +597,15 @@ mints a per-session token and passes it as `GAIA_GAIA_SIDECAR_TOKEN_FILE`
 (`gaia.daemon.sidecars.spec` mirrors both names as plain strings so core never
 imports this wheel).
 
+**Child processes.** The programs the agent starts — shell commands, MCP
+servers, CLI installs and sign-ins, native hub agents, media tools, the Lemonade
+server — never inherit the sidecar token or GAIA's other internal credentials
+(the model-broker token, custody secret and engineering pairing token): their
+environment comes from `gaia.env.child_env`, which also drops any name listed
+in `GAIA_CHILD_ENV_DENY` (comma or space separated). User credentials such as `GH_TOKEN` pass through unchanged.
+`GAIA_NO_DOTENV=1` in the sidecar's launch environment stops it loading `.env`
+files; a `.env` file cannot set that switch itself.
+
 ### 5.5 Other transports
 
 The HTTP server above is the surface this package drives, and everything in
@@ -378,18 +617,30 @@ the hub, which is what this package delivers, is supervised by the daemon over
 the HTTP surface above instead (§6.1).
 
 It emits the identical canonical event vocabulary, but its input channel accepts
-a JSON line carrying a `gaia_control` key, which gives it something HTTP does
-not have: a back-channel that can answer a confirmation prompt *while* a turn is
-in flight, and stop that turn (`cancel`) without ending the process — so loaded
-skills, "always" grants, history and the bypass mode survive a cancel. It also
-takes `--bypass-permissions` (start with gating off) and
-`--use-claude` / `--claude-model` (route chat to the Anthropic API instead of
-local Lemonade; embeddings stay on Lemonade either way). None of that is
-reachable over `/v1/gaia/query`.
+a JSON line carrying a `gaia_control` key: a back-channel that answers a
+confirmation prompt *while* a turn is in flight, toggles full access or
+"accept edits" (file edits inside the starting folder run unasked; commands still
+ask), and stops a turn (`cancel`) without ending the process — so loaded skills,
+"always" grants, history and the permission mode survive a cancel. When stdin
+closes mid-turn (the host has gone), the running turn is cancelled and saved in
+the session history as interrupted: "This answer was interrupted when GAIA
+closed." The question is saved when the turn starts, so it survives even if the
+host kills the process before the turn ends. Another process sharing the
+history file leaves a turn that is still running out of its model view.
+
+Contract 2.14 gave the HTTP surface the same three capabilities per run and per
+session — `/tool_decision`, `/sessions/{id}/bypass` (the route keeps its
+original spelling), and `provider: "claude"`. What remains stdio-only is the
+*launch* form of those switches: `--full-access` starts a process with gating
+already off, `--accept-edits` starts it in accept-edits mode, and `--use-claude` / `--claude-model` pin the backend for the life
+of the process (embeddings stay on Lemonade either way).
 
 The stdio TUI also supports Local, Fireworks AI, and AMD LLM Gateway through
-Lemonade. `/model` lists downloaded local and discovered cloud chat models;
+Lemonade. `/model` lists downloaded local and discovered cloud chat models,
+grouped by provider, with `(default)` beside the configured default model;
 `/model <id>` switches the live client while preserving conversation and skills.
+The switch reply is one line naming the model, where it runs, and, for a cloud
+model, that messages and anything read from files or memory are sent there.
 Cloud IDs (`fireworks.*`, `amd.*`) route through Lemonade without local model
 loading. Model-state status events identify the provider and remote inference.
 The TUI's `/provider` panel configures credentials directly with local Lemonade;
@@ -397,8 +648,82 @@ keys never travel through stdio queries. These controls are not exposed over
 `/v1/gaia/query`. Lemonade may independently be configured to route a model
 remotely, so a local server URL alone does not establish local inference.
 
+`--bypass-permissions` turns off more than the prompt. It also lifts the shell
+tool's own guardrails for the session: the shell-only operators — redirection
+(`>`, `>>`, `<`), backgrounding (`&`), substitution (`` ` ``, `$()`) and the
+newline — parse and run, chaining (`&&`, `||`, `;`, `|`) already ran by
+default, the read-only binary allowlist is replaced by a developer set
+(`node`, `npm`, `make`, `cmake`, `go`, `cargo`, `sed`, `awk`, `curl`, `sleep`,
+`timeout`, `export`, `cp`, `mv`, plus `python`/`python3`/`pytest`/`gh`/`git`,
+which already had their own paths), and the shell rate limit is dropped. `git`
+being in that set means its policy's outright refusals — push, reset, rebase —
+also stop applying under bypass. That is
+arbitrary code execution in the working directory, which is why it exists only
+on this transport: one local parent process on a private pipe. It is **not**
+reachable over HTTP, and the request body cannot ask for it —
+`POST /v1/gaia/sessions/{id}/bypass` stops an HTTP session's approval prompts
+but never lifts these shell gates. A command those gates hold is never run
+unasked there: on a run someone can answer it still emits `needs_confirmation`
+and waits for `/tool_decision`, and on a run nobody can answer it is refused.
+`rm` is excluded
+from the developer set — not a boundary, since anything in the set can delete a
+file, but a tripwire against an accidental recursive delete. Redirection has one
+exception: a command that is nothing but a skill-granted CLI runs argv-only
+rather than through a shell, so a `>` there is refused with an explanation
+instead of reaching the binary as a literal argument.
+
+Every shell command run under bypass is recorded with its full arguments and its
+per-segment breakdown in `~/.gaia/cache/file_audit.log` — skipping the prompt
+does not skip the record. Treat that file as sensitive; arguments are verbatim.
+The host can toggle bypass mid-session over `gaia_control`, and the shell gates
+follow on the very next command.
+
+`--use-claude` is the one with a reach beyond the machine, and it cannot be
+turned on for what this package delivers: the terminal UI **refuses** the launch
+flag for a daemon-transport agent, with an error saying so, because it pins the
+backend for the life of the process and the daemon relay has no such lever.
+
+That is a limit on the *launch flag*, not on the agent. Since contract 2.14 a
+caller can ask for Anthropic per request with `/query`'s `provider` field (§5.2),
+so local inference is this package's **default**, not a property of the transport
+that nobody can change. Anything reaching Anthropic is named by the request that
+asked for it.
+
 ---
 
+### 5.6 Adding to a turn already running
+
+`POST /v1/gaia/query/{run_id}/followup` with `{ "text": "…" }` hands a live run
+something the user typed after it started. Contract ≥ 2.15.
+
+It is not a second turn and not an interrupt. The run keeps going on its
+existing SSE stream; the agent folds the text into that turn's context at its
+next agent-loop step boundary, labelled as arriving mid-task, and answers it
+alongside the work already in progress. A five-minute turn can therefore be
+corrected ("actually, only the unread ones") while it is still running, instead
+of the correction waiting out the turn it was meant to change.
+
+Two refusals, both loud, because the caller has already taken the message from
+the user and owes them a truthful answer about where it went:
+
+| Status | Meaning                                                      |
+| ------ | ------------------------------------------------------------ |
+| `404`  | No such run in flight — it finished or was cancelled. Send it as a new `/query`. |
+| `409`  | The run's agent is not accepting mid-turn input.              |
+
+A turn that has already formed its answer takes one more step to address a
+follow-up, so a turn answering in a single step is covered too. The one
+exception is a turn already at its step limit: the message stays queued rather
+than being consumed into a context no model call will read.
+
+Because `/query` is stateless (§2.4) the host still owns the transcript: record
+a delivered follow-up in the `context` you push on the **next** turn, between
+that turn's question and its answer, or the conversation loses words the agent
+demonstrably saw.
+
+Clients that predate 2.15 get a `404` on the path itself. Probe `/version`
+before sending rather than reading a 404 as "the run ended".
+
 ## 6. Process ownership
 
 Two distinct paths, deliberately:
@@ -458,8 +783,8 @@ failed start never leaks a process.
 | Code    | Meaning                                                                 |
 | ------- | ----------------------------------------------------------------------- |
 | `0`     | Success                                                                 |
-| `1`     | A typed failure: `IntegrityError`, `PlatformError`, `HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`, `PortInUseError`, `SidecarExitedError`, `MalformedResponseError`, or an unexpected error |
-| `2`     | Usage error: unknown command, invalid `--port`, or a flag the command does not read (`run --port`, `serve --component`, `serve --cache-dir`, `run`/`serve` `--platform`), an unknown `--component`, or a non-https `--base-url` without `--allow-insecure-base-url` |
+| `1`     | A typed failure: `IntegrityError`, `PlatformError`, `HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`, `PortInUseError`, `SidecarExitedError`, `MalformedResponseError`, or an unexpected error; also `serve` on Ctrl+C when the sidecar survives the forced kill (the message names its pid and the kill command) |
+| `2`     | Usage error: unknown command, an unknown option, invalid `--port`, or a flag the command does not read (`run --port`, `serve --component`, `serve --cache-dir`, `run`/`serve` `--platform`), an unknown `--component`, or a non-https `--base-url` without `--allow-insecure-base-url` |
 | *other* | From `run`: the TUI's own exit code, propagated verbatim                 |
 
 A TUI killed by a signal propagates as `128 + signum` (the shell convention), so a
@@ -535,3 +860,24 @@ yourself, which no lock describes, and `{ lock }` to reuse an already-loaded loc
 `DEBUG=gaia` (or `DEBUG=*`) enables debug output. **Everything goes to stderr** —
 stdout belongs to the TUI once it is exec'd, and to machine-readable JSON for
 `fetch` / `version`.
+
+## Developer engineering mode
+
+- **Opt-in.** The agent enables it with `--developer-mode` or `GAIA_DEVELOPER_MODE=1`
+  in the host process. `gaia engineering` and the engineering MCP server accept only
+  the explicit `--developer-mode` flag. It is separate from diagnostic `--dev`.
+- **Surface.** Only in that mode does the agent load the `gaia-harness-engineering`
+  skill and the `share_engineering_context`, `append_engineering_context`,
+  `approve_engineering_code`, `engineering_status`, `open_engineering_app` and
+  `revoke_engineering_context` tools. Sessions without it have none of them.
+- **Consent.** Sharing, appending and code approval each ask for a fresh approval of
+  the exact content or scope shown. None of them can be remembered or auto-approved.
+  Snapshots are recipient-bound and expire; revoking stops future reads.
+- **Pairing.** Configure the coding app's MCP connection from a Python GAIA install
+  with the `[mcp]` extra. The frozen binary this package ships can reuse that
+  configuration but cannot launch the Python MCP server itself.
+- **Code.** Fixes happen in the coding app, in worktrees from GAIA's managed source
+  cache. Preview results are reported by that app, not verified by GAIA. Nothing
+  self-assesses or updates the installed GAIA.
+
+See the [usage guide](https://amd-gaia.ai/docs/guides/harness-engineering).

package/binaries.lock.json

@@ -1,76 +1,76 @@
 {
   "schemaVersion": "3.0",
-  "agentVersion": "0.2.0",
+  "agentVersion": "0.3.2",
   "components": {
     "sidecar": {
-      "componentVersion": "0.2.0",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.2.0",
+      "componentVersion": "0.3.2",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.3.2",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-agent-win32-x64.exe",
           "executable": "gaia-agent.exe",
-          "sha256": "5d2ea1a5fd40e2399ba2bf50aec80b44d89c7e7bfdbad846c050f683fc8bf842",
-          "size": 103531825
+          "sha256": "b107ed0740408b3ea50ab2556503549f173bcea13756e0cab0a5d0c98c867eab",
+          "size": 172894251
         },
         "darwin-arm64": {
           "filename": "gaia-agent-darwin-arm64",
           "executable": "gaia-agent",
-          "sha256": "fbe526e7eb044a2ce633fbd487a1ae75001683eff190d8359eabf9ccc7196069",
-          "size": 88311472
+          "sha256": "2a339e225396df8f1623ff32051dd92800bf2224c76ba482cd25ae7ba30ebe30",
+          "size": 162463472
         },
         "darwin-x64": {
           "filename": "gaia-agent-darwin-x64",
           "executable": "gaia-agent",
-          "sha256": "b02731c786d79d7f5e644662238a64d1761eb6a23d421821df46e6a8282b585d",
-          "size": 94294544
+          "sha256": "a796c734a72f43489062faa7d011399bcfdbd97280992e0ff8fea9734702aa28",
+          "size": 173074704
         },
         "linux-x64": {
           "filename": "gaia-agent-linux-x64",
           "executable": "gaia-agent",
-          "sha256": "6c68a22c25954ea3c8d2a0a541bc04eba2401281d2a2b6448007983acd050a00",
-          "size": 140015368
+          "sha256": "815817da63df38ae08dc96df226b758f53c54e56b59588b79a5e605c27c2ab64",
+          "size": 211939056
         }
       }
     },
     "tui": {
-      "componentVersion": "0.24.1",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/terminal-hub/0.24.1",
+      "componentVersion": "0.25.0",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/terminal-hub/0.25.0",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-win-x64.exe",
           "executable": "gaia-tui.exe",
-          "sha256": "ce07269674de6773fd304d67eef3ff19cd578f447fc90a13f0309a61ae5ef504",
-          "size": 19213824
+          "sha256": "9b1c467b04b267f172a6024589f1ba0ddc882729337913d8afa7dcd43a7a7967",
+          "size": 20604416
         },
         "win32-arm64": {
           "filename": "gaia-win-arm64.exe",
           "executable": "gaia-tui.exe",
-          "sha256": "41f2a25b2bf15bea6f70626bb519496aeb822cc2629dd3529e325319b7abb3ca",
-          "size": 17744384
+          "sha256": "332068c5588e5639213225d63e4a1827d9258928e4053b7d6602668dc7eda60c",
+          "size": 19030016
         },
         "darwin-arm64": {
           "filename": "gaia-darwin-arm64",
           "executable": "gaia-tui",
-          "sha256": "dc334e89cebefaa2cc5117942ccbc4dc391034c3013ebf02d2bebf87f5e99a5a",
-          "size": 17499282
+          "sha256": "bb5ae28ae99ad25c095b3f57c4abf4e2ff67fa560122dc0a99036aedf9184802",
+          "size": 18801330
         },
         "darwin-x64": {
           "filename": "gaia-darwin-x64",
           "executable": "gaia-tui",
-          "sha256": "9af8c1fefeff4814bae6bbe9698ffaac3b59f248a422525e9f9b50812f5435da",
-          "size": 18629664
+          "sha256": "5259c82dc195297130e16377586ed6e0e668c5ec7f8b27a76ee029d67d776b52",
+          "size": 20015840
         },
         "linux-x64": {
           "filename": "gaia-linux-x64",
           "executable": "gaia-tui",
-          "sha256": "ef80198f3c4f6c2a4e92993fe19257c67cf009e29632398642549274ef8c2ffa",
-          "size": 18292898
+          "sha256": "07f1cc448f8056b5915eff2869f9f3eec3a5d04485d93e448ccad00d186d23c5",
+          "size": 19669154
         },
         "linux-arm64": {
           "filename": "gaia-linux-arm64",
           "executable": "gaia-tui",
-          "sha256": "31d9e1fee15e4a21e677ca7abb707fcf08257d5e7f50f1baa71bc7159335c170",
-          "size": 17105058
+          "sha256": "c324100d2de989823e816a6aae7eb4e1224019096b9a46ef1a6983ca6b98598f",
+          "size": 18350242
         }
       }
     }

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;GAWG;AA8BH,UAAU,UAAU;IAClB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,mEAAmE;IACnE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAaD,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuCpD;AAsID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,MAAM,GAAG,SAA+B,EACjD,KAAK,GAAE,MAAM,GAAG,SAA2B,GAC1C,MAAM,GAAG,SAAS,CAsBpB;AA+CD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAUnG;AAuKD,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC1D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;GAWG;AA8BH,UAAU,UAAU;IAClB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,mEAAmE;IACnE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAaD,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAwCpD;AA8JD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,MAAM,GAAG,SAA+B,EACjD,KAAK,GAAE,MAAM,GAAG,SAA2B,GAC1C,MAAM,GAAG,SAAS,CAsBpB;AA+CD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAUnG;AAsLD,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC1D"}