@amd-gaia/gaia 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -6,6 +6,44 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.3]
+
+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`

package/README.md

@@ -42,7 +42,7 @@ however you arrive at the terminal UI, it behaves identically.
 - **On Linux x64, glibc 2.34 or newer** for the agent sidecar (Ubuntu 22.04,
   Debian 12 and RHEL 9 or later). An older distro cannot start the agent. Check
   with `ldd --version`.
-- The `gaia` Python CLI **0.25.2 or newer** on `PATH` for the daemon the terminal
+- The `gaia` Python CLI **0.25.3 or newer** on `PATH` for the daemon the terminal
   UI starts. An earlier core cannot run this agent, so the UI comes up with
   nothing behind it. Install it with
   `curl -fsSL https://amd-gaia.ai/install.sh | sh` (Windows:
@@ -262,6 +262,14 @@ it out. It also carries `performance`, the turn's model and tool timings and
 each model call's token counts, when the binary sends it. See
 [`SPEC.md` §5.1](./SPEC.md#51-endpoints).
 
+**Keeping a multi-turn conversation? Send `turns`, not `context`** (contract ≥
+2.25). Send `turns: []` on the first turn so its `final` carries
+`model_messages`, store that with the reply, and send them back, oldest first,
+so the agent sees the tool calls it made and what they returned.
+Text-only `context` loses them, and the agent can't explain its own last turn.
+An empty `turns` list clears a retained session's history. Older binaries
+reject `turns` with `422`.
+
 Every failure throws a typed error (`IntegrityError`, `PlatformError`,
 `HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`) with a message
 that names what failed and what to do about it.

package/SKILL.md

@@ -252,7 +252,7 @@ curl http://127.0.0.1:8141/health
 ## 7. Call `POST /v1/gaia/query`
 
 This is the whole agent surface. There is **no typed query client** in this
-package — call it with plain `fetch`. Contract version **2.24**; the stream is
+package — call it with plain `fetch`. Contract version **2.25**; the stream is
 `text/event-stream` terminated by **exactly one** `final` or `error`.
 
 Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
@@ -270,6 +270,7 @@ Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
 | `internet_off` | no | Contract ≥ 2.23. `true` refuses web search and page fetches, the browser, connector, mailbox and Agent Hub tools and any call or shell command that contacts another host, with a message telling the model the internet is off for this chat; `false` allows them. A retained session keeps the last value: send it every turn. Omit it to leave the agent as it is. To change it mid-turn, `POST /v1/gaia/sessions/{session_id}/internet` with `{"internet_off": true}`; the next tool call follows it, and an unknown session is a **404**. Post it only once `/query` has answered, since the turn's own value replaces an earlier one; re-read the switch then and post it if it changed. |
 | `changes_turn_id` | no | Contract ≥ 2.19. Needs `session_id`. The agent copies each file before changing it, under `<GAIA home>/snapshots/<session_id>/<changes_turn_id>/`, so the turn can be reviewed and undone; the copies are complete before the terminal event. Format: 14 digits of local time, `-`, 8 hex digits (`YYYYmmddHHMMSS-xxxxxxxx`); anything else is a **422**. Omit it to copy nothing. |
 | `surface` | no | Contract ≥ 2.20. `"agent_ui"`, `"tui"` or `"cli"` — the front-end the turn comes from. With `"agent_ui"` the agent points recurring requests at the Agent UI's **Scheduled tasks** page. It also picks where a model-provider error tells the user to fix it; omitted (a headless caller), that is the model server the GAIA host uses (`LEMONADE_BASE_URL`). Read when a session is built. |
+| `turns` | no | Contract ≥ 2.25. Earlier turns as the model saw them, oldest first: each is that turn's `final.model_messages`, or a `{user, assistant}` text pair for a turn without one. Send it instead of `context` (then `[]`, or the request is a **422**) so the agent sees its own earlier tool calls and their results; send `[]` on the first turn. It keeps the newest whole turns that fit its window. Sent, even as `[]`, it makes `final` carry `model_messages`; `[]` also clears a retained session's history. |
 | `reasoning` | no | Contract ≥ 2.22. `true` streams the model's reasoning as `reasoning` events (`{ delta }`), apart from `status` lines and the answer's `token`s. Join the deltas as they come: each keeps its own spacing. Omit it and reasoning folds into `status` lines as before. |
 | `can_answer_questions` | no | Set `false` for one-shot / batch runs so the agent resolves ambiguity itself instead of parking on a question nobody can see. |
 | `model` | no | Overrides the model id. On a retained `session_id` a different model is **switched in place** (contract ≥ 2.14), keeping the conversation and any loaded skills; a switch that fails is a **409** and leaves the session on its previous model. |
@@ -336,7 +337,7 @@ The canonical event shapes, as emitted:
 | `tool_result` | `{ type, tool, data, render? }` — an MCP tool that returned text carries it in `data.mcp_output` (`{ text, truncated }`); a `search_web` result lists its hits in `data.sources` (`[{ title, url }]`) |
 | `needs_confirmation` | `{ type, run_id, action, summary, confirm_id?, always_scope?, risk?, tool_label?, args?, args_truncated?, prompt_context? }` — answer it, or it ends the run; see §8. `summary` shortens long code; `args` is the call itself, exactly the arguments the model sent, each value capped at 64,000 characters (`args_truncated: true` when one was cut — don't auto-approve a call you can't fully see). What GAIA adds to the prompt is in `prompt_context`, never `args`: `working_directory` (where a shell call runs, when the model's arguments don't say), `risk_note` (why GAIA's checks don't cover the call) and `file_path` (the absolute path a write lands at, when the model gave a relative one) |
 | `needs_input` | `{ type, run_id, request_id, question, options[], allow_free_text, sensitive, respond_url, timeout_seconds? }` |
-| `final` | `{ type, answer, usage?, failed?, context?, context_error?, performance? }` — terminal. `failed: true`: the model failed mid-turn and `answer` says what was and wasn't done; show it as an error, not a result. `context` / `context_error` and `performance` (the turn's step timings) are optional; see SPEC §5.1 |
+| `final` | `{ type, answer, usage?, failed?, context?, context_error?, performance?, model_messages? }` — terminal. `failed: true`: the model failed mid-turn and `answer` says what was and wasn't done; show it as an error, not a result. `model_messages` (contract ≥ 2.25, only when the request sent `turns`) is the turn as the model saw it; store it with the reply and send it back in `turns`. `context` / `context_error` and `performance` (the turn's step timings) are optional; see SPEC §5.1 |
 | `error` | `{ type, detail, status }` — terminal, surface `detail` verbatim |
 
 Rules a client must respect:
@@ -580,10 +581,12 @@ Two consequences an integrator needs to plan for:
   alongside `gaia-voice`'s 790.
 - **An embedding pass on the first semantic code search.** If the repo has no
   [code index](https://amd-gaia.ai/docs/guides/code-index), the first
-  `search_code_index` builds it, then searches. On a large monorepo that one
-  search takes minutes of local embedding; a task that never searches pays
-  nothing. `GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in the background at task
-  start instead.
+  `search_code_index` starts building it in the background. A small repo is
+  searched within that call; on a large monorepo the build takes many minutes
+  of local embedding, and each search until then reports its progress so the
+  agent greps meanwhile. A task that never searches pays nothing.
+  `GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in the background at task start
+  instead.
 
 The sidecar's CLI accepts only `--host` and `--port`, so pointing the map at a
 specific project means `GAIA_PROJECT_ROOT=/path/to/repo` in its environment, or
@@ -662,7 +665,7 @@ There is no silent null.
   temp dir) is dropped, and a **shared** bin directory is moved to the end
   instead of removed, so the `python3` / `lemonade-server` / real `gaia` beside
   it stay reachable. If the Python CLI isn't installed anywhere, the daemon never
-  comes up. It must also be **0.25.2+**: an older core's daemon starts fine but
+  comes up. It must also be **0.25.3+**: an older core's daemon starts fine but
   cannot run this agent, which reads as a UI with a dead agent rather than as
   a version problem.
 - **The TUI is installed as `gaia-tui`, never `gaia`** — the terminal-hub artifact
@@ -693,7 +696,7 @@ Then, in another terminal:
 
 ```bash
 curl -s http://127.0.0.1:8141/health          # {"status":"ok","service":"gaia-agent-gaia"}
-curl -s http://127.0.0.1:8141/version         # {"apiVersion":"2.24","agentVersion":"0.3.1"}
+curl -s http://127.0.0.1:8141/version         # {"apiVersion":"2.25","agentVersion":"0.3.1"}
 curl -s http://127.0.0.1:8141/v1/gaia/init    # 200 + "ready":true, or 503 + a "hint"
 curl -N -X POST http://127.0.0.1:8141/v1/gaia/query \
   -H 'content-type: application/json' \

package/SPEC.md

@@ -258,7 +258,7 @@ the header.
 | ------------------ | --------------------------------------- |
 | Default port       | `8141` (`DEFAULT_PORT` in `server.py`)  |
 | Reserved port      | `4001` — refused with a `RangeError`    |
-| Contract version   | `API_VERSION = "2.24"`                  |
+| Contract version   | `API_VERSION = "2.25"`                  |
 | Agent id / prefix  | `gaia` → `/v1/gaia/...`                 |
 
 ### 5.1 Endpoints
@@ -386,6 +386,19 @@ model's failure reads "the model server at `host:port`", not "Lemonade on this
 machine". Pre-2.20 binaries `422` the field and word every such error for the
 TUI.
 
+`turns` (contract ≥ 2.25) is the conversation so far as the model saw it,
+oldest first. Each entry is one earlier turn's `final.model_messages`, which
+holds the assistant's tool calls and the tool results, or a user/assistant text
+pair for a turn that recorded none. The agent replays the newest whole turns
+that fit its context window and says in a `status` event when older ones drop
+out. Sent, it replaces `context`, which must then be `[]` (anything else is a
+`422`); `turns: []` means no earlier turns, and clears a retained session's
+history. A request that sent `turns`, even `[]`, gets `model_messages` on its
+`final` so the caller can store it with the reply; a request without `turns`
+never does, because the record holds every tool result in full. It is also
+absent when the run had not finished 15 s after its answer, and that turn then
+replays as text only. Pre-2.25 binaries `422` `turns`.
+
 `reasoning` (contract ≥ 2.22), when `true`, streams the model's reasoning as
 `reasoning` events, `{ "type": "reasoning", "delta": "…" }`, so a client can
 show it apart from `status` lines and from the answer's `token`s. Each delta
@@ -504,7 +517,8 @@ directory shape, entry points, installed commands and platform quirks, present
 whenever the agent's working directory resolves to a code repository (a VCS
 directory or a recognised manifest at its root). `GAIA_PROJECT_ROOT=<path>`
 picks the project when the working directory is not it. If that repository has
-no code index, the first `search_code_index` builds one;
+no code index, the first `search_code_index` starts building one in the
+background and reports its progress until it lands;
 `GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in a background thread at task start
 instead. The same repository check also
 makes `run_shell_command` always-on for the session instead of semantically

