@amd-gaia/gaia 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# 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.
+
+### Added
+
+- **`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.
+- **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).
+- **`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.
+
+### 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 on `PATH` for the daemon the TUI starts.
+- 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` 0.1.1 has no caller-auth token, so unlike
+  `@amd-gaia/agent-email` this package mints and sends none.
+- 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,202 @@
-# @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.0` 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.
+Everything runs locally on your machine; nothing you type or index leaves it.
+
+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 on `PATH` for the daemon the terminal UI starts. 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                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `--base-url <url>`    | Override the download base URL from `binaries.lock.json`       |
+| `--cache-dir <dir>`   | Where to cache the terminal UI binary                          |
+| `--sidecar-dir <dir>` | Where to install the agent sidecar (default `~/.gaia/agents/gaia`) |
+| `--platform <key>`    | Fetch for another platform (`fetch` only)                      |
+| `--force`             | Re-download even when a verified binary is already cached      |
+| `--port <n>`          | Sidecar bind port for `serve` (default `8141`)                 |
+
+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]`   |
+| 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 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.
+
+## 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.