@amd-gaia/gaia 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,13 +4,554 @@ All notable changes to `@amd-gaia/gaia` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this package adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.1] — unreleased
+## [Unreleased]
 
-First working release. `npx @amd-gaia/gaia` is now the single command that gets a
-user running GAIA: it fetches and verifies everything GAIA needs and drops them
-into the terminal UI. Before this there was no packaged path at all — the flagship
-agent had to be run from a repo checkout with a Python environment, and reaching
-the terminal UI meant building it from source.
+- **Finished work is no longer replaced by "I can't confirm this is done".** A
+  redaction task that loaded the `document-extract` skill had its answer swapped
+  for a coverage warning about its own `redaction_log.csv`, and a task with two
+  named outputs only knew about the last one. Every file the request names, and
+  every file the turn wrote, is now an output and never a source; the skill
+  checks coverage only when the request names a source document or asks for
+  every item. No check replaces a non-empty answer any more: an unproven
+  save, test result or extraction keeps the answer and adds a short "I
+  couldn't confirm all of this" list after it; a turn that ends early keeps
+  what it said ahead of its report; and a tool that keeps failing ends with the
+  model's answer from what it found, then the failure. A failed image request
+  is no longer rewritten into advice to start GAIA with an `--sd` flag that
+  does not exist. `load_skill` no longer tells the model the extraction tools
+  cannot run when it is about to register them, and a rejected extractor reply
+  is now logged.
+- **`run_python` works in the Agent UI without a project.** It ran from the
+  server's own folder, which is not an allowed path, so every approved snippet
+  was refused and the agent fell back to slower shell commands. With no project
+  and a working directory you did not allow, a snippet now runs in the agent's
+  scratch directory, and its result says so. A project outside the allowed
+  paths is still refused.
+- **An "always" answer for a shell command no longer covers code in the
+  scratch folder.** A command run there or naming a path there — `cd` into it
+  then `python -m explore`, or `pytest`, `make`, `pip install`, `uv run` or
+  `go run` pointed at it — and a script handed a scratch path as an argument
+  now ask every time, with no `always_scope`, the same as a script there.
+  `always_scope` labels for commands that run code they do not show now say so:
+  `pytest (runs the test code it finds)`, `make (runs the Makefile's
+  commands)`, `python -m explore (runs that Python module)`.
+- **Exploring data no longer asks twice per step.** Each step wrote a helper
+  script into the agent's own scratch folder and ran it, so a data task asked
+  for approval about 30 times. Writes inside that folder now run unasked
+  (writes anywhere else still ask). Running a script from it asks each time
+  and offers no `always_scope`, since what is in that folder changes without
+  a prompt.
+- **A command no loaded skill grants asks you instead of failing.** `python
+  script.py`, `git commit` or `pip install` with no skill granting them used to
+  come back as "needs a skill grant … declares 'shell:execute:git' in its
+  SKILL.md", which nobody could act on. They now raise the approval prompt; a
+  skill grant still skips it for reads. A prompt's `summary` for a write or
+  code-running command ends with one plain line on what it can do, and the
+  `in <folder>` line also appears when an earlier `cd` moved the session. A
+  call you decline tells the agent not to reach the same result another way,
+  and a run nobody can answer refuses in one plain sentence.
+- **Commands GAIA's checks don't cover ask once instead of failing.** `git
+  push`, `git fetch`, `python -c`, PowerShell the checks can't read, a line with
+  shell operators, or a path outside the allowed folders used to be refused
+  outright. They now raise a prompt whose `summary` is the exact line the shell
+  will run, its full folder and a risk sentence, with no `always_scope`; an
+  approval runs that line once. Still refused with no prompt: an encoded
+  PowerShell command or invisible characters, a line whose quoting can't be
+  split the way the shell would, such a line that also deletes or discards work
+  (`git push --force`, `git reset --hard`, `rm` outside the project), and
+  folders no approval can open.
+- **`run_python` and `execute_python_file` work in the released binary.** The
+  binary has no Python interpreter, so it handed every script to its own
+  argument parser, which rejected it, and no calculation, chart or `.xlsx`
+  could be produced. It now runs scripts itself, with openpyxl, python-docx,
+  python-pptx, reportlab, pypdf, pandas, numpy, matplotlib and the full
+  standard library bundled for them. The Windows binary grows from 147 MB to
+  168 MB.
+- **Long Python data jobs can finish.** `run_python` gave up after 60 s and
+  the agent abandoned `execute_python_file` at 180 s even when it had asked
+  for 15 minutes, while the script kept running and left a corrupt workbook
+  behind. Python runs now get 120 s by default and up to 1800 s on request,
+  the agent waits that long, and a run that runs out of time is killed with
+  every process it started; the result names the files that changed while it
+  ran so the agent checks them instead of reporting them finished.
+- **Document search says when it could not search.** With the embedding
+  model or Lemonade Server down, `query_documents` and `query_specific_file`
+  answered "no relevant information found", so the agent told the user their
+  documents held nothing on the topic. They now return an error naming the
+  cause (Lemonade unreachable, or the embedding model failing) and how to fix
+  it. `index_document` and `index_directory` report the same cause, and
+  `index_directory` stops at the first such file and reports an error when no
+  file could be indexed. Hints for a missing optional package (RAG, PDF, Excel,
+  HTML parsing) say in a frozen build that it isn't bundled, and from source
+  give the install command for the running Python.
+- **A failed tool call is reported as a failure.** `run_shell_command` returned
+  `status: success` for a command that exited non-zero, so the TUI and Agent UI
+  showed a failed build or test run as a passed step. It is now `status: error`
+  with an `error` naming the failing step, its exit code and the last stderr
+  line; `stdout`, `stderr` and `return_code` are unchanged. grep's no-match and
+  diff's "inputs differ" (exit 1) stay a success and say so in `expected_exit`.
+  An MCP tool that answers `isError`, a DuckDuckGo search that was blocked, a
+  `tasklist`/`wmctrl`/`osascript` window listing that failed, a notification
+  whose PowerShell died, and an `open_url` with no browser to open are errors
+  too. Install hints in a frozen build no longer name the binary as a Python to
+  run pip with.
+- **Reviewing a few documents reads them in full.** `read_file` on a Word,
+  PDF or Excel file returned `[Binary file, N bytes]`, so to compare a term
+  sheet against a draft agreement the agent indexed them and ran a handful of
+  searches, and missed a closing date that differed between the two because no
+  search asked for it. `read_file` now returns the extracted text, in parts sized
+  to the model's budget that say where the next part starts, and the prompt
+  tells the agent to read a few documents in full for a review, comparison or
+  reconciliation and keep indexing for large collections and single lookups.
+- **`fetch_page` no longer drops the middle of a long page.** Text past
+  `max_length` was cut to its head and tail, which is where a product page keeps
+  its menus and footer, not its price. It now returns the first part with a
+  marker naming the offset of the next, takes `offset` to continue and `find` to
+  jump to the passages containing a word, says so when a word is not on the
+  page, and flags a page with almost no static text as rendered by JavaScript.
+  `Length:` now reports the whole page rather than the excerpt.
+- **Long desktop tasks finish with their deliverables instead of a bare "I
+  can't confirm this is done".** Picking a controller from nine datasheets and
+  pricing a 40-unit BOM ran out of its 50 steps while still searching for
+  prices, and the reply dropped the recommendation the agent had already
+  written. The agent's default step limit is now **150** (a `/query`
+  `max_steps` or `GAIA_AGENT_MAX_STEPS` still wins); at 20, 10 and 5 steps left
+  it is told to write the requested files from what it has, marking unverified
+  values, and a turn that still runs out keeps its findings and lists what is
+  missing after them.
+- **The model notice is one line.** Switching or restoring a model printed a
+  four-sentence paragraph that named the model twice and said "via Lemonade".
+  It now reads like "Switched to **DeepSeek-V4.1-Flash** on the AMD LLM Gateway
+  (cloud). Your messages, and anything read from files or memory, are sent
+  there." The `/model` list drops "via Lemonade" from its headings and marks
+  the configured default model with `(default)`.
+- **Single-file search results name their file.** `query_specific_file` put the
+  path only at the top of its result, so each chunk arrived with no source and
+  the chunk cards showed none. Every chunk now carries `source_file`, and the
+  result lists it in `source_files`, as `query_documents` already did.
+- **The turn log counts the answer of a streamed turn.** With `GAIA_TURN_LOG`
+  set, a turn whose answer streamed out recorded `answer_chars: 0`. It now
+  records the length of the answer the user saw.
+- **`run_python` and `execute_python_file` work in the released binary.** The
+  binary has no Python interpreter, so it handed every script to its own
+  argument parser, which rejected it, and no calculation, chart or `.xlsx`
+  could be produced. It now runs scripts itself, with pypdf, pymupdf,
+  python-docx, python-pptx, openpyxl, xlsxwriter, reportlab, pandas, numpy,
+  matplotlib and the full standard library bundled for them, and both tools
+  name those libraries to the model. A script that starts `sys.executable`
+  (`-m`, `-c`, a file) runs too; `-m pip` says packages can't be installed
+  and lists what is bundled. The Windows binary grows from 147 MB to 168 MB.
+- **A Python script that fails is reported as a failure.** A non-zero exit
+  came back as `status: success`, so the TUI showed a failed run as
+  successful. It is now `status: error`, with an `error` naming the exit code
+  and the last stderr line; `stdout`, `stderr` and `return_code` are unchanged.
+- **`GAIA_ALLOWED_PATHS` confines a run to the folders you name.** The agent
+  could read anything under the user's home and nothing narrowed that short of
+  embedding it, so an evaluation run could read the graders' answer keys. Set
+  to absolute folders, it narrows every file tool, search, index and shell path
+  check to them — it never widens, an invalid value stops startup, and code the
+  agent runs (`run_python`, shell) is not confined.
+
+- **The sidecar's start-up warm-up now makes the first question fast.** It
+  primed only the agent's own instructions, without the tool list or the rest
+  of the system prompt, so the first question re-read all ~19K prompt tokens
+  (34 s on Qwen3.6-35B-A3B). It now sends exactly what a turn sends, and the
+  first question reads only its own ~50 tokens (5 s). A warm-up that fails is
+  logged as a warning with its cause instead of an info line.
+- **`/model` names the command that connects a cloud provider.** With no
+  Fireworks or AMD gateway connection, the list told users to "connect this
+  provider in the TUI provider settings", a screen with no obvious way in. It
+  now says to run `/provider`, the command that opens it.
+- **The TUI's provider picker works after GAIA's Lemonade restarts.** When the
+  agent ran as the TUI's own child, its model-state ping kept naming the port
+  Lemonade started on, so after a restart the picker said "Lemonade did not
+  respond" while chat worked. With a local or cloud chat model the ping now
+  reports the port the agent talks to, and it still never starts a stopped
+  server. A Claude session still reports the port it started with.
+- **The Agent UI's Skills settings list this agent's skills.** With the agent
+  installed from the Hub, the page said the agent package was not installed
+  and to run `gaia init`, which changed nothing: the bundled skills live
+  inside the binary, where the UI could not read them. `GET /v1/gaia/skills`
+  (contract **2.17**) now returns them.
+- **A message sent right after Stop is answered instead of refused.** A stopped
+  turn holds its session until its model call returns, so the next `/query`
+  got `409 … is already running a turn` for as long as the stopped answer would
+  have taken — about 40 s for a long one. It now waits for the stopped turn to
+  finish (up to 240 s) and then runs. A turn that was not cancelled is still
+  refused at once.
+- **Documents attached to a chat now reach the agent.** In the Agent UI, a
+  Hub-installed agent answered "no documents are indexed" about a file the user
+  had attached, because the relayed turn never carried the chat's files.
+  `/query` now takes a `documents` field (contract **2.16**): the agent indexes
+  them before the turn, granting each exact file and not its folder, including
+  a file attached partway through a conversation.
+- **The first chat after the agent starts uses its own tools.** A session built
+  while the start-up warm-up was still building could end up running the
+  warm-up agent's tools, so a file it had just indexed read as access denied.
+  Agents are now built one at a time.
+- **Web requests work behind a corporate TLS-inspecting proxy.** HTTPS now
+  trusts the operating system's certificate store, as pip does, instead of only
+  Python's bundled list, so a proxy root such as Zscaler's no longer fails every
+  fetch with `CERTIFICATE_VERIFY_FAILED`.
+- **Starting the agent no longer downloads a model you skipped.** The HTTP
+  sidecar's start-up warm-up skips the default local model when it is not
+  downloaded, so someone using a cloud model is not handed a multi-GB download
+  they never asked for.
+
+## [0.3.0]
+
+Released with GAIA 0.25.0, and requires it.
+
+### Changed
+
+- **Requires `amd-gaia>=0.25.0` and `gaia-agent-chat>=0.2.0`.** Every file tool
+  now checks the allowed-folders rule, and that check ships in core 0.25.0; an
+  older core cannot import the chat agent this one builds on.
+- **`~/.gaia/logs/gaia-agent.log` stays bounded.** It rotates like `gaia.log`
+  (10 MB, three backups; `GAIA_LOG_MAX_MB`, `GAIA_LOG_BACKUPS`) instead of
+  growing without limit.
+
+- **Everyday questions get short, plain answers.** "Why is the sky blue?" got
+  140 words with an equation, and a Wi-Fi question got diagnostic shell runs.
+  The voice skill now caps an everyday answer at three plain sentences, goes
+  one level deeper only when asked, honours a stored short/detailed preference,
+  and answers general-knowledge questions without running tools.
+- **Memory off no longer loads the embedding model.** A private chat, or one
+  with memory switched off, used to load the ~300 MB embedder on its first turn
+  only to validate it and to score the always-on `gaia-voice` skill. It now
+  loads when memory is first used, such as when memory is switched back on or
+  the agent recalls something. A turn with only always-on skills loaded embeds
+  nothing.
+- **Every tool is offered on every turn again, as in the Agent UI.** Per-turn
+  tool selection swapped about a dozen tools in and out at its cap, which broke
+  the local model's prompt cache (17s to first token on a one-line question,
+  0.4s without it) and left out the tool a question needed: a CSV question was
+  given web tools and fetched an unrelated page. `GAIA_DYNAMIC_TOOLS=1` turns
+  selection back on. The registered count is 95: `load_tools`, the selector's
+  escape hatch, registers only while selection is on.
+- **A turn's silent opening now says what the model is doing.** A thinking
+  model sat on "Getting started" for 10-20 s while it read the prompt and then
+  reasoned in a paragraph released only once finished. `status` events gain an
+  optional `phase` (`loading_model`, `downloading_model`, `reading`,
+  `reasoning`, `tool_call`) with a `words` or `chars` count, sent when each phase
+  actually starts; the terminal UI shows them as "Reading your request",
+  "Reasoning · 214 words" and so on. Clients that ignore the field see the same
+  sentence in `message`.
+- **GPU models no longer load at 32K on an NPU-profile machine.** The NPU's
+  32,768-token ceiling was applied to every model whenever `default_device` was
+  `npu`, so a GGUF model ran at half its window and long tasks overflowed. It now
+  binds NPU (FLM) models only. A model can also opt in to a window sized to the
+  machine's memory, up to its native maximum.
+- **A stale `GAIA_SKILL_SET` now stops startup.** An undeclared name used to be
+  dropped silently, so the agent came up healthy with no skills. The sidecar
+  and the stdio entry now exit non-zero before serving, with a message naming
+  the valid sets; leave the variable unset to start without one.
+- **The code index is built on first search, not at task start.** In 32
+  SWE-bench tasks the agent never searched it, yet every task embedded the whole
+  repository in the background: about 2,000 local embedding requests per six
+  tasks. The first `search_code_index` now builds it; `GAIA_PROJECT_MAP_AUTO_INDEX=1`
+  restores building at task start.
+- **The first answer on a local model starts in seconds, not after a ~20 s
+  silence.** The terminal UI now shows a "Getting GAIA ready" stage before the
+  chat: the agent starts, loads its model and reads its system prompt there,
+  step by step. New stdio sentinel `warm_up` (answers `warmed_up`, or
+  `warm_up_skipped` for a remote model).
+- **Permission prompts say what a command does, once.** Running the tests is
+  labelled `RUNS CODE`, not `DESTRUCTIVE`; the command appears once, relative to
+  the project; and `a` ("always this session") is offered for shell commands and
+  Python too, covering the command's family — `pytest` covers
+  `python -m pytest`, `cd proj && pytest 2>&1 | tail`. Deletes never offer it.
+  `needs_confirmation` gains an optional `risk` field.
+- **Shift+Tab permission modes in the terminal UI**: ask → accept edits → full
+  access. Accept edits lets file edits inside the starting folder run unasked;
+  the stdio control verb is `accept_edits`, and `--accept-edits` starts in it.
+  Full access is still never turned on by a stray keypress.
+- **An unanswered prompt is reported as a timeout.** `tool_decision` accepts
+  `timeout`; the agent tells the user the request expired rather than that they
+  refused it.
+- The default chat model now follows the hardware. On a PC whose GPU has
+  ~27 GB for models — a 64 GB+ Strix Halo or a 32 GB GPU; the 23.3 GB model also
+  needs its context cache — `gaia init` sets up Qwen3.6 35B A3B (a 23 GB Lemonade
+  built-in MoE, run with thinking on) and records it as `default_model`; the
+  agent and its `GET /v1/gaia/init` readiness check use it for chat. Gemma 4 E4B
+  is still downloaded for vision. Every other PC, including a CPU-only one, keeps
+  Gemma alone.
+- **Qwen3.6 gets the longest context this PC's memory holds.** Up to its native
+  262,144 tokens on a Strix Halo (a 5.4 GB KV cache), about 152K on a 32 GB GPU,
+  never under 64K. Gemma stays at 64K.
+- Qwen3.8 Flash Next (82 GB, multimodal, thinking on) is available on a
+  128 GB Strix Halo and never picked as a default; it needs ~90 GB for models.
+  Choose it with `gaia config set default_model user.Qwen3.8-Flash-Next-GGUF`;
+  `gaia init` refuses it on a PC that cannot hold it.
+- **Bypass permissions is now called full access, everywhere.** `--full-access`
+  and `/full-access` replace `--bypass-permissions` and `/bypass`; the old names
+  fail with a message naming the new one. `/full-access always` (or
+  `gaia config set full_access true`) keeps it on across launches.
+- **The agent has to read a file before it changes it.** `edit_file`, and
+  `write_file` on an existing file, now refuse a file the agent hasn't read with
+  `read_file` in this session, or one that changed on disk since it did. Benchmark
+  runs caught the agent patching files it had never opened, from a grep snippet
+  or a guess; now it has to look first. A partial read counts, creating a file
+  needs no read, and the refusal comes before any approval prompt. It applies
+  with confirmations bypassed too.
+- **The agent sees every installed skill and loads the one that fits.**
+  Previously a per-turn matcher scored the request against skill descriptions
+  and loaded a skill on 0 of 24 benchmark tasks, so most GitHub requests never
+  learned `gh` was available. The system prompt now lists each installed skill
+  in one line (~1,000 tokens for the starter pack), and refusing a skill-gated
+  CLI names the skill to load. `GAIA_SKILL_DISCOVERY=0` still hides the list.
+  **Removed:** `GAIA_SKILL_DISCOVERY_TAU` is now ignored, and
+  `GaiaAgentConfig(skill_discovery_threshold=…)` raises `TypeError` — drop the
+  argument. See the Agent Skills spec, "Skill catalogue".
+- Contract `apiVersion` is now **2.14** (2.13 added `GET /memory`) for the two new routes and
+  the `claude` provider value. A differing major still raises
+  `VersionMismatchError`; a higher minor is accepted.
+- **Changing `model` on a live `session_id` switches in place** instead of
+  returning 409, so the conversation and any loaded skills survive it. A switch
+  that fails still returns 409 and leaves the session on its previous model.
+
+### Fixed
+
+- **Answering the agent's question from the Agent UI or the TUI works.**
+  `POST /query/{run_id}/respond` only took the answer as `response`, while
+  both front-ends send `{ request_id, value }` as the contract specifies, so
+  every answer was refused and the run waited until the question timed out.
+  It now takes `value`. `response` is still accepted; sending both, or
+  neither, is a 422.
+- **A file you allow is usable by every tool, including document Q&A.** Indexing
+  or querying a file outside the chat's scope was refused with no prompt, and
+  approving it through another tool still left it unreadable to the document
+  index. Indexing now asks the same question `read_file` does, and one approval
+  covers both. A tool waiting on that question is no longer abandoned at its
+  180 s limit while the question is still on screen. A refusal now tells the
+  model not to copy or move the file elsewhere to get around it.
+- **`--use-claude` works with the downloaded binary.** The release build left
+  out the Anthropic client, so every Claude launch from the terminal UI, and
+  every `/model` switch to Claude, failed with "The 'anthropic' package is
+  required", which a frozen binary cannot act on. The client is now bundled, and
+  the release build fails if it is missing.
+
+- **Code search works in an Agent UI chat that is not inside a project.** It
+  started in GAIA's own documents folder, which usually does not exist yet, so
+  every `search_code_index` failed with "repo_path does not exist". It now starts
+  in a repository the chat can reach, else any folder it can reach that exists.
+
+- **`/model` no longer offers speech or other non-chat models as chat
+  targets.** Whisper was listed as a "chat-capable" local model; switching to it
+  reported success and broke the next turn. Transcription, speech, music,
+  classification, upscaling and 3D models are excluded; a model labeled `chat`
+  still qualifies even if it also transcribes.
+- **The agent no longer starts an unrelated job after answering.** A bugfix
+  request loaded the `coding` skill, whose "find every call site" tip switched
+  on document inventorying; after the fix was done and verified, the agent spent
+  minutes extracting every file it had read until the user cancelled. Only a
+  skill built on the extraction tool turns inventorying on now. Separately,
+  once a turn has answered, a tool call on nothing the request touched is not
+  run and a second one ends the turn, and a tool that keeps failing with new
+  arguments is stopped like an identical repeat.
+- A "no" now covers what an action does, not the one tool it was asked
+  through. After you decline `pytest`, or leave its prompt unanswered, the
+  agent no longer writes `run_tests.py` and runs it with another tool: any
+  call that would run the tests, reach the same host, or change the same file
+  is stopped for the rest of that request. Where the surface can ask, you get
+  the exact command and why, with Allow once / Don't run it; otherwise the
+  agent stops and asks in its reply.
+- `/v1/gaia/query` now honours `provider` on an existing session. It used to
+  matter only when the session was created, so `provider: "lemonade"` could keep
+  sending a Claude session's conversation to Anthropic, and `provider: "claude"`
+  could run locally. A different provider now switches the session in place.
+  Naming a `model` that belongs to the other provider is a 400, on new and
+  existing sessions alike. Omitting `provider` and naming a Claude `model` now
+  starts a Claude session, the way it already switched an existing one — it used
+  to point the local backend at an id it cannot serve.
+- "Lemonade is not reachable" errors no longer tell users to run
+  `lemonade-server serve`, a command current Lemonade installs don't have. The
+  `GET /v1/gaia/init` hint, run errors, and `/model` now say how to start
+  Lemonade on the user's own install (tray app, macOS app, service, or CLI).
+  `/model <unknown>` with nothing downloaded likewise names the download command
+  the host actually has, instead of the removed `lemonade-server pull`.
+- `gaia serve` no longer exits 0 when Ctrl+C fails to stop the sidecar. The
+  error naming the surviving process and how to kill it was discarded, so the
+  next `serve` hit an unexplained port conflict. It now prints that error and
+  exits 1.
+- Conversation state is saved under `~/.gaia/sessions` instead of the directory
+  the agent was started from. A `session_id` must be 1–128 characters from
+  `A-Z a-z 0-9 . _ -`; any other value is a 400 on `/query` and
+  `/sessions/{session_id}/bypass` instead of a 500. A corrupt saved session fails
+  the request instead of being silently replaced.
+- `gaia hub install gaia` no longer refuses Intel Macs: the hub manifest now
+  lists `darwin-x64`, which the release already builds and the lock already ships.
+- The hub install card advertises the declared npm package instead of an unpublished PyPI wheel.
+- The readiness check (`GET /v1/gaia/init`) and the terminal session's health
+  report name GAIA's own Lemonade Server instead of Lemonade's default port.
+- Clearing a TUI conversation now also clears the flagship stdio agent’s prior
+  conversation context, while preserving the selected model, skills, and permissions.
+- Internal session deletion (not yet exposed by a route) refuses busy agents instead of closing them mid-turn.
+- Scratch files no longer land in the user's project. The system temp dir was
+  out of scope, so the agent wrote throwaway test runners and intermediate files
+  into the repository instead. It now gets its own scratch directory, named in its
+  prompt and deleted when the agent closes; the rest of the temp dir stays denied.
+- Every file tool now checks the same allowed-folders rule as `read_file`:
+  browsing, folder and content search, recent files, document indexing, folder
+  watching, code indexing, and where screenshots, transcripts and exports are
+  saved. A folder outside the scope gets the usual approval prompt, and a folder
+  you approve is readable by document indexing too.
+
+### Added
+
+- **A committed, machine-readable `/query` contract.** `openapi.gaia.json` in
+  the Python package is generated from the live routes
+  (`python -m gaia_agent.export_openapi`) and checked for drift in CI, so a
+  typed client no longer has to reverse-engineer the body from prose —
+  `query`, `run_id`, and `context` are required, `run_id` must be a UUID, and
+  the bearer-auth posture is declared in the schema. Swagger UI (`/docs`) is
+  disabled on the sidecar — it loads its JS from a CDN, an unexpected network
+  call for an offline embedder — but `/openapi.json` is still served.
+- **Programs the agent starts no longer inherit GAIA's internal credentials.**
+  Shell commands, MCP servers, CLI installs and sign-ins, native hub agents,
+  media tools and the Lemonade server get the sidecar's environment minus
+  GAIA's own tokens. Your own variables (`GH_TOKEN` and the like) still pass through, so CLI skills
+  keep working. An embedding app can withhold more names with
+  `GAIA_CHILD_ENV_DENY` (comma or space separated), and can stop GAIA loading
+  `.env` files with `GAIA_NO_DOTENV=1` — read from the real environment, so a
+  `.env` cannot set it.
+- **The agent can drive a real browser.** Pages behind JavaScript or a login
+  used to be out of reach — `fetch_page` is one HTTP GET, so a signed-in inbox
+  or a dashboard came back empty. Eight new tools open a real Chromium, read
+  it, click and type in it, and sign in to a site; the password goes to the
+  human, never the model, and the session is stored encrypted. Acting inside a
+  session you signed in to asks first. Ships behind the optional `browser`
+  extra; without it none of the eight register. Registered tool count goes
+  88 → 96.
+- **Fast mode, for a session that's only conversation.** `GAIA_FAST=1` drops
+  the flagship to a plain conversational surface for the whole session —
+  3,110 tokens of fixed prompt instead of 17,942 — so saying "hi" no longer
+  costs as much as a repo search. Session-scoped and one-way: a fast session
+  has no documents, files, web or skills and cannot pick them up mid-way.
+- **`chat`, `doc` and `file` are no longer offered as agents.** New users saw
+  four entries in the picker where only one is the product. The three ids still
+  resolve, so existing sessions, `*-lite` aliases and eval scenarios keep
+  working — they are hidden, not deleted, and `ChatAgent` remains the
+  flagship's base class. A session created without an explicit agent now lands
+  on the flagship rather than a hidden agent.
+- **Complete inventories from long documents.** Asking for every exercise,
+  action item or finding in a transcript now returns all of them, each with its
+  source quote, instead of a condensed list. The opt-in `document-extract` skill
+  drives new `extract_document_items` and `save_extracted_items` tools; a save is
+  reported only after the exact file is written and read back, and anything
+  unfinished is reported as incomplete. `gaia-voice` gains one routing line
+  (702 tokens).
+- **The agent can set up a skill's CLI instead of handing the job back.** Asking
+  it to triage GitHub issues on a machine without `gh` used to end the
+  conversation. Three new tools — `check_cli_setup` (read-only), `install_cli`
+  and `sign_in_cli` — let it report exactly what is wrong, install the CLI with
+  the machine's package manager, and drive the browser sign-in. Both mutating
+  tools are confirmation-gated on every call and no skill grant pre-approves
+  them; over `/v1/gaia/query` they are refused, like every other gated tool
+  (§8). Registered tool count goes 83 → 86.
+- **A shell command's `cd` now survives to the next one.** Every
+  `run_shell_command` call used to start from scratch, so `cd build` in one
+  call was invisible to the next. `get_shell_state` reads the session's
+  current directory, and `reset_shell_session` returns it to where the task
+  started. Registered tool count goes 86 → 88.
+- **Say something while the agent is still working.** `POST
+  /v1/gaia/query/{run_id}/followup` hands a live run a message the user typed
+  after it started (contract **2.15**). The run is not interrupted and no
+  second turn starts — the agent folds the text into the turn already running
+  at its next step boundary, so a correction during a five-minute task changes
+  that task instead of arriving after it finished. Unknown run → `404`, an
+  agent that cannot take one → `409`; both loud, because the caller has already
+  taken the message from the user. See SPEC §5.6 and SKILL §7.
+- **Approve a gated tool over HTTP.** `write_file`, `run_shell_command` and the
+  seven other confirmation-gated tools can now run through `/v1/gaia/query`:
+  the stream stays open on `needs_confirmation` and
+  `POST /v1/gaia/query/{run_id}/tool_decision` answers it. Previously the only
+  possible answer was a refusal, so those tools were unreachable over HTTP.
+  `POST /v1/gaia/sessions/{session_id}/bypass` turns the asking off for a
+  session. A run that cannot answer — no `session_id`, or
+  `can_answer_questions: false` — is still refused. See SKILL §8.
+- **Claude as an inference backend.** `provider: "claude"` sends the
+  conversation to Anthropic's API instead of the local server; `model` then
+  names a Claude model. Anything outside `lemonade` / `claude` is still a 400.
+- **`gaia-agent --serve` works from a pip install.** The console script pointed
+  past the transport dispatcher, so the documented HTTP mode exited with
+  "unrecognized arguments".
+- **Tracked eval scorecard ([`SCORECARD.md`](./SCORECARD.md)).** The agent now
+  ships a per-release scorecard: judged-scenario pass rate (the aggregate)
+  plus per-category rates and the judge's average score across the
+  13-category eval corpus (`eval/scenarios/gaia_*`), generated by
+  `hub/agents/gaia/python/packaging/gen_scorecard.py` from real
+  `gaia eval agent --agent-type gaia` runs. CI runs a PR subset
+  (`test_gaia_agent_eval.yml`), the weekly sweep runs the full corpus, and the
+  release pipeline gates on the committed card
+  (`scorecard-gate` + a judged eval subset in `release_agent_gaia.yml`).
+  The initially committed card is a harness validation measured with the
+  agent on `claude-haiku-4-5` (the dev environment cannot run Lemonade); the
+  first full runner refresh (`gaia_scorecard_refresh.yml`) replaces it with
+  the Gemma-4-E4B product baseline.
+- **`capture_skill` — capture a skill from pasted `SKILL.md` text, a URL, or a
+  local folder, with code inert until trusted.** The agent can now bring a
+  skill into `~/.gaia/skills` straight from the conversation (68 registered
+  tools, up from 67). Every capture is confirmation-gated, security-audited (a
+  `BLOCK` verdict refuses it), SSRF-guarded on the URL path, and lands at the
+  `experimental` tier. Instructions load immediately; any `tools.py`/scripts
+  the bundle carries stay **inert** until the user runs
+  `gaia skill promote <name>` in a terminal, which re-audits and binds trust
+  to the audited bytes. Over `/query`, `capture_skill` is gated like the
+  other confirmation tools (SKILL §8; SPEC §5.2 documents the load-time
+  deferral).
+- **`run_python`, always on.** A quick calculation or data transform is now one
+  confirmation-gated call that runs from the project root and returns what it
+  printed, instead of a throwaway script left in your repository. It joins the
+  always-on tool set (about 250 more prompt tokens per call) and the `shell`
+  bundle.
+- Opt-in developer-mode skill and consent-gated MCP handoffs to Claude Code/Codex,
+  with managed worktrees, approved feedback snapshots and reported preview results.
+  Python `[mcp]` installation is required for the bridge; normal mode has no access.
+- **The shell, always on inside a code repository.** When the project map
+  resolves to a repository (a VCS directory or a known manifest at its root),
+  `run_shell_command` is offered on every turn instead of only when the request
+  happens to sound like a shell request. Coding tasks such as "skip these tests
+  on PRs" previously ran without a shell and did every grep through `run_python`.
+  It follows the *same* root the map already uses, so the sidecar needs
+  `GAIA_PROJECT_ROOT=/path/to/repo` (or `GaiaAgentConfig(project_root=...)` when
+  embedding) to see your repository — its own working directory is whatever
+  started it, not yours. With no repository nothing changes, and the shell's
+  approval gate still applies either way. See SKILL §11.
+- **`sleep`, always on.** The agent can now wait before retrying, e.g. until a
+  rate limit resets, instead of giving up; before, its only way to wait was
+  `time.sleep` inside a confirmation-gated `run_python`. Up to five minutes per
+  call, no approval needed, and Stop ends the wait within a second. It joins the
+  always-on tool set (about 190 more prompt tokens per call) and the
+  `loop_control` bundle (80 tools → 81).
+- **`--bypass-permissions` now lifts the shell guardrails too.** It used to skip
+  only the confirmation prompt, which left the agent unable to run a build or a
+  test suite even with the user's blanket consent: no interpreter, test runner
+  or package manager was reachable, and nothing could write its output anywhere.
+  Under bypass, redirection (`>`, `>>`, `<`), backgrounding (`&`), substitution
+  (`` ` ``, `$()`) and the newline now parse and run — chaining with `&&` / `||`
+  / `;` / `|` already worked by default — the
+  read-only 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`), and the
+  shell rate limit is dropped. Off by default and byte-identical to before when
+  off. `git` in that set means its policy's outright refusals — push, reset,
+  rebase — also stop applying under bypass. `rm` stays excluded. Every command run this way is audit-logged with its full
+  arguments. Stdio only — an HTTP session's `/bypass` stops its approval prompts
+  but never lifts the shell gates, and the request body cannot ask for it.
+  Redirection has one exception: a command that
+  is nothing but a skill-granted CLI runs argv-only, so `>` there is refused
+  with an explanation instead of reaching the binary as text. See SPEC §5.5.
+
+### Notes
+
+- Tracks sidecar contract `apiVersion` **2.14**; a differing major raises
+  `VersionMismatchError`.
+- `GET /v1/gaia/memory` (contract 2.13) answers the same read-only snapshot the
+  stdio transport's `/memory` sentinel produces, so a daemon-supervised
+  install of the flagship exposes `/memory` too, not just a subprocess one.
+
+## [0.2.0] — 2026-09-16
 
 ### Fixed
 
