@amd-gaia/gaia 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,244 @@
+# Changelog
+
+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
+
+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.
+
+### Fixed
+
+- Windows npm launchers now find the Python daemon CLI even when npm passes the
+  package script as argv[1], preserving unrelated tools in shared PATH directories.
+
+### Added
+
+- **Image generation, reachable out of the box.** "Draw me a red bicycle" now
+  generates a PNG with local Stable Diffusion and reports the path; previously
+  the tools existed behind a flag nothing turned on, so the agent just said it
+  couldn't. Adds `generate_image`, `list_sd_models`, and `get_generation_history`
+  (70 tools → 73) plus an `image_gen` bundle so per-turn selection can find them.
+  Generating swaps the resident model, so the next reply waits for the chat model
+  to reload. The `image-gen` starter skill covers prompt expansion and iterating
+  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
+  command syntax — instead of discovering each one through a failed tool call.
+  Capped at 600 prompt tokens. If the repository has no code index the map
+  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
+  the `session_id` was built with gets `409` rather than silently answering on
+  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
+  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.
+  `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
+  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
+  opt-in bundle the way a task skill is. No *skill set* ships enabled: the
+  manifest's `skill_sets:` / `default_skill_set:` blocks stay commented out until
+  an eval measures what loading several bodies costs. See SKILL.md §10.
+- **A materially smaller fixed prompt on every call.** That always-on
+  `gaia-voice` guidance was rewritten from 2,129 tokens to 676 with all of its
+  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
+  without it the UI ran the REST sidecar as its own stdio child and the chat
+  filled with uvicorn's startup log. It is written on a cache hit as well as a
+  fresh download, so an install left by an earlier version repairs itself, and
+  only for this host's own platform — a `--platform` fetch stages a binary for a
+  different machine and records nothing. See SPEC §4.1.
+- **`--allow-insecure-base-url`** — opt-in for a non-`https` `--base-url`, for a
+  trusted local mirror.
+
+### Changed
+
+- **A `LEMONADE_BASE_URL` that already carries a path is now used exactly as
+  written.** Previously any URL not ending in `/api/v1` had that suffix appended,
+  so a reverse proxy configured as `https://proxy.example/lemonade` was silently
+  rewritten to `https://proxy.example/lemonade/api/v1`. It now resolves to
+  `https://proxy.example/lemonade` unchanged, and only a bare origin with no path
+  at all gains `/api/v1`. If a proxied install starts returning `404` after
+  upgrading, append the API path to the variable yourself.
+
+### Fixed
+
+- **A second `gaia serve` no longer reports success against a server it does not
+  own.** With the port already taken, the incumbent answered `/health` while our
+  own sidecar was still unpacking, so the start "succeeded", printed a ready URL
+  for someone else's server, and the child then died of `EADDRINUSE`. The port is
+  now checked before anything is spawned, and a taken one fails naming the port
+  and how to find the process holding it.
+- **Importing the package no longer changes a host app's error handling.** The
+  crash and signal handlers reaped every sidecar *before* checking whether the
+  host had its own handler, so an exception the host handled killed the sidecar
+  and the host's next request got an unexplained `ECONNREFUSED`.
+- **`gaia run` no longer breaks the terminal UI's `PATH`.** Hiding our own `gaia`
+  shim removed the whole bin directory, which on a Homebrew or pipx layout also
+  took `python3`, `lemonade-server`, and the real `gaia` with it — so the UI
+  reported a missing CLI that we had hidden. A shared directory now moves to the
+  end of `PATH` instead of being dropped.
+- **Flags a command does not read are refused, not ignored.** `run --port 9000`
+  parsed fine and came up on the default port; likewise `serve --component` and
+  `serve --cache-dir`.
+- **A failed install says what to do.** A download that could not be moved into
+  place — usually a running sidecar holding the file on Windows — printed a raw
+  stack trace.
+- **`taskkill` failures name their reason.** Its exit code and stderr were
+  discarded, so "Access is denied" surfaced ten seconds later as a generic
+  timeout.
+- **A sidecar that survives shutdown is still reaped at exit.** `shutdown`
+  de-registered it before killing it, so one that survived both kill windows
+  became a permanent orphan holding the port.
+- **`serve` removes its signal handlers once it stops**, so Ctrl+C keeps working
+  afterwards, and a repeat Ctrl+C during a slow teardown now says what it is
+  waiting for instead of looking frozen.
+- **A non-JSON reply from a sidecar probe raises a typed error** rather than a
+  bare `SyntaxError` — the case where a proxy answers `200` with an HTML page.
+- **`--port` no longer accepts what `Number()` would coerce**, so `--port 0x2710`
+  is rejected instead of quietly binding 10000.
+
+### Security
+
+- **A desktop notification can no longer run code.** On Windows, `notify_desktop`
+  rendered its message box by pasting the title and body into a PowerShell command
+  string, so a `'` in either — text the model picks, and prompt-injected content
+  can steer it — closed the string literal and the remainder ran as PowerShell.
+  The command is now a fixed script that reads both values from the child's
+  environment, and the tool now needs your approval before it runs, like the
+  other tools that spawn a process (SKILL.md §8).
+- **`resolveSidecarPath` / `resolveTuiPath` verify the binary before returning a
+  path that gets spawned.** Both fed `spawn()` from a predictable cache path with
+  no integrity check, so anything able to write `~/.gaia/agents/gaia/` got code
+  run — despite the package documenting the SHA verify as its security boundary.
+  They now re-hash against `binaries.lock.json`; pass `{ verify: false }` for a
+  binary you built yourself. Note this makes them proportional to the binary's
+  size — resolve once at startup, not per request.
+- **`--base-url` requires `https`** unless `--allow-insecure-base-url` is passed.
+  The pinned SHA already made a plaintext mirror non-exploitable, but tampering
+  surfaced as a confusing `IntegrityError` instead of the transport failure it is.
+- **A ~200MB artifact is never held in memory whole.** Downloads stream to disk,
+  and the cache-hit check that re-hashes an already-installed binary — which runs
+  on every `gaia run` — reads it in bounded chunks. Both hashes are computed
+  incrementally, and a download is still verified *before* the file is moved into
+  place.
+
+### Fixed
+
+- **Esc stops a running turn in the terminal UI without killing the agent.**
+  The TUI used to kill the agent process, and on the released one-file binary
+  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
+  the whole process tree.
+- **A restart after a hard stop no longer turns bypass permissions 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
+
+- 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
+  of a second large download. `run` therefore does not spawn a sidecar itself —
+  the terminal UI reaches agents through the daemon relay and never holds a
+  sidecar token, so a second process would only contend for the port. `serve` is
+  the direct path for callers who do want to own it.
+- The TUI is installed as `gaia-tui`, never as `gaia`, so it cannot shadow the
+  `gaia` bin shim npm places on `PATH` — the terminal-hub artifact itself is named
+  `gaia-<platform>`, which is why the lock separates `filename` from `executable`.
+- Because the TUI comes from the `terminal-hub` lane, this package cannot be
+  released until that component is published at the version the lock pins. The
+  release fails loudly naming the required version; it never falls back to
+  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.
+- 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`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2024-2025 ADVANCED MICRO DEVICES
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,227 @@
-# @amd-gaia/gaia — placeholder
+# @amd-gaia/gaia
 
-This `0.0.0` publish exists only to create the package so a **trusted publisher
-(OIDC)** can be configured on npmjs.com. npm cannot create a package from OIDC,
-so the first version has to be published with a token.
+One command gets you a working GAIA:
 
-Nothing here is usable. The real CLI ships from `0.1.1` onward, published from
-`.github/workflows/release_agent_gaia.yml` with provenance.
+```bash
+npx @amd-gaia/gaia
+```
+
+That fetches the two binaries GAIA needs — the agent sidecar and the terminal UI —
+verifies both against a checksum manifest that ships inside this package, and drops
+you into the terminal UI. No Python to install, no repo to clone, no build step.
+Local inference is the default. The TUI can explicitly select Fireworks AI or AMD
+LLM Gateway through Lemonade; remote chat sends conversation history to that provider. The
+terminal UI's `--use-claude` flag, which would send a conversation to the
+Anthropic API, is refused for the agent this package installs — see
+[`SPEC.md` §5.5](./SPEC.md#55-other-transports).
+
+The terminal UI you get here is the published **`terminal-hub`** component — the
+exact same binary a full GAIA install runs as `gaia tui`, not a separate build. So
+however you arrive at the terminal UI, it behaves identically.
+
+## What it actually does
+
+1. **Resolves your platform** — `win32-x64`, `darwin-arm64`, `darwin-x64`,
+   `linux-x64` (plus `linux-arm64` / `win32-arm64` for the terminal UI).
+2. **Reads `binaries.lock.json`**, the checksum manifest published with this exact
+   package version. It records, per binary, which hub lane it comes from and what
+   it must hash to.
+3. **Downloads and SHA-256 verifies both binaries.** A hash that does not match is
+   a hard failure — the download is deleted and the run stops. There is no
+   "continue anyway" path and no unverified fallback.
+4. **Launches the terminal UI**, which brings up the GAIA daemon and the agent
+   sidecar and hands you the chat. Its exit code becomes ours.
+
+## Requirements
+
+- **Node.js 18+** (for the built-in `fetch`).
+- **[Lemonade Server](https://amd-gaia.ai/docs/reference/dev)** running locally —
+  it hosts the model the agent thinks with. GAIA tells you if it isn't up.
+- The `gaia` Python CLI **0.23.1 or newer** on `PATH` for the daemon the terminal
+  UI starts. Earlier cores start a daemon that has no entry for this agent, so the
+  UI comes up with nothing behind it. Install it with
+  `curl -fsSL https://amd-gaia.ai/install.sh | sh` (Windows:
+  `irm https://amd-gaia.ai/install.ps1 | iex`).
+
+## Supported platforms
+
+The terminal UI is Go and cross-compiles everywhere. The agent sidecar is a frozen
+Python build, produced on the machine it targets, and **has no arm64 Linux or arm64
+Windows build**. On those two platforms `npx @amd-gaia/gaia` stops with an error
+naming your platform and the ones that do work — it will not start a UI with no
+agent behind it.
+
+| Platform key   | Agent sidecar | Terminal UI |
+| -------------- | :-----------: | :---------: |
+| `win32-x64`    |       ✅      |     ✅      |
+| `darwin-arm64` |       ✅      |     ✅      |
+| `darwin-x64`   |       ✅      |     ✅      |
+| `linux-x64`    |       ✅      |     ✅      |
+| `linux-arm64`  |       —       |     ✅      |
+| `win32-arm64`  |       —       |     ✅      |
+
+`npx @amd-gaia/gaia version` prints this matrix, plus the version and source URL of
+each binary, for the release you have installed.
+
+## Commands
+
+```
+gaia [run] [options] [-- <tui args>]   Fetch + verify both binaries, then launch the TUI
+gaia fetch [options]                   Download + verify only; print JSON and exit
+gaia serve [options]                   Run the agent sidecar alone (REST API, no TUI)
+gaia version                           Print the lock manifest and this host's platform
+gaia help                              Show help
+```
+
+Anything after a bare `--` goes to the terminal UI untouched:
+
+```bash
+npx @amd-gaia/gaia -- --debug
+```
+
+Common options:
+
+| Flag                  | Meaning                                                       | Accepted by |
+| --------------------- | ------------------------------------------------------------- | ----------- |
+| `--base-url <url>`    | Override the download base URL from `binaries.lock.json`. Must be `https:` | `run`, `fetch`, `serve` |
+| `--allow-insecure-base-url` | Permit a non-`https` `--base-url` (a trusted local mirror) | `run`, `fetch`, `serve` |
+| `--sidecar-dir <dir>` | Where to install the agent sidecar (default `~/.gaia/agents/gaia`) | `run`, `fetch`, `serve` |
+| `--cache-dir <dir>`   | Where to cache the terminal UI binary                          | `run`, `fetch` |
+| `--force`             | Re-download even when a verified binary is already cached      | `run`, `fetch`, `serve` |
+| `--platform <key>`    | Fetch for another platform                                     | `fetch` |
+| `--component <name>`  | Fetch only `sidecar` or `tui`                                  | `fetch` |
+| `--port <n>`          | Sidecar bind port (default `8141`)                             | `serve` |
+
+A flag a command does not read is **refused**, not ignored — `gaia run --port
+9000` exits 2 rather than silently coming up on the default port.
+
+Set `DEBUG=gaia` for download, spawn, and sidecar output on stderr. Diagnostics
+never touch stdout, which the terminal UI owns.
+
+## Where things land
+
+| What            | Path                                     |
+| --------------- | ---------------------------------------- |
+| Agent sidecar   | `~/.gaia/agents/gaia/gaia-agent[.exe]`   |
+| Install record  | `~/.gaia/agents/gaia/.installed`         |
+| Terminal UI     | `~/.gaia/npm-cache/gaia-<version>/gaia-tui[.exe]` |
+
+The sidecar goes into the GAIA daemon's own cache directory on purpose: the daemon
+is what spawns and supervises it, and it does its own SHA-256 check on the way. By
+putting an already-verified binary there we save a second download rather than
+racing one.
+
+The `.installed` record next to it is what the daemon and the terminal UI read to
+know the agent is installed — without it the UI would run the sidecar as its own
+stdio child instead of letting the daemon supervise it. It is rewritten even when
+the binary was already cached, so an install left by an earlier version repairs
+itself the next time you run. A `--platform` fetch stages a binary for a
+*different* machine, so it deliberately leaves no record.
+
+The terminal UI is installed as `gaia-tui`, **never** as `gaia` — a file named
+`gaia` in a cache directory would shadow the `gaia` shim npm puts on your `PATH`.
+
+## Ports
+
+| Service       | Port                              |
+| ------------- | --------------------------------- |
+| Agent sidecar | `8141` on `127.0.0.1`             |
+| GAIA daemon   | assigned at start, recorded in `~/.gaia/host/instance.json` |
+
+Port **4001 is reserved repo-wide** and is refused with an error if you pass it.
+Both services bind loopback only — this agent speaks for your documents and memory
+and has no business on a LAN interface.
+
+## Running the sidecar on its own
+
+`gaia serve` skips the terminal UI and gives you the REST surface directly, for
+integrating GAIA into your own app:
+
+```bash
+npx @amd-gaia/gaia serve --port 8141
+curl http://127.0.0.1:8141/health
+```
+
+It waits for `GET /health`, checks the contract version, and tears the whole
+process tree down on Ctrl+C. See [`SPEC.md`](./SPEC.md) for the endpoints.
+
+The sidecar normally requires a per-session bearer token on `/v1/gaia/*`, but
+neither `serve` nor `startSidecar` mints one, so both leave it in dev mode — the
+token check off, `Host`/`Origin` still enforced. This agent has shell and file
+tools, so before you expose it to anything, supply a token of your own: see
+[`SPEC.md` §5.4](./SPEC.md#54-caller-authentication).
+
+## Programmatic use
+
+```ts
+import { randomUUID } from "node:crypto";
+import { fetchAll, startSidecar, shutdown } from "@amd-gaia/gaia";
+
+const { sidecar } = await fetchAll();               // both binaries, SHA-256 verified
+const proc = await startSidecar({ binaryPath: sidecar.binaryPath });
+
+const sessionId = randomUUID(); // reuse across the whole conversation, see below
+
+const res = await fetch(`${proc.baseUrl}/v1/gaia/query`, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({
+    query: "summarize my notes",
+    run_id: randomUUID(),
+    session_id: sessionId,
+    context: [],
+  }),
+});
+
+await shutdown(proc);
+```
+
+`/v1/gaia/query` streams Server-Sent Events terminated by exactly one `final` or
+`error`. `fetchAll()` also returns the TUI's path if you would rather launch that.
+
+**Reuse the same `session_id` for every turn in a conversation.** It is what
+lets a document you had it index, or a skill you had it load, survive to the
+next question — drop it (or mint a new one per call) and the agent still
+answers, but it forgets everything from the previous turn. See
+[`SPEC.md` §5.2](./SPEC.md#52-session_id-and-agent-retention) for the retry
+and eviction behavior.
+
+Every failure throws a typed error (`IntegrityError`, `PlatformError`,
+`HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`) with a message
+that names what failed and what to do about it.
+
+## Where the binaries come from
+
+The two binaries ship from two different places, and `binaries.lock.json` records a
+version and a source URL for each:
+
+| Binary        | Published as                              | Built by                         |
+| ------------- | ----------------------------------------- | -------------------------------- |
+| Agent sidecar | the `gaia` agent, at this package's version | this package's release           |
+| Terminal UI   | the `terminal-hub` component, at its own version | the core GAIA release       |
+
+The terminal UI is **consumed, not rebuilt**. It is byte-for-byte the `gaia tui`
+binary a core install ships, so there is no second copy that could lag behind or
+behave differently — which is the entire reason it is sourced this way.
+
+## Integrity
+
+`binaries.lock.json` is the single source of truth for what gets downloaded and
+what it must hash to. The release pipeline regenerates it from the artifacts
+actually being served — the sidecars it just published, and the terminal-hub
+artifacts it downloaded and cross-checked against the hub's own recorded hashes.
+
+Between releases the lock carries `PENDING-replace-with-real-sha256` placeholders.
+**A placeholder blocks the fetch outright** — before any network call — so an
+unverifiable binary can never be downloaded, let alone executed. If you need to run
+against a locally built binary, build it yourself and point the lifecycle helpers
+at it directly; the fetcher will not be talked into it.
+
+## Links
+
+- Guide: <https://amd-gaia.ai/docs/guides/gaia>
+- Technical reference: [`SPEC.md`](./SPEC.md)
+- Changes: [`CHANGELOG.md`](./CHANGELOG.md)
+- Issues: <https://github.com/amd/gaia/issues>
+
+MIT licensed. © 2024-2026 Advanced Micro Devices, Inc.