Integrate Gaia

Integrating @amd-gaia/gaia

@amd-gaia/gaia delivers two binaries and owns their process lifecycle: the frozen agent sidecar (gaia-agent) and the Go terminal UI (gaia-tui). It ships no agent logic of its own, and it builds neither binary at install time — both are published artifacts it downloads and verifies. The terminal UI is the published terminal-hub component, the same binary a full GAIA install runs as gaia tui, so its behaviour cannot differ from that one. Everything runs on the local machine against a local model server — nothing you type or index leaves it.

Two ways in:

• npx @amd-gaia/gaia — fetch, verify, launch the terminal UI. What a human runs.
• The programmatic exports — fetch, spawn the sidecar, drive POST /v1/gaia/query yourself. What you use when embedding GAIA in an app.

This file is NOT one of the agent's own skills. It is the integration playbook: how you wire this package into an app. The agent separately loads Agent Skills into its own prompt at runtime from gaia_agent/skills/<name>/SKILL.md. Same filename, different artifact — don't ship this one as an agent skill. See Skills.

1. Install

bashCopy code
npx @amd-gaia/gaia          # no install step; fetches what it needs on first run
npm install @amd-gaia/gaia  # when you want the programmatic exports

The package is ESM-only ("type": "module") and needs Node 18+ for the built-in fetch. Use import, not require; from CommonJS use await import("@amd-gaia/gaia").

@amd-gaia/gaia publishes with this release — it is not on npm yet. Until the release tag lands, npx @amd-gaia/gaia will not resolve. Run the agent from a source checkout in the meantime (see the guide).

2. What npx @amd-gaia/gaia actually does

1. Resolves the host platform key (`${process.platform}-${process.arch}`).
2. Reads binaries.lock.json, the checksum manifest published with this exact package version. Each component records its own hub lane, version, artifact name and hash — they do not share a base URL.
3. Downloads both binaries, each from its own lane, and SHA-256 verifies each against the lock.
4. Installs the sidecar into ~/.gaia/agents/gaia/ and the TUI into ~/.gaia/npm-cache/gaia-<version>/.
5. Writes ~/.gaia/agents/gaia/.installed — the record the daemon and the TUI both read to decide the sidecar is installed. Written on a cache hit too, so an install staged by an earlier release repairs itself.
6. Execs the TUI, whose exit code becomes ours.

run deliberately does not spawn a sidecar. The TUI reaches agents through the GAIA daemon's relay and never holds a sidecar token, and the daemon is what spawns and supervises the sidecar — from exactly the directory step 4 wrote to. A second sidecar started here would only fight the daemon's own for port 8141. Use gaia serve when you want to own the process.

Other commands: gaia fetch (download + verify, print JSON, exit), gaia serve (sidecar alone), gaia version (per-component version, source URL, and platform matrix). Anything after a bare -- goes to the TUI verbatim.

Where each binary comes from

Two things follow from that, and both bite if you assume otherwise:

• The two components version independently. lock.agentVersion is this package's version; components.tui.componentVersion is the terminal-hub release it consumes. They will not match.
• The TUI's artifact names use win-x64 / win-arm64, not win32-*. Platform keys stay in Node's namespace (process.platform says win32); only the filename crosses over. Never build a TUI URL by interpolating a platform key — read filename from the lock entry.

3. The integrity gate — it will stop you, by design

The SHA-256 check is this package's security boundary, and there is no flag, env var, or option that relaxes it.

• Bytes are hashed in memory and compared before anything is written to the cache path. A mismatch raises IntegrityError naming expected vs actual and leaves nothing on disk.
• A placeholder hash blocks the fetch before any network call — between releases every sha256 in the lock is PENDING-replace-with-real-sha256, and a value that is all zeros or contains PENDING (case-insensitive) is treated as a placeholder. You get a PlatformError, not a download.
• A cache hit re-hashes the on-disk file. A cached binary whose bytes drifted is re-downloaded, not reused.

If you need to run against a locally built binary, build it and point startSidecar / runTui at it directly. The fetcher will not be talked into it.

4. Platform coverage — the sidecar has two gaps