package/binaries.lock.json

@@ -1,34 +1,34 @@
 {
   "schemaVersion": "3.0",
-  "agentVersion": "0.3.2",
+  "agentVersion": "0.3.3",
   "components": {
     "sidecar": {
-      "componentVersion": "0.3.2",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.3.2",
+      "componentVersion": "0.3.3",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.3.3",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-agent-win32-x64.exe",
           "executable": "gaia-agent.exe",
-          "sha256": "b107ed0740408b3ea50ab2556503549f173bcea13756e0cab0a5d0c98c867eab",
-          "size": 172894251
+          "sha256": "44892b0c48b6f41d25372045b9136dc259edd644196acc59592a8fc5d16ee7a4",
+          "size": 173039470
         },
         "darwin-arm64": {
           "filename": "gaia-agent-darwin-arm64",
           "executable": "gaia-agent",
-          "sha256": "2a339e225396df8f1623ff32051dd92800bf2224c76ba482cd25ae7ba30ebe30",
-          "size": 162463472
+          "sha256": "66f086d888ba8d42a18a38cc2a4f532200aa03ec36e22b8ca253e21698bbd01d",
+          "size": 162600800
         },
         "darwin-x64": {
           "filename": "gaia-agent-darwin-x64",
           "executable": "gaia-agent",
-          "sha256": "a796c734a72f43489062faa7d011399bcfdbd97280992e0ff8fea9734702aa28",
-          "size": 173074704
+          "sha256": "864155bcee93886d22f48f04c160329baf74c7900e6cb11693a1879eb2b5f18a",
+          "size": 173141904
         },
         "linux-x64": {
           "filename": "gaia-agent-linux-x64",
           "executable": "gaia-agent",
-          "sha256": "815817da63df38ae08dc96df226b758f53c54e56b59588b79a5e605c27c2ab64",
-          "size": 211939056
+          "sha256": "a35a9db438e4de0abd289283eaab7ac44abf2bc529d66deb5d2eada01c423e3d",
+          "size": 212086912
         }
       }
     },

package/dist/lifecycle.d.ts

@@ -24,7 +24,7 @@ export declare const DEFAULT_PORT = 8141;
 /** Repo-wide reserved port. Nothing here may ever bind it. */
 export declare const RESERVED_PORT = 4001;
 /** The apiVersion this package is built against (`server.py: API_VERSION`). */
-export declare const API_VERSION = "2.24";
+export declare const API_VERSION = "2.25";
 /** The agent id in the sidecar's route prefix (`/v1/gaia/...`). */
 export declare const AGENT_ID = "gaia";
 /** `GET /health` response. */
@@ -110,7 +110,7 @@ export interface WaitForHealthOptions {
  */
 export declare function waitForHealth(baseUrl: string, opts?: WaitForHealthOptions): Promise<void>;
 export interface VersionCheckOptions {
-    /** apiVersion this package was built against. Default API_VERSION ("2.24"). */
+    /** apiVersion this package was built against. Default API_VERSION ("2.25"). */
     expectedApiVersion?: string;
 }
 /**

package/dist/lifecycle.js

@@ -33,7 +33,7 @@ export const DEFAULT_PORT = 8141;
 /** Repo-wide reserved port. Nothing here may ever bind it. */
 export const RESERVED_PORT = 4001;
 /** The apiVersion this package is built against (`server.py: API_VERSION`). */
-export const API_VERSION = "2.24";
+export const API_VERSION = "2.25";
 /** The agent id in the sidecar's route prefix (`/v1/gaia/...`). */
 export const AGENT_ID = "gaia";
 /** Basename the sidecar executable is written as (matches the lock). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/gaia",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "One command to run GAIA: fetches and SHA-256 verifies the flagship agent sidecar and the terminal UI, then launches them. Runs 100% locally on AMD Ryzen AI.",
   "author": "AMD AI Group",