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

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:

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:

{
  "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

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):

  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:

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.15; 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):

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, response } 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:

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:

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:

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:

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:

from gaia_agent.agent import GaiaAgent, GaiaAgentConfig

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