@@ -29,7 +570,6 @@ the terminal UI meant building it from source.
   on the previous image.
 - TUI provider setup for Local, Fireworks AI, and AMD LLM Gateway, with masked
   runtime API keys, discovered models, and remote-inference status.
-
 - **A project map at task start.** In a code repository the agent now opens
   every task knowing the directory shape, the likely entry points, which
   commands are installed, and the three platform differences that change
@@ -38,10 +578,6 @@ the terminal UI meant building it from source.
   starts one in the background; `GAIA_PROJECT_MAP_AUTO_INDEX=0` turns that off,
   and `GAIA_PROJECT_ROOT` picks the project when the working directory is not
   it. See SKILL §11.
-- **`503` from `/query` at session capacity.** When every retained session
-  slot is busy and none is idle enough to evict, starting a new session
-  returns `503` with the reason in `detail` — retryable, distinct from a
-  bug-shaped `500`. See SPEC §5.2.
 - **Three further client-visible refusals from `/query`.** Reusing a `run_id`
   that is still in flight gets `409` — it used to replace the live run, leaving
   it with no way to be cancelled. Supplying a `model` that differs from the one
@@ -49,21 +585,17 @@ the terminal UI meant building it from source.
   the old model. A request with an absent or empty `Host` header gets `400`
   rather than being served, closing a DNS-rebinding check that failed open.
   See SPEC §5 and §5.2.