terminal-hub publishes the TUI for all six targets. The sidecar is a PyInstaller freeze built on the platform it targets, and there is no arm64 Linux and no arm64 Windows sidecar build.

Resolving the sidecar on those two keys raises PlatformError naming the platform and the supported set. It is not silently skipped, and the TUI is never launched with no agent behind it. npx @amd-gaia/gaia version prints the matrix for the version you have.

5. Prerequisite — a local Lemonade server

The agent thinks with a model hosted by Lemonade Server, which this package does not install. Required before any query succeeds:

1. Lemonade 10.2.0 or newer, running. GAIA's daemon starts and supervises one, so gaia daemon start is normally all that is needed (gaia init also installs and starts it on first run). Qwen3.8 Flash Next needs v2026.39.1 or newer, the version gaia init installs; older servers cannot load it.
2. The machine's default chat model downloaded — run gaia init. It picks Qwen3.6-35B-A3B-GGUF where a GPU holds it (~27 GB for models, weights plus context cache — a 64 GB+ Strix Halo or a 32 GB GPU) and Gemma-4-E4B-it-GGUF everywhere else, CPU-only PCs included, and records the pick as default_model in ~/.gaia/config.json. On 128 GB-class PCs the user may switch to the multimodal user.Qwen3.8-Flash-Next-GGUF with gaia config set default_model. model.id below names whichever this machine uses. gaia download takes no model argument — naming one makes it exit 2. To pull a single model instead, repeat the command GET /v1/gaia/init gives you: it names the Lemonade client this machine actually has. Do not invent one.

Do not guess — ask the sidecar. GET /v1/gaia/init is a read-only preflight (it never pulls or loads) that probes Lemonade, compares its version to the floor, and checks the model is present:

bashCopy code
curl -s http://127.0.0.1:8141/v1/gaia/init

It answers 200 when ready and 503 when not, with the same body shape either way — so branch on .ready and render .hint, never on the status code alone:

jsoncCopy code
{
  "ready": false,
  "lemonade": { "reachable": false, "base_url": "…", "version": null,
                "min_version": "10.2.0", "compatible": null },
  "model":    { "id": "Gemma-4-E4B-it-GGUF", "present": false,
                "loadable": null, "ctx_size": null },
  // The manual fallback ("Otherwise: …") is resolved for the host's Lemonade
  // install (tray app, macOS app, systemd service, or CLI) — render it verbatim.
  "hint": "Local Lemonade Server is not reachable at …. GAIA starts it automatically — run `gaia daemon start` if the background service is not running. Otherwise: Start the Lemonade app from Applications, then retry. Or set LEMONADE_BASE_URL to a running server. See https://amd-gaia.ai/docs/guides/gaia."
}

lemonade.compatible: null is indeterminate, not a pass — the version could not be parsed. Render it as unknown.

GET /health is liveness only. A green /health means the REST surface is up; it says nothing about whether a query will work.

6. Start the sidecar

tsCopy code
import { fetchAll, startSidecar, shutdown } from "@amd-gaia/gaia";

// Fetch + SHA-256 verify both binaries. Build step, not per request.
const { sidecar, tui } = await fetchAll();

// Spawn -> poll /health -> check the contract apiVersion, in one call.
const proc = await startSidecar({ binaryPath: sidecar.binaryPath });  // port 8141

// ... drive proc.baseUrl ...

await shutdown(proc);   // tree-kill; auto-cleanup also reaps on exit

• fetchAll(opts?) returns { sidecar, tui, lock }. Each result carries binaryPath, platformKey, sha256, cached, url. For one component use fetchBinary({ component: "sidecar" | "tui", outDir }).

• startSidecar throws if the binary can't start, never becomes healthy (HealthTimeoutError, 60 s default — a cold one-file build unpacks first), or reports an apiVersion whose major differs from this package's (VersionMismatchError). On any failure it shuts the sidecar down before rethrowing, so a failed start never leaks a process.

