@amd-gaia/gaia 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -6,197 +6,425 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-- **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.
+## [0.3.3]
 
-- **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.
+Released with GAIA 0.25.3, and requires the `gaia` Python CLI 0.25.3+ on `PATH`.
+Integrators: the sidecar contract is now **2.25**; clients built for 2.18
+keep working, and older binaries refuse the new `turns` field with `422`,
+so probe `/version` before sending it.
+
+- **AMD LLM Gateway models run their tool calls.** The agent asks each cloud
+  model once whether it calls tools natively, and runs tool calls written as
+  text instead of dropping them, so a turn no longer ends without the work.
+- **Music and sound effects can be generated locally** with Lemonade's
+  audio-generation models (three new tools, 98 in total).
+- **The first code search on a large repo no longer hangs the turn.** The
+  index builds in the background and search reports its progress meanwhile.
+- **A bare file name means a file in the chat's folder** for reading,
+  listing, browsing, finding, searching and running, as it already did for
+  writing.
+- **`.epub` books are indexed chapter by chapter**, and a file the agent
+  can't read is refused instead of being indexed as binary text.
+- **Two agents starting together on a new database no longer fail** with
+  `database is locked`.
+
+### For integrators: contract 2.25
+
+- **The agent remembers its own tool calls across turns** (contract **2.25**,
+  #5701). A caller that pushed history as `context` could send only text, so
+  on the next turn the agent saw its earlier answers but not the commands it
+  ran or their errors, and "why did that fail?" got "I have no record of the
+  tool calls". Send the new `turns` field (`[]` on the first turn) and that
+  turn's `final` carries `model_messages`, the turn as the model saw it, tool
+  calls and results included. Send those back in `turns`, oldest first, and
+  the agent replays them, keeping the newest whole turns that fit its context
+  window. `turns` replaces `context` when sent (a non-empty `context` beside
+  it is a `422`), and `[]` clears a retained session's history. A caller that
+  sends no `turns` gets no `model_messages`, so a `final` stays small for
+  text-only clients. Pre-2.25 binaries refuse the field with `422`, so probe
+  `/version` first.
+
+## [0.3.2]
+
+Released with GAIA 0.25.2, and requires the `gaia`
+Python CLI 0.25.2+ on `PATH`. Integrators: the sidecar contract is now
+**2.24**; clients built for 2.18 keep working, and the new
+`/query` fields are refused with `422` by older binaries, so probe
+`/version` before sending them.
+
+- **Memory downloads its embedding model when it is missing.** On the first
+  start that uses memory, the agent now fetches the required embedding model
+  from Lemonade instead of silently running without memory; the initial
+  download can be about 300 MB.
+- **Unknown or misplaced switches are refused.** `gaia --forse` and
+  `gaia fetch --developer-mode` now exit 2 instead of silently starting the TUI;
+  pass terminal-UI arguments after a bare `--`.
+
+- **The Agent UI's "Under the hood" figures cover GAIA chats.** It said every
+  answer was "not measured", because only the agent saw its own step timings.
+  `final` now carries `performance` with them: the turn's model and tool
+  seconds and each model call's token counts. Older binaries never send it.
+- **`GET /v1/gaia/skills` says where each skill came from.** Each skill now
+  carries a `source` (`agent-bundled`, `user` or `claude-import`; `null` for
+  any other root), so the Agent UI can group the Skills list by origin. An
+  older agent omits it and the UI shows the list flat.
+- **One very long turn no longer vanishes from the conversation.** A turn
+  bigger than the whole history budget, like a pasted log or a long document
+  read, was dropped from what the model saw next, answer included, so "now
+  shorten that" ran with no record of it. It is now kept: long tool results
+  become a short note naming the tool, and its longest messages are cut with
+  a note saying how much.
+- **Internet off also stops the mailbox and Agent Hub tools.** With a chat's
+  Internet switched off, GAIA could still read Gmail or Outlook and search or
+  install skills from the Agent Hub, because those tools carry no URL for the
+  check to see. They are now refused with the same message as a web search.
+
+### For integrators: contract 2.24
+
+- **Relative file paths use the chat workspace.** A new `working_directory` field
+  on `/query` tells the agent where bare file names resolve, separately from
+  `allowed_paths`. New and retained sessions use the same workspace for reads,
+  writes, edits and approval prompts. Send it only after `/version` reports
+  contract 2.24 or later.
+
+### For integrators: contract 2.23
+
+- **`/query` takes `internet_off`** (contract **2.23**, #5883). The Agent UI
+  never told the agent when a chat's Internet switch was off, so the switch
+  stayed locked in every GAIA chat on a standard install. `true` refuses web
+  search, page fetches, the browser, connector, mailbox and Agent Hub tools and
+  commands that contact another host, as it does when the agent runs inside the Agent UI. `false`
+  allows them, and omitting it leaves the agent as it is. A retained session
+  keeps the last value. Older binaries `422` the field.
+- **`POST /v1/gaia/sessions/{session_id}/internet`** (contract **2.23**)
+  reaches a turn already running. Without it, a user who turned the internet
+  off mid-turn watched the agent keep searching until the turn ended. Body
+  `{"internet_off": bool}`; the session's next tool call follows it. An
+  unknown session is a `404`, as for `/bypass`. Post it only once `/query`
+  has answered: until then the turn's own `internet_off` replaces it.
+
+### For integrators: contract 2.22
+
+- **A client can show the model's reasoning.** Over `/query` the reasoning
+  only arrived folded into `status` lines, so the Agent UI showed none of it
+  for an installed GAIA. A request with `reasoning: true` now gets it as
+  `reasoning` events, `{ delta }`, kept apart from the answer. Without the
+  field nothing changes. Older binaries reject it with `422`.
+
+### For integrators: contract 2.21
+
+- **`final` says how full the model's window is** (contract **2.21**,
+  #5738). The Agent UI's Context panel and the meter beside its message box
+  stayed empty for every GAIA chat, because only the agent can measure its
+  own prompt, tools and window. `final` now carries `context` with that
+  measurement for the next call, or `context_error` when measuring failed.
+  A stopped or failed turn carries neither. Older binaries never send it.
+- **A relayed write prompt names where the file lands.** When the model asks to
+  write `shop2.txt`, `needs_confirmation` now carries the absolute path the
+  write resolves to in `prompt_context.file_path`, so a front-end can show
+  `/Users/you/shop2.txt` instead of a bare name. `args` still holds exactly the
+  model's `file_path`.
+- **A web search's results reach the client.** The Agent UI listed no Sources
+  for a GAIA web search, because a `search_web` `tool_result` carried only a
+  300-character summary. Its `data` now also carries `sources`, a list of
+  `{ title, url }` for each hit. Older binaries never send it.
+
+- **An old failure in memory no longer stops a request you make now.** A note
+  like "this page returned 503, don't waste tool calls on it" was obeyed as a
+  standing ban, so the agent refused a URL you handed it. Memories now reach
+  the model as dated notes your request outranks, and a passing failure is
+  marked as one. A 429 or 502-504 "try later" failure is no longer saved as
+  an error memory at all.
+- **Text from a file is not saved as your details.** The agent could save a
+  line from a document it read, or call it something you had saved. It now
+  saves text from a file, page or tool result only when you ask it to keep
+  something, and an empty memory search says that file text is not saved.
+
+- **Pushed history that doesn't fit the model's window no longer overflows
+  it.** `/query` used the `context` you pushed as-is, but you size it without
+  seeing the agent's prompt and tools. On a 32K window the two together could
+  exceed the window and fail the turn. The agent now keeps the newest whole
+  turns that fit beside its prompt and streams a `status` event when older
+  ones drop out of view.
+
+- **Homebrew tools are visible to the agent on a Mac.** An app opened from Finder
+  or the Dock starts with only the system folders on its search path, so the
+  agent could not run `gh`, `node` or anything else Homebrew installed, and its
+  prompt said they were "not installed". The agent now starts with the `PATH`
+  your login shell builds (only when opened that way: started from a terminal it
+  keeps the terminal's own `PATH`, so an activated virtualenv still wins), and a
+  tool it still cannot find is reported as not
+  reachable from its shell rather than missing from your machine. If your shell
+  startup is slow or fails, the agent logs a warning and keeps the old path.
+
+### For integrators: contract 2.20
+
+- **A failed model request says which endpoint failed, worded for your
+  front-end** (contract **2.20**, #5295). A headless caller of `/query` whose
+  hosted model returned HTTP 502 was told the "cloud request through Lemonade
+  failed" and to check "the TUI provider settings", though no TUI was
+  involved. The error now names the provider and the `host:port` the request
+  went through. A local model on a base URL you set is reported as "the model
+  server at `host:port`" instead of "Lemonade on this machine", since GAIA
+  can't tell what serves it. The advice follows the `surface` field: a caller
+  that omits it is pointed at the model server the GAIA host uses; `"tui"`,
+  `"agent_ui"` and `"cli"` keep their own settings screens. Older binaries
+  refuse the field with `422`, so probe `/version` before sending it.
+  Version skew: a front-end older than this release never sends `surface`, so
+  against this agent it gets the headless advice (the model server's
+  `LEMONADE_BASE_URL`) instead of its own settings screen. GAIA ships the TUI,
+  the Agent UI and this agent together, so this only shows when one of them is
+  updated without the others, or when the TUI's `/version` probe times out and
+  it can't confirm the agent takes the field.
+- **Answers stream over `/query`.** The HTTP sidecar ran its agent with
+  streaming off, so a relayed turn (the Agent UI, and the TUI's later sessions)
+  showed "Waiting on the model" until the whole answer landed at once, Stop could
+  not cut a model call short, and a stopped turn kept no text. Every `/query`
+  turn now streams its model calls and sends the answer as `token` events before
+  `final`, the same as the stdio transport. A run cancelled mid-answer stops
+  within a token and ends with an empty `final`, as stdio does; text not yet
+  sent when the cancel lands is dropped.
+### Fixed
+
+- **"Save it to my Documents folder" saves to the user's Documents folder.**
+  The system prompt told GAIA that "my documents" meant its own documents
+  folder (`~/.gaia/documents`), so a new file the user asked for in Documents
+  went into GAIA's hidden folder, where they would never find it. Finding an
+  existing file still checks GAIA's folders first.
+- **Secrets stay out of memory and the conversation log.** A bank PIN was saved
+  as a memory, because the filter knew passwords and API keys but not PINs. The
+  conversation log also kept the PIN, a password the agent had refused, a card
+  number and an SSN verbatim, where `search_past_conversations` read them back.
+  PINs, passcodes, card security codes, Luhn-valid card numbers and SSNs are now
+  refused as memories, and every credential-shaped span is replaced with
+  `[secret removed]` before a turn is logged.
+- **"How much free disk space do I have?" gets the right number, first try.**
+  On a Mac, GAIA said a nearly full disk had ~233 GB free: its system-info
+  tool reported only the share the system volume uses, so 97.8% used read as
+  5%. It now reports free space as macOS counts it, and says it answers
+  free-space questions, so GAIA no longer tries a shell command that is refused.
+- **Full access in the Agent UI asks before a gated shell command instead of
+  refusing it.** With `/sessions/{id}/bypass` on, a command such as a delete or
+  `git add` was refused outright, so a Full access chat could not run it at
+  all. On a run someone can answer it now emits `needs_confirmation` and runs
+  only on an allow from `/tool_decision`. The shell gates still stay on over
+  HTTP, commands that need no approval still run unasked, and a run nobody can
+  answer still refuses.
+- **Local models with a large window can write longer replies.** The output
+  cap is a quarter of the loaded window (16K at 64K, between 8K and 32K)
+  instead of a flat 8K, and a reply cut off at the cap is told to write the
+  file in smaller parts.
+- **`search_file_content` searches the workspace.** A relative or default
+  directory resolved against the sidecar's own folder and reported "0 files";
+  it now resolves against the workspace, searches text files of any extension,
+  and says when nothing was searched.
+- **Token counts are exact in the published binary, offline too.** The binary
+  could not load its tokenizer, so every turn trimmed history and sized
+  context from an estimate that overcounts, and logged `Unknown encoding
+  cl100k_base`. The tokenizer and its data now ship inside the binary, so it
+  no longer downloads anything to count tokens.
+
+### For integrators: contract 2.20
+
+- **`/query` takes `surface`** (contract **2.20**): `"agent_ui"`, `"tui"` or
+  `"cli"`. Asked to run something on a schedule from the Agent UI, the agent
+  said it had no scheduler and sent the user to Windows Task Scheduler; with
+  `"agent_ui"` it points them at the **Scheduled tasks** page instead. Older
+  binaries `422` the field, so probe `/version` before sending it.
+- **The agent knows which folders it can work in.** The system prompt now names
+  the session's folders and labels GAIA's documents folder, so "summarize X in
+  my documents folder" looks there first instead of trying `~/Documents` and
+  the home folder.
+
+### For integrators
+
+- **A tool result keeps the tool's own status.** When a tool's result had no
+  structured payload, the `tool_result` event's `data` carried only `summary`
+  and `success`, so a client could not tell a skipped `remember` (a private
+  chat saves nothing) from a saved one, and the Agent UI listed it as saved.
+  `data` now also carries `status` when the tool returned one. Additive, so
+  the contract version is unchanged.
+
+- **An MCP tool call says which connector it used and what came back.** A Git
+  connector call reached a client as a bare `mcp_git_git_log`, and its result
+  as "Tool 'git_log' returned data". `tool_call` gains optional `mcp_server`,
+  `mcp_server_label` ("Git") and `mcp_tool` ("git_log"), and the result's
+  `data` carries the tool's text in `mcp_output` (`{ text, truncated }`, capped
+  at 16,000 characters). Clients that ignore the fields see the same events.
+
+### For integrators: contract 2.19
+
+- **`/query` can record a turn's file changes for undo** (contract **2.19**).
+  Desktop chats run in this agent and the Agent UI relays them, so a file the
+  agent wrote never reached the chat's Changes view or its Undo. With
+  `changes_turn_id` (and `session_id`), the agent copies each file before
+  changing it into the snapshot store the Agent UI reads, and finishes the
+  recording before the terminal event. Older binaries refuse the field with
+  `422`, so probe `/version` before sending it.
+- **A confirmation's `args` are only what the model sent.** `needs_confirmation`
+  `args` also carried keys the agent adds to its own prompt — a risk note, a
+  scratch-folder marker, and the folder a shell call runs in — so a policy
+  client auto-approving on `args` matched fields the model never sent. `args`
+  is now exactly the call's arguments; the folder and risk note moved to a new
+  `prompt_context` object.
+- **A tool result names the file it wrote.** When a tool's result carries
+  `file_path` or `image_path`, the `tool_result` event's `data` now keeps it, so
+  a client can list the files a turn produced.
+
+## [0.3.1]
+
+Released with GAIA 0.25.1, and requires it. Integrators: the sidecar
+contract is now **2.18**; clients built for 2.17 keep working, and the new
+`/query` fields are refused with `422` by older binaries, so probe
+`/version` before sending them.
+
+### Linux
+
+- **The Linux agent runs on glibc 2.34 or newer.** The `linux-x64` agent is
+  now built against glibc 2.34 (#5545), so it starts on Ubuntu 22.04, Debian 12
+  and RHEL 9. Before, it needed glibc 2.38 and failed at launch on those.
+
+### For integrators: contract 2.18
+
+- **`/query` takes the chat's file scope and memory mode** (contract **2.18**).
+  `allowed_paths` lets the Agent UI hand the agent the same scope its session
+  panel shows. `memory` fixes private chats saving to memory: the relayed turn
+  never said the chat was private or that memory was off, so the agent went on
+  saving the errors and lessons it records on its own. `"private"` or `"off"`
+  now turns off every memory write for the turn.
+- **A confirmation carries the call it asks about.** `needs_confirmation` now
+  has `args` (each value capped at 64,000 characters, with `args_truncated`
+  when one was cut) and `tool_label`, so a client can show all of the code it
+  is approving rather than the shortened `summary`, and word a path prompt for
+  a file or folder that exists.
+- **A turn the model gave up on ends as failed, not done.** When the model
+  stopped responding or refused mid-turn (a stall, a 404, every retry spent),
+  the turn ended on the model's opening sentence and the Agent UI listed the
+  chat as done. The final answer now names the step, the provider and the
+  cause, what already ran, and what is unfinished, and the `final` event
+  carries `failed: true`.
+- **A turn queued for the model says so on the stream.** When another process
+  or request is using the model, `/query` now sends `status` events with
+  `phase: "model_queue"` every ~2 s, carrying a `queue` object with the turn's
+  place in line, who holds the model and how long it has waited, then one
+  `granted` update. A turn queued this way leases ahead of background work, and
+  `/query/{run_id}/cancel` takes it out of the queue. Before, the stream went
+  silent for the whole wait, so a client could not tell a queued turn from a
+  dead one.
+- **Needs core 0.25.1.** The chat agent this one builds on imports the
+  reasoning-effort tool, which first ships in core 0.25.1, so its
+  `amd-gaia` floor and `min_gaia_version` rise to 0.25.1 with that release.
+
+### File access and privacy
+
+- **Full access in the Agent UI grants the folders you name.** Turning it on
+  over `/sessions/{id}/bypass` refused every path outside the chat's scope with
+  nobody asked. On a run the caller can answer for, Full access now grants the
+  path without a prompt, as it does in-process; Ask mode asks. Unattended runs,
+  the home folder and drive roots are still refused.
+- **No more approval prompts for files that aren't there.** Naming a missing
+  file or folder outside the allowed paths opened a 10-minute approval prompt,
+  and only after it did the agent learn the file didn't exist; a retry asked
+  again. The tool now says the file wasn't found straight away, without asking,
+  and names an allowed or attached file with the same name. `analyze_data_file`
+  given a bare file name uses the attached file of that name instead of asking
+  about one in the working folder. Secret and protected paths are refused
+  exactly as before, whether or not they exist.
+- **A turn's file changes can be undone.** The agent saves a copy of every
+  file before a tool writes, edits, creates or deletes it, so the Agent UI
+  can show the turn's changes and put every file back, even after a restart.
+  A turn that also ran a shell command, Python or an MCP tool says undo may
+  be incomplete.
+- **Saving a download asks about the file, not its folder.** A download into
+  the home folder failed without asking, because the agent asked to grant the
+  whole folder. It now asks about the one file it is about to create.
+- **A document another program has open is re-indexed once it is free.** On
+  Windows, a watched file that Word, PowerPoint or another program held locked
+  was read once, reported as corrupted, and never re-indexed. It is now retried
+  a few times, and if it stays locked the log says to close the program and
+  save the file again.
+
+### Long and busy turns finish
+
+- **A context overflow no longer throws away the evidence.** A task that read
+  many documents used to fill a 32K–64K window, after which the overflow retry
+  dropped every older result and the answer was built on whatever was left
+  (#2780). The retry now keeps each result whole behind a handle the model can
+  re-read, and retries only when the request will then fit.
+- **Token counts no longer undercount when the tokenizer data can't load.** On
+  an offline or locked-down machine the counter fell back to characters ÷ 4.28,
+  which undercounts JSON and CJK text, so history that should take half the
+  window could fill it (#5066). It now warns and counts at least one token per
+  three UTF-8 bytes.
+- **Opening a session or switching its model no longer freezes the other
+  sessions.** The sidecar built a new session's agent, and ran a `/model`
+  switch (which builds a new client and checks its server), on its event
+  loop. Every other session's stream stopped for that long, heartbeats
+  included, so the TUI and the daemon relay saw an idle connection. That
+  setup now runs on a worker thread, and a request that goes away mid-setup
+  still releases its session.
+- **Background memory upkeep no longer wipes the chat's cached prompt.**
+  Memory consolidation, reconciliation and skill distillation ran on the
+  model slot the conversation uses, so the next message re-read the whole
+  ~19K-token prompt (~45 s on Gemma-4-E4B). They now run on the side slot,
+  as memory extraction already did.
+- **A turn cut short by closing the TUI is saved as interrupted.** The session
+  history got a turn only once it ended, so closing the TUI mid-turn saved it
+  as an ordinary "stopped" answer, or, if the TUI had to kill the agent, lost
+  the question entirely. The question is now saved when the turn starts, and a
+  turn the TUI's closing cut short ends with "This answer was interrupted when
+  GAIA closed." A resumed session (`GAIA_HISTORY_FILE`) sees it. Questions
+  queued before the close are saved as they ended.
+- **A busy, restarting or sleeping model server no longer fails the turn.**
+  The agent waits for a shared Lemonade that is loading another app's model,
+  waits up to 60 s for GAIA's own server to come back after a restart, and a
+  PC that sleeps mid-answer resumes instead of reporting a stall. A shared
+  KV-cache collision is no longer reported as "conversation too long".
+- **Nothing a tool waits on can hang the turn for good.** A hung MCP server,
+  a web server sending one byte at a time (page fetches stop at 120 s,
+  downloads at 30 min) and a busy embedder during indexing (one 300 s wait
+  per batch, with a message saying why) all end with a clear error. One bad
+  batch of parallel tool calls no longer trips the failure breaker and ends
+  the task with no answer.
+- **The agent's own scripts get time to run.** A script run through an
+  interpreter (`python analyze.py big.csv`) gets a 600 s default instead of
+  the 30 s kill for quick commands.
+- **Web search survives DuckDuckGo rate limits.** A refused search is retried
+  with backoff and through DuckDuckGo's lite endpoint, or answered by Tavily
+  when that connector is set up, instead of failing and being saved to memory
+  as a known error.
+
+### Memory you can trust
+
+- **Memory keeps what the user says, and keeps it current.** Facts come only
+  from what the user says about themselves, a forgotten fact is not re-learned
+  from old chats, a newer fact outranks the one it replaced, and a write that
+  carries tool-call markup or model reasoning is refused instead of saved
+  corrupted. Relevant memories now surface in the chats they are about.
+
+### Models and answers
+
+- **gpt-oss 20B and 120B are supported models.** On a model that grades its
+  reasoning, the agent gets `set_reasoning_effort` (low, medium or high) to
+  choose how hard it thinks for the rest of the request; every new message
+  starts again at medium. It is not registered on other models, so the
+  agent's 95 tools on Gemma and Qwen are unchanged.
+- **gpt-oss runs the agent.** Every array tool parameter now declares
+  `items`, without which gpt-oss's chat template rejected every request
+  with HTTP 500, and gpt-oss control markers inside a file or page the agent
+  reads are broken up so the model no longer answers with nothing.
+- **Answers are checked more honestly.** A claim such as "all 55 tests pass"
+  is checked even when the same sentence says "but" or "not", and asking the
+  agent to run a shell command runs it rather than reading the shell's state.
+
+### Diagnostics
+
+- **The turn log says how busy the model server was.** With `GAIA_TURN_LOG`
+  set, each model call records the server's own prefill, decode and cache-reuse
+  figures and the time spent waiting on the model-slot lease, the slot lock and
+  the status probe; each turn records its server compute, its non-model time,
+  and what filled the gaps between model calls. `GET /v1/gaia/debug/turns`
+  returns the last records while recording is on (off the versioned contract).
 
 ## [0.3.0]
 
@@ -543,9 +771,198 @@ Released with GAIA 0.25.0, and requires it.
   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.
 
+### Also in 0.3.0
+
+These were still listed under Unreleased when 0.3.0 was tagged, so they
+shipped in it.
+
+- **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.
+- **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.
+
 ### Notes
 
-- Tracks sidecar contract `apiVersion` **2.14**; a differing major raises
+- Tracks sidecar contract `apiVersion` **2.17**; 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
@@ -790,9 +1207,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.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.
+  inference, and the `gaia` Python CLI 0.25.2+ on `PATH` for the daemon the TUI
+  starts. 0.25.2 is the first core that can run the current release; 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.