-- **Per-turn skill-body selection.** A loaded skill stays loaded, but its body
-  only renders in the prompt on turns whose query matches its description; the
-  rest collapse to a one-line menu the model re-activates with `load_skill`.
-  `GAIA_DYNAMIC_SKILLS=0` turns the selection off, `GAIA_DYNAMIC_SKILLS_TAU`
-  overrides the match threshold, and an embedder outage disables it for the
-  session (every body renders — capability is never lost to a failed match).
 - **Per-turn tool selection, now on by default for the flagship `full`
-  profile.** The model is sent at most 26 of its 71 tools on any one call — a
+  profile.** The model is sent about 28 of its 84 tools on any one call — a
   fixed core plus whichever cohesion bundles the query matched — instead of the
   whole registry every time. No capability is lost: `load_tools` is an escape
-  hatch the model calls mid-turn to pull in a bundle the selector missed.
+  hatch the model calls mid-turn to pull in a bundle the selector missed; that
+  bundle is appended for the rest of the turn (briefly above the cap, which the
+  next turn restores) so the prompt already sent stays cached.
   `GAIA_DYNAMIC_TOOLS=0` turns the selection off, `GAIA_DYNAMIC_TOOLS_MAX`
   moves the cap and `GAIA_DYNAMIC_TOOLS_TAU` the match threshold.
 - **One bundled skill ships enabled: `gaia-voice`.** It is a manifest `skills:`