• Tree-kill is not optional. The frozen sidecar spawns a child uvicorn process that child.kill() on the parent does not reap, which leaves port 8141 bound. shutdown kills the group (POSIX SIGTERM to -pid, escalating to SIGKILL; Windows taskkill /T /F). autoCleanup (default true) also reaps on exit, SIGINT/SIGTERM/SIGHUP, uncaughtException, and unhandledRejection. A SIGKILL of your process is the one case nothing in-process can catch.

• Mint a caller token, or you are running the sidecar unauthenticated. The sidecar requires Authorization: Bearer <token> on every /v1/gaia/* request, and skips the check only when neither token env var is set — dev mode, which is what startSidecar gives you, because this package mints nothing. Loopback binding is not the boundary: this agent has shell and file tools. Mint your own and pass it through the env option (StartOptions extends SpawnOptions, so it merges over process.env):

  tsCopy code
  import { randomBytes } from "node:crypto";
  const token = randomBytes(32).toString("hex");
  const proc = await startSidecar({
    binaryPath: sidecar.binaryPath,
    env: { GAIA_GAIA_SIDECAR_TOKEN: token },   // or ..._TOKEN_FILE, a 0600 path
  });
  

  Then send authorization: "Bearer " + token on every /v1/gaia/* call. /health, /version, and /v1/gaia/version are exempt, so startSidecar's own health-and-version handshake works either way. If you did not spawn the sidecar — you are talking to one the GAIA daemon started — the token is the daemon's, delivered to the sidecar as GAIA_GAIA_SIDECAR_TOKEN_FILE (a 0600 file path); read it from there, don't invent one. A 401 whose detail names both env vars means you sent the wrong token or none.

  The programs the agent starts (shell commands, MCP servers, CLI installs and sign-ins, native hub agents, media tools) never inherit this token or GAIA's other internal credentials. To withhold your own variables from them too, list the names in GAIA_CHILD_ENV_DENY (comma or space separated); GAIA_NO_DOTENV=1 stops the sidecar loading .env files.

Or skip the code entirely and let the CLI own it:

bashCopy code
npx @amd-gaia/gaia serve --port 8141
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.17; 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):

tsCopy code
import { randomUUID } from "node:crypto";

const runId = randomUUID();
const res = await fetch(`${proc.baseUrl}/v1/gaia/query`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "text/event-stream",
    authorization: `Bearer ${token}`,   // required unless the sidecar is in dev mode — §6
  },
  body: JSON.stringify({
    query: "Summarize the PDFs in ~/Documents/reports",
    run_id: runId,
    context: [],
    session_id: "s1",
    can_answer_questions: false,
  }),
});

const reader = res.body!.getReader();
const dec = new TextDecoder();
let buf = "";
outer: for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  let i: number;
  while ((i = buf.indexOf("\n\n")) >= 0) {
    const frame = buf.slice(0, i);
    buf = buf.slice(i + 2);
    const line = frame.split("\n").find((l) => l.startsWith("data: "));
    if (!line) continue;                  // ":" frames are keepalive comments
    const ev = JSON.parse(line.slice(6));
    switch (ev.type) {
      case "status":      console.log(ev.message); break;
      case "token":       process.stdout.write(ev.delta); break;
      case "tool_call":   console.log(`→ ${ev.tool}`, ev.args); break;
      case "tool_result": console.log(`← ${ev.tool}`, ev.data); break;
      case "needs_confirmation": break;   // see §8 — a refusal follows
      case "needs_input": /* answer it — see below */ break;
      case "final":       console.log(ev.answer); break outer;   // terminal
      case "error":       console.error(ev.detail); break outer; // terminal
      default:            console.warn("unsupported event", ev); // future additive type
    }
  }
}

The canonical event shapes, as emitted:

Rules a client must respect:

• An idle run emits : keepalive SSE comments every 10 s. Skip lines that aren't data: and reset your read-idle timer on them — a long tool call is not a dead stream.
• Never treat stream close without a terminal event as success. The server guarantees one; a close without one means something broke on your side.
• Answer needs_input, don't restart. The run is parked on the same stream. POST /v1/gaia/query/{run_id}/respond with { request_id, value } and keep reading the existing stream — a fresh /query POST abandons the paused run. Unknown run → 404; a request_id that is no longer pending → 409 (both loud, never a silent drop). Render each option's description, and mask the input when sensitive is set.
• Cancel with POST /v1/gaia/query/{run_id}/cancel. It returns { run_id, cancelled } — an unknown id reports cancelled: false with a 200, not a 404, because a cancel racing a normal completion is expected. Dropping the HTTP connection also cancels the run.
• Add to a running turn with POST /v1/gaia/query/{run_id}/followup (contract ≥ 2.15, body { text }). The run is not interrupted and no second turn starts: the agent folds the text in at its next step boundary and answers it alongside what it was already doing. Unknown run → 404, an agent that cannot take one → 409; both are loud, so hold the message rather than telling the user it was sent. /query is stateless, so put a delivered follow-up into the next turn's context yourself, between that turn's question and its answer.

8. Over /v1/gaia/query, a gated tool asks — when you can answer

Read this before you design a workflow around it. This section is about the HTTP surface — the agent's other transport can collect an approval; see SPEC §5.5.

Twelve of the agent's 95 tools mutate the machine and need explicit approval before they run. Nine sit in the base TOOLS_REQUIRING_CONFIRMATION set — write_file, edit_file, run_shell_command, wait_for_condition, which re-runs a shell command until it succeeds, execute_python_file, run_python, notify_desktop, which spawns a PowerShell child on Windows to draw the notification, and install_cli / sign_in_cli, which install software and sign a CLI in to the user's account — and the flagship adds three of its own (CONFIRMATION_REQUIRED_TOOLS): install_skill, capture_skill, and remove_skill, because installing or capturing a skill writes third-party content under ~/.gaia/skills and removing one deletes it. A capture that does land is additionally code-inert: its instructions load, but any tools.py/scripts stay unregistered until a human runs gaia skill promote <name> in a terminal. Everything else — reading, indexing, querying, web fetching, memory, and the read-only check_cli_setup — runs without asking.

The eight live-browser tools are gated by a hook, not a set, so a name alone does not tell you whether a call will ask. browser_login always asks. browser_click / browser_type ask when the call acts inside a session the run signed in to, or when the target element's label reads irreversible, and run unasked on the open web. The hook fails closed: if the browser cannot be asked what state it is in, the call is treated as authenticated and prompts. Design a workflow around the approval path, not around a fixed tool list.

Contract ≥ 2.14 can answer one. Send a session_id and leave can_answer_questions unset (or true). The stream emits needs_confirmation carrying a confirm_id and then stays open while the agent waits:

Copy code
data: {"type":"needs_confirmation","run_id":"…","action":"run_shell_command","summary":"python -m pytest -q tests/","confirm_id":"…","always_scope":"pytest","risk":"execute"}

Answer it on the same run, then keep reading the stream:

Copy code
POST /v1/gaia/query/{run_id}/tool_decision
{ "decision": "allow" | "deny" | "always" | "timeout", "confirm_id": "…" }

summary is the command or call itself, shown once — your UI supplies the question. risk says what the call does (read, write, execute, destructive); label by it rather than by tool name, since run_shell_command is pytest on one call and rm -rf on the next. always grants the family named in always_scope for the rest of the session (pytest covers every spelling of a test run) — say so in your UI, because it stops asking; no always_scope means don't offer it. If your prompt expires unanswered, send timeout, not deny: it still refuses, but the agent tells the user the request timed out instead of claiming they said no. Unknown run → 404; a prompt that is no longer pending → 409; any other decision → 422. All loud, never a silent drop. Send confirm_id: without it a late answer resolves whichever prompt replaced the one it was typed against.

To stop being asked for a whole session:

Copy code
POST /v1/gaia/sessions/{session_id}/bypass
{ "enabled": true }

It applies to the very next gated tool, including one in a turn already running, and an unknown session is a 404 rather than a new one. A malformed session_id is a 400, same as on /query.