-  entry, so it is always on and rendered in full on every LLM call — 676 tokens
+  entry, so it is always on and rendered in full on every LLM call — 702 tokens
   of every prompt, and it declares no tools. It is the agent's honesty floor
   (don't claim work you didn't do, don't present empty output as a result,
   don't substitute a near-miss and report success), which is why it is not in an
@@ -75,46 +607,6 @@ the terminal UI meant building it from source.
   behavioural rules intact. It had been a rationale document — every rule
   followed by the incident that motivated it — and the model needs the rule,
   not the incident report.
-- **`gaia run` (the default command)** — resolves the host platform, fetches and
-  SHA-256 verifies both binaries, then launches the terminal UI and propagates its
-  exit code. Arguments after a bare `--` are forwarded to the TUI verbatim.
-- **Dual-binary delivery.** The package installs two published artifacts: the
-  frozen agent sidecar (`gaia-agent`), published by this package's own release,
-  and the terminal UI (`gaia-tui`), which is the published **`terminal-hub`**
-  component. The TUI is consumed, not rebuilt — it is byte-for-byte the binary a
-  full GAIA install runs as `gaia tui`, so an npm user and a core user cannot end
-  up on terminal UIs that behave differently. A second build under this package's
-  own lane would have been the same bytes at a different version under a third
-  naming convention, and the two would have drifted.
-- **`binaries.lock.json` `schemaVersion` 3.0** — a component-keyed checksum
-  manifest where **each component carries its own `componentVersion`, `baseUrl`
-  and `platforms`**. Component-first rather than the email agent's flat `binaries`
-  map because the two differ in every dimension: hub lane, version, and platform
-  coverage (terminal-hub covers arm64 Linux and arm64 Windows; the PyInstaller
-  sidecar does not). A single shared base URL cannot address two lanes, so a
-  `1.x`- or `2.x`-shaped lock is rejected at load with an error naming the schema.
-- **Terminal-hub artifact naming is handled in data.** That lane names its Windows
-  builds `gaia-win-x64.exe` / `gaia-win-arm64.exe`, while platform keys come from
-  `process.platform` and say `win32`. The lock keeps the `win32-*` key and carries
-  the hub's spelling in `filename`, so nothing branches on platform to construct a
-  URL. The mapping is asserted on both sides (`TUI_ARTIFACT_NAMES` in
-  `src/platform.ts` and in the lock generator) because a wrong name there is not a
-  build failure anywhere — it is a 404 on a user's first run.
-- **Mandatory SHA-256 verification.** Every download is hashed and compared
-  against the lock before it is written. A mismatch deletes the download and
-  raises `IntegrityError` naming expected vs actual. A placeholder hash blocks the
-  fetch before any network call. There is no flag that relaxes either.
-- **`gaia fetch`** — download and verify without launching; prints JSON. Supports
-  `--component` and `--platform` for cross-platform staging in CI.
-- **`gaia serve`** — run the agent sidecar alone on `127.0.0.1:8141` for
-  integrators who want the REST surface without a daemon or a UI. Health-polls
-  `GET /health`, checks the contract version, and tree-kills on exit. Port `4001`
-  is refused.
-- **`gaia version`** — prints, per component, its version, the URL it is fetched
-  from, and its platform matrix.
-- **Programmatic exports** — `fetchAll`, `startSidecar`, `shutdown`, `runTui`, the
-  platform helpers, and the typed error classes, for embedding GAIA in another
-  app.
 - **The `.installed` record is written after a verified sidecar install.**
   Staging the binary was only half an install: the daemon and the terminal UI
   both key "this agent is installed" on `~/.gaia/agents/gaia/.installed`, and
@@ -205,14 +697,83 @@ the terminal UI meant building it from source.
   that killed only the launcher: the cancelled tool call ran to completion and
   the surviving process consumed the next message. The first Esc now sends the
   agent a `cancel` control message, so the turn ends and the session keeps its
-  loaded skills, "always" grants, history and bypass mode. A second Esc stops
+  loaded skills, "always" grants, history and full access. A second Esc stops
   the whole process tree.
-- **A restart after a hard stop no longer turns bypass permissions back on.**
+- **A restart after a hard stop no longer turns full access back on.**
   The replacement agent is launched in the session's current permission mode
   instead of from the original flags, and the TUI says what the restart lost.
 
 ### Notes
 
+- `gaia_agent` enforces a per-session caller-auth bearer on every `/v1/gaia/*`
+  request, plus a loopback `Host` allowlist and non-loopback `Origin` rejection.
+  This package mints no token, so a sidecar it spawns comes up in dev mode (token
+  check skipped, loudly warned, Host/Origin still enforced) — pass your own
+  through `spawnSidecar`'s `env` to turn it on. See SPEC §5.4.
+
+## [0.1.1] — 2026-08-21
+
+First working release. `npx @amd-gaia/gaia` is now the single command that gets a
+user running GAIA: it fetches and verifies everything GAIA needs and drops them
+into the terminal UI. Before this there was no packaged path at all — the flagship
+agent had to be run from a repo checkout with a Python environment, and reaching
+the terminal UI meant building it from source.
+
+### Added
+
+- **`503` from `/query` at session capacity.** When every retained session
+  slot is busy and none is idle enough to evict, starting a new session
+  returns `503` with the reason in `detail` — retryable, distinct from a
+  bug-shaped `500`. See SPEC §5.2.
+- **Per-turn skill-body selection.** A loaded skill stays loaded, but its body
+  only renders in the prompt on turns whose query matches its description; the
+  rest collapse to a one-line menu the model re-activates with `load_skill`.
+  `GAIA_DYNAMIC_SKILLS=0` turns the selection off, `GAIA_DYNAMIC_SKILLS_TAU`
+  overrides the match threshold, and an embedder outage disables it for the
+  session (every body renders — capability is never lost to a failed match).
+- **`gaia run` (the default command)** — resolves the host platform, fetches and
+  SHA-256 verifies both binaries, then launches the terminal UI and propagates its
+  exit code. Arguments after a bare `--` are forwarded to the TUI verbatim.
+- **Dual-binary delivery.** The package installs two published artifacts: the
+  frozen agent sidecar (`gaia-agent`), published by this package's own release,
+  and the terminal UI (`gaia-tui`), which is the published **`terminal-hub`**
+  component. The TUI is consumed, not rebuilt — it is byte-for-byte the binary a
+  full GAIA install runs as `gaia tui`, so an npm user and a core user cannot end
+  up on terminal UIs that behave differently. A second build under this package's
+  own lane would have been the same bytes at a different version under a third
+  naming convention, and the two would have drifted.
+- **`binaries.lock.json` `schemaVersion` 3.0** — a component-keyed checksum
+  manifest where **each component carries its own `componentVersion`, `baseUrl`
+  and `platforms`**. Component-first rather than the email agent's flat `binaries`
+  map because the two differ in every dimension: hub lane, version, and platform
+  coverage (terminal-hub covers arm64 Linux and arm64 Windows; the PyInstaller
+  sidecar does not). A single shared base URL cannot address two lanes, so a
+  `1.x`- or `2.x`-shaped lock is rejected at load with an error naming the schema.
+- **Terminal-hub artifact naming is handled in data.** That lane names its Windows
+  builds `gaia-win-x64.exe` / `gaia-win-arm64.exe`, while platform keys come from
+  `process.platform` and say `win32`. The lock keeps the `win32-*` key and carries
+  the hub's spelling in `filename`, so nothing branches on platform to construct a
+  URL. The mapping is asserted on both sides (`TUI_ARTIFACT_NAMES` in
+  `src/platform.ts` and in the lock generator) because a wrong name there is not a
+  build failure anywhere — it is a 404 on a user's first run.
+- **Mandatory SHA-256 verification.** Every download is hashed and compared
+  against the lock before it is written. A mismatch deletes the download and
+  raises `IntegrityError` naming expected vs actual. A placeholder hash blocks the
+  fetch before any network call. There is no flag that relaxes either.
+- **`gaia fetch`** — download and verify without launching; prints JSON. Supports
+  `--component` and `--platform` for cross-platform staging in CI.
+- **`gaia serve`** — run the agent sidecar alone on `127.0.0.1:8141` for
+  integrators who want the REST surface without a daemon or a UI. Health-polls
+  `GET /health`, checks the contract version, and tree-kills on exit. Port `4001`
+  is refused.
+- **`gaia version`** — prints, per component, its version, the URL it is fetched
+  from, and its platform matrix.
+- **Programmatic exports** — `fetchAll`, `startSidecar`, `shutdown`, `runTui`, the
+  platform helpers, and the typed error classes, for embedding GAIA in another
+  app.
+
+### Notes
+
 - The sidecar is installed into `~/.gaia/agents/gaia/`, the GAIA daemon's own
   cache directory. The daemon spawns and supervises the sidecar; putting an
   already-verified binary where it looks turns its fetch into a cache hit instead
@@ -229,16 +790,9 @@ the terminal UI meant building it from source.
   building its own TUI. Each terminal-hub artifact is additionally cross-checked
   against the hub's own server-side SHA-256 before its hash enters the lock.
 - Requires Node.js 18+ (built-in `fetch`), a running Lemonade Server for
-  inference, and the `gaia` Python CLI 0.23.1+ on `PATH` for the daemon the TUI
-  starts. 0.23.1 is the first core whose daemon knows how to supervise this
-  agent; on 0.23.0 the UI starts with nothing behind it.
+  inference, and the `gaia` Python CLI 0.25.0+ on `PATH` for the daemon the TUI
+  starts. 0.25.0 is the first core that can run this agent; on an earlier core
+  the UI starts with nothing behind it.
 - The sidecar has no arm64 Linux or arm64 Windows build. On those platforms the
   run stops with an error naming the platform and the supported set rather than
   launching a UI with no agent behind it.
-- `gaia_agent` enforces a per-session caller-auth bearer on every `/v1/gaia/*`
-  request, plus a loopback `Host` allowlist and non-loopback `Origin` rejection.
-  This package mints no token, so a sidecar it spawns comes up in dev mode (token
-  check skipped, loudly warned, Host/Origin still enforced) — pass your own
-  through `spawnSidecar`'s `env` to turn it on. See SPEC §5.4.
-- Tracks sidecar contract `apiVersion` **2.12**; a differing major raises
-  `VersionMismatchError`.