That bypass stops the prompts; it does not open the shell. The stdio transport's --bypass-permissions does both — it runs gated tools unasked and lifts the shell tool's guardrails (redirection and the other shell-only operators, the read-only binary allowlist, the rate limit). That second half is arbitrary code execution, appropriate for one local parent on a private pipe and not for a bound socket, so it stays on stdio: HTTP sessions never lift the shell gates, and the request body rejects unknown fields so a client cannot ask. See SPEC §5.5.

A run nobody can answer is still refused. With can_answer_questions: false, or with no session_id, the server emits needs_confirmation, follows it immediately with a terminal final saying it stopped before running the action, and cancels the run:

Copy code
data: {"type":"final","answer":"I stopped before running 'write_file' because it needs your explicit approval, and this streaming surface cannot collect that yet. …"}

That is deny-by-default, not an oversight: parking a batch run on a prompt nobody will ever see reads as a hang. So a one-shot integration cannot run those nine tools — pass a session_id and answer, or perform the mutation from your own code and let the agent do the reading and reasoning.

9. File-access scope

The agent's file, document, and data tools are confined to a set of allowed paths, and the default is the user's home directory. That is the honest scope for a personal document agent, and it is still a real boundary — system directories, program files, and other users' homes are refused, with the check run against the resolved path so a symlink out of scope doesn't slip through.

Being in scope is not the same as being safe, and two denylists apply inside it. Reads refuse secrets — .env, id_rsa, credentials.json, .netrc, .pem/.key, and everything under ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube — even in an allowed directory. Writes additionally refuse anything that executes on its own: shell startup files, PowerShell profiles, ~/.config/autostart/*, systemd user units, LaunchAgents, and a repo's .git/ (hooks and config). Both come back as a structured error naming the file and the reason, so do not plan an integration around reading a credential file or editing a shell rc — perform those from your own code.

The agent also gets its own scratch directory for throwaway scripts and intermediate files, so they stay out of the user's project. It is created per agent under the system temp dir, deleted when the agent closes, and is the only part of the temp dir the agent may use.

In 0.1.1 narrowing it is a construction-time setting only. The packaged sidecar exposes no flag or env var for allowed_paths (its CLI accepts only --host and --port), so restricting the scope means embedding GaiaAgent in your own Python process:

pythonCopy code
from gaia_agent.agent import GaiaAgent, GaiaAgentConfig

agent = GaiaAgent(config=GaiaAgentConfig(allowed_paths=["/home/me/Documents"]))

10. Skills — one always-on, the rest opt-in

The agent is built to host Agent Skills (short playbooks loaded into its own prompt, grouped into named sets, one set active per launch), and its bundled skill directory is the highest-precedence discovery root.

Loaded skills are not all resident every turn: each turn the agent embeds the query against every loaded skill's description and renders only the matching bodies in full — the rest collapse to a one-line menu entry, and the model (or the user) re-activates one by calling load_skill on it again. GAIA_DYNAMIC_SKILLS=0 disables the per-turn selection (every loaded body renders every turn); GAIA_DYNAMIC_SKILLS_TAU=<float> overrides the match threshold. Manifest skills: entries are always-on and never collapse, and a turn with only always-on skills loaded embeds nothing. If the embedder is unavailable, selection disables itself for the session and every body renders — capability is never silently lost to a failed match.

One skill ships enabled: gaia-voice. It is a manifest skills: entry, so it is always on, always rendered in full, and paid on every LLM call of every turn — budget for it. It is not a task recipe but the agent's honesty floor: do not claim work you did not do, do not present empty output as a result, do not substitute a near-miss and report success. Those failures corrupt an answer whatever the task is, which is why it cannot live in an opt-in bundle. It declares no tools, and its body measures 790 tokens (tiktoken cl100k).

document-extract ships bundled but not enabled. gaia-voice routes a request for every item in a document to it, and it drives extract_document_items and save_extracted_items so a long transcript yields a complete, source-quoted inventory rather than a summary. A skill turns that inventorying on only by listing extract_document_items in tools_required; wording such as "find every call site" in another skill does not.

No skill set loads. gaia-agent.yaml ships its skill_sets: and default_skill_set: blocks commented out — following the email agent's precedent, because loading several skill bodies into every prompt costs tokens and no eval has measured that trade for this agent yet. Re-enabling is uncommenting two blocks; no code change.

So today there is nothing for GAIA_SKILL_SET to select — leave it unset; any value stops the agent at startup (the sidecar exits non-zero before binding its port). Once a release declares sets, GAIA_SKILL_SET is the selection channel for the packaged sidecar (its CLI accepts only --host and --port), and an undeclared name stops startup naming the valid sets rather than falling back to a default. Beyond gaia-voice, do not design around a skill being on by default.

11. The project map — two things it costs you

When the agent's working directory is a code repository, every task starts with a project map in the system prompt: the root, the directory shape, the likely entry points, which commands are installed, and the three platform differences that change command syntax. It exists so the agent stops burning round trips on "no such file" and "command not found".

Two consequences an integrator needs to plan for:

• Up to 600 prompt tokens, every turn. That is the enforced ceiling (1.8% of the NPU profile's 32K window), not a typical value — budget it alongside gaia-voice's 790.
• An embedding pass on the first semantic code search. If the repo has no 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.

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 GaiaAgentConfig(project_root=...) when embedding. A directory that is neither a VCS checkout nor holds a recognised manifest gets no map — that is the designed answer, not a failure.

The same root check also decides whether the shell rides along: when it resolves to a repository, run_shell_command is offered on every turn instead of only when semantic selection guesses the request sounds like a shell request. No repository, no change.

12. Ports

Port 4001 is reserved repo-wide: spawnSidecar throws a RangeError and gaia serve --port 4001 exits 2. Both services bind loopback only — this agent speaks for the user's documents and memory and has no business on a LAN interface.

13. Running in a server or long-lived app

• fetchAll / fetchBinary are a build step, not per request — network plus a full SHA-256 hash of a large artifact. Run once at install time.
• resolveSidecarPath / resolveTuiPath are startup, not per request. They re-hash the binary against binaries.lock.json before handing back a path that gets spawned, so they cost a full read of a large file. Resolve once and keep the path. { verify: false } skips the check for a binary you built yourself.
• Spawn once at boot and hold the Sidecar handle for the process lifetime. Never per request.
• Low concurrency. One local Lemonade model slot, so parallel queries serialize. Cap inflight runs.
• The package does not restart a crashed sidecar. It reaps one; supervision is the daemon's job (or yours).
• DEBUG=gaia puts download, spawn, and sidecar output on stderr. stdout belongs to the TUI once exec'd, and to machine-readable JSON for fetch / version — never write diagnostics there.

Every failure throws a typed error extending GaiaError, so instanceof GaiaError catches any of ours: IntegrityError, PlatformError, HealthTimeoutError, VersionMismatchError, BinaryNotFoundError, HttpError. There is no silent null.

Gotchas — read before debugging

• /health green ≠ ready. It never touches the model server. Use GET /v1/gaia/init and branch on .ready; it returns 503 with a full body and a hint, not an empty error.
• A terminal error whose detail starts "Local Lemonade Server is not reachable" means Lemonade isn't running or isn't reachable — not a bug in this package. Start it, or set LEMONADE_BASE_URL.
• needs_confirmation is followed by a refusal and the run ends. See §8. The nine gated tools are unreachable over /query — the agent itself can run them on a transport that can prompt (SPEC §5.5).
• A placeholder hash in binaries.lock.json blocks the fetch before any network call. Between releases that is the expected state — it is not a broken install, and there is no override.
• No linux-arm64 / win32-arm64 sidecar. The TUI has both. A PlatformError on those hosts is the design, not a missing artifact.
• A 401 from /v1/gaia/* is the caller-auth token, not a bug. The sidecar requires Authorization: Bearer <token>; /health, /version, and /v1/gaia/version are exempt, which is why a green health check sits happily in front of a 401 on /query. It skips the check only in dev mode — neither token env var set — which is what spawnSidecar and gaia serve produce, because this package mints nothing. Do not treat loopback binding as the boundary; mint a token and pass it (§6).
• run_id must be a UUID, and unknown fields in the request body are a 422 — the model forbids extras. Typos don't get ignored.
• gaia run needs the Python gaia CLI on PATH — the TUI shells out to it to start the daemon. So the TUI doesn't re-invoke our own npm shim, the child's PATH is rewritten: a directory holding nothing but our shim (an npx 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.0+: 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 is called gaia-<platform>, and a file named gaia in a cache directory would shadow the npm bin shim. The lock's filename and executable differ for that reason. Don't rename it back.
• The TUI comes from a lane this package doesn't publish. If a fetch 404s on the TUI but not the sidecar, the pinned terminal-hub version is the thing to check — gaia version prints it and its base URL.
• ESM-only. require("@amd-gaia/gaia") fails; use import or dynamic import().

Verify the integration

Green path, in order:

bashCopy code
npx @amd-gaia/gaia version          # per-component version + source URL + matrix
npx @amd-gaia/gaia fetch            # JSON: one entry per binary with its sha256
npx @amd-gaia/gaia serve --port 8141

Against a lock that still carries PENDING-… hashes, fetch is expected to fail with a PlatformError before any download — that is the gate working, not a broken install. Only a published release has real hashes.

Then, in another terminal:

bashCopy code
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.17","agentVersion":"0.1.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' \
  -d '{"query":"What can you do?","run_id":"00000000-0000-4000-8000-000000000001","context":[],"can_answer_questions":false}'

A healthy run streams status / token events and ends with one final. If /v1/gaia/init is 503, fix what its hint names and retry — the rest of your integration is fine.

That /query call carries no Authorization header because gaia serve starts the sidecar in dev mode. Against one started with a token, add -H "authorization: Bearer $TOKEN" — a 401 here and a green /health is that and nothing else (§6).

A 503 from /query itself is a different condition: every retained session slot is busy and none is idle enough to evict (SPEC §5.2). Do NOT loop on /v1/gaia/init — it will report ready. Wait for a running turn to finish (or close an idle session) and retry the same /query.

Three more refusals are yours to avoid, each naming its fix in detail (SPEC §5.2 has the reasoning):

• 409 — the run_id is still in flight. You mint it, so mint a fresh UUID per request; reusing one would leave the earlier run with no way to be cancelled.
• 409 — the model switch itself failed (a missing Claude credential, an unknown local model). The session stays on its previous model, so this is a failed request rather than a broken session; detail names the reason.
• 400 — the Host header is absent or empty. The loopback check fails closed, so omitting the header is refused rather than served. Send Host: 127.0.0.1:<port>; every real HTTP client already does.

After cancelling a turn, send the next /query on that session straight away. It is held until the stopped turn's model call returns (up to 240 s), then runs. A session whose running turn was NOT cancelled still answers 409.

For the full wire contract, lock schema, exit codes, and timeout table, see SPEC.md. For the user-facing overview, see README.md and https://amd-gaia.ai/docs/guides/gaia.

TUI inference providers

The stdio TUI supports /provider for Local, Fireworks AI, and AMD LLM Gateway. Keys are entered in a masked field and sent directly to local Lemonade's runtime auth API, never as agent queries. /model lists supported discovered cloud and downloaded local models; /model fireworks.gemma-4-31b-it selects Gemma 4 31B IT when available. Cloud chat sends conversation history to the selected provider; embeddings remain on Lemonade. The status event names the actual provider and marks remote inference. This is a TUI/stdio capability, not an HTTP query command.

Developer engineering mode

Available only when GAIA was started with --developer-mode (or GAIA_DEVELOPER_MODE=1). If the engineering tools are missing, say that developer mode is off; don't route around it with shell or file tools. When describing a handoff, claim only what happened:

• Context was shared only after the user approved that exact snapshot in the prompt. Approval can't be remembered, so each share or append asks again.
• Opening the coding app never creates or submits a task, and for Codex it doesn't prefill a prompt either. Never say the context was "posted" or "sent" to Codex; give the user the directory and the prompt to paste.
• Preview and test results come from the coding app. Report them as app-reported, not as checks GAIA ran.
• Revoking stops future reads; it cannot recall data already delivered.

See the usage guide.