@amd-gaia/gaia 0.0.0 → 0.1.1

package/dist/cli.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * `gaia` — the one command that gets you running.
+ *
+ *   npx @amd-gaia/gaia                 fetch + verify both binaries, then launch the TUI
+ *   npx @amd-gaia/gaia fetch           fetch + verify only
+ *   npx @amd-gaia/gaia serve           run the agent sidecar alone (REST, no TUI)
+ *   npx @amd-gaia/gaia version         print the lock manifest
+ *
+ * Every download is SHA-256 verified against `binaries.lock.json` before it is
+ * written, and a mismatch or a placeholder hash aborts the run. There is no
+ * "continue anyway" path.
+ */
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { GaiaError } from "./errors.js";
+import { daemonSidecarCacheDir, defaultCacheDir, fetchAll, fetchBinary, } from "./fetch.js";
+import { DEFAULT_PORT, RESERVED_PORT, runTui, shutdown, startSidecar, } from "./lifecycle.js";
+import { COMPONENTS, componentBaseUrl, componentLock, currentPlatformKey, loadLock, platformsFor, } from "./platform.js";
+// Flags that consume a value. Being explicit avoids the footgun where
+// `--base-url --force` silently swallows the next flag as a value.
+const VALUE_FLAGS = new Set([
+    "base-url",
+    "platform",
+    "port",
+    "cache-dir",
+    "sidecar-dir",
+    "component",
+]);
+/** Raised for a malformed command line; the caller turns it into exit 2. */
+export class UsageError extends Error {
+}
+export function parseArgs(argv) {
+    const out = { _: [], flags: {}, passthrough: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            out.passthrough = argv.slice(i + 1);
+            break;
+        }
+        if (a.startsWith("--")) {
+            // Both `--flag value` and `--flag=value` — dropping the second silently
+            // would download from the default hub after the user pointed us elsewhere.
+            const eq = a.indexOf("=");
+            const key = eq === -1 ? a.slice(2) : a.slice(2, eq);
+            const inline = eq === -1 ? undefined : a.slice(eq + 1);
+            if (VALUE_FLAGS.has(key)) {
+                if (inline !== undefined) {
+                    if (inline === "")
+                        throw new UsageError(`--${key} was given an empty value`);
+                    out.flags[key] = inline;
+                    continue;
+                }
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith("--")) {
+                    throw new UsageError(`--${key} expects a value`);
+                }
+                out.flags[key] = next;
+                i++;
+            }
+            else {
+                if (inline !== undefined) {
+                    throw new UsageError(`--${key} does not take a value (got '${a}')`);
+                }
+                out.flags[key] = true;
+            }
+        }
+        else if (a === "-h") {
+            out.flags["help"] = true;
+        }
+        else {
+            out._.push(a);
+        }
+    }
+    return out;
+}
+const HELP = `@amd-gaia/gaia — run GAIA locally on AMD Ryzen AI
+
+Usage:
+  gaia [run] [options] [-- <tui args>]   Fetch + verify both binaries, then launch the TUI
+  gaia fetch [options]                   Download + SHA-256 verify the binaries only
+  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 this help
+
+run options:
+  --base-url <url>     Override the per-component download base URL from
+                       binaries.lock.json (applies to every component fetched)
+  --cache-dir <dir>    Where to cache the TUI binary
+  --sidecar-dir <dir>  Where to install the agent sidecar
+                       (default ~/.gaia/agents/gaia — the daemon's own cache)
+  --force              Re-download even when a verified binary is already cached
+  -- <tui args>        Forward everything after \`--\` to gaia-tui verbatim
+
+fetch options:
+  --component <name>   Fetch only one of: ${COMPONENTS.join(", ")} (default: both)
+  --platform <key>     Override the platform key (e.g. linux-x64). Default: this host
+  plus every run option above.
+
+serve options:
+  --port <n>           Bind port (default ${DEFAULT_PORT}; ${RESERVED_PORT} is reserved and refused)
+
+Notes:
+  * No binaries are committed to the repo. Every download is SHA-256 verified
+    against binaries.lock.json and FAILS LOUDLY on any mismatch.
+  * A placeholder hash in the lock blocks the fetch outright, so an unverifiable
+    binary can never be trusted.
+  * The agent sidecar has no arm64 Linux or arm64 Windows build; the TUI does.
+    \`gaia version\` prints the exact per-component platform matrix.
+  * The TUI is the published \`terminal-hub\` component — byte-identical to the
+    \`gaia tui\` a core install runs, so its behaviour cannot drift from it.
+  * Set DEBUG=gaia for download, spawn, and sidecar output on stderr.
+`;
+const flagStr = (args, k) => typeof args.flags[k] === "string" ? args.flags[k] : undefined;
+/**
+ * Shared download options. `--platform` is accepted only by `fetch`: `run` and
+ * `serve` execute what they download, and honouring a foreign platform there
+ * would write a wrong-architecture binary into the daemon's cache and then try
+ * to spawn it.
+ */
+function downloadOptions(args, allowPlatform = false) {
+    const platformKey = flagStr(args, "platform");
+    if (platformKey !== undefined && !allowPlatform) {
+        throw new UsageError("--platform is only valid for `gaia fetch`. `run` and `serve` execute the " +
+            `binary, so it must be built for this host (${currentPlatformKey()}).`);
+    }
+    return {
+        baseUrl: flagStr(args, "base-url"),
+        ...(allowPlatform && platformKey !== undefined ? { platformKey } : {}),
+        force: Boolean(args.flags["force"]),
+        tuiDir: flagStr(args, "cache-dir"),
+        sidecarDir: flagStr(args, "sidecar-dir"),
+    };
+}
+/**
+ * The child's PATH with this package's own bin directory removed.
+ *
+ * npm installs our shim as `gaia`, and the TUI starts the daemon by resolving
+ * `gaia` on PATH (tui/internal/daemon/client.go) expecting the *Python* CLI.
+ * Left alone, the TUI would re-invoke us with `daemon start` and the daemon would
+ * never come up. Returns undefined when PATH is unset.
+ */
+export function pathWithoutOwnShim(rawPath = process.env["PATH"], argv1 = process.argv[1]) {
+    if (rawPath === undefined || !argv1)
+        return rawPath;
+    const sep = process.platform === "win32" ? ";" : ":";
+    let ownBinDir;
+    try {
+        ownBinDir = path.resolve(path.dirname(argv1));
+    }
+    catch {
+        return rawPath;
+    }
+    const same = (dir) => {
+        const resolved = path.resolve(dir);
+        return process.platform === "win32"
+            ? resolved.toLowerCase() === ownBinDir.toLowerCase()
+            : resolved === ownBinDir;
+    };
+    return rawPath
+        .split(sep)
+        .filter((d) => d !== "" && !same(d))
+        .join(sep);
+}
+/** Validate `--port`. Rejects out-of-range values and the reserved port. */
+export function resolvePort(raw) {
+    const port = typeof raw === "string" ? Number(raw) : DEFAULT_PORT;
+    if (!Number.isInteger(port) || port <= 0 || port > 65535 || port === RESERVED_PORT) {
+        return {
+            error: `--port must be a port in 1..65535 and not ${RESERVED_PORT} (got ${String(raw)})`,
+        };
+    }
+    return { port };
+}
+async function cmdRun(args) {
+    const opts = downloadOptions(args);
+    process.stderr.write("[gaia] fetching and verifying the agent sidecar and the terminal UI ...\n");
+    const { sidecar, tui } = await fetchAll(opts);
+    process.stderr.write(`[gaia] sidecar ${sidecar.cached ? "cached" : "installed"} -> ${sidecar.binaryPath}\n` +
+        `[gaia] tui     ${tui.cached ? "cached" : "installed"} -> ${tui.binaryPath}\n` +
+        "[gaia] starting the terminal UI ...\n");
+    // The TUI owns the daemon handshake and the daemon owns the sidecar process —
+    // the TUI never holds a sidecar bearer token, so starting one here would only
+    // fight it for the port. Our job is to put a *verified* binary where the daemon
+    // looks, which fetchAll just did.
+    const childPath = pathWithoutOwnShim();
+    return runTui({
+        binaryPath: tui.binaryPath,
+        args: args.passthrough,
+        env: childPath === undefined ? {} : { PATH: childPath, Path: childPath },
+    });
+}
+async function cmdFetch(args) {
+    const opts = downloadOptions(args, true);
+    const only = args.flags["component"];
+    const results = [];
+    if (typeof only === "string") {
+        if (!COMPONENTS.includes(only)) {
+            throw new UsageError(`unknown --component '${only}'; expected one of ${COMPONENTS.join(", ")}`);
+        }
+        const component = only;
+        const lock = loadLock();
+        results.push(await fetchBinary({
+            component,
+            lock,
+            outDir: component === "sidecar"
+                ? (opts.sidecarDir ?? daemonSidecarCacheDir())
+                : (opts.tuiDir ?? defaultCacheDir(lock.agentVersion)),
+            baseUrl: opts.baseUrl,
+            platformKey: opts.platformKey,
+            force: opts.force,
+        }));
+    }
+    else {
+        const all = await fetchAll(opts);
+        results.push(all.sidecar, all.tui);
+    }
+    process.stdout.write(JSON.stringify({
+        ok: true,
+        binaries: results.map((r) => ({
+            component: r.component,
+            binaryPath: r.binaryPath,
+            platform: r.platformKey,
+            sha256: r.sha256,
+            cached: r.cached,
+            url: r.url,
+        })),
+    }, null, 2) + "\n");
+    return 0;
+}
+async function cmdServe(args) {
+    const parsed = resolvePort(args.flags["port"]);
+    if ("error" in parsed) {
+        process.stderr.write(`error: ${parsed.error}\n`);
+        return 2;
+    }
+    const { port } = parsed;
+    const opts = downloadOptions(args);
+    process.stderr.write("[gaia] fetching and verifying the agent sidecar ...\n");
+    const result = await fetchBinary({
+        component: "sidecar",
+        outDir: opts.sidecarDir ?? daemonSidecarCacheDir(),
+        baseUrl: opts.baseUrl,
+        force: opts.force,
+    });
+    // We own the lifecycle here (autoCleanup off) so the graceful shutdown below
+    // actually runs; the default auto-reaper would SIGKILL the tree first.
+    const sidecar = await startSidecar({
+        binaryPath: result.binaryPath,
+        port,
+        autoCleanup: false,
+    });
+    try {
+        process.stdout.write(`\n  ▸ GAIA agent: ${sidecar.baseUrl}/v1/gaia/query\n`);
+        process.stdout.write(`    Health:     ${sidecar.baseUrl}/health\n`);
+        process.stdout.write("    Lemonade must be running for live queries. Ctrl+C to stop.\n\n");
+        await new Promise((resolve) => {
+            let stopping = false;
+            const stop = () => {
+                if (stopping)
+                    return; // a second signal must not re-enter shutdown
+                stopping = true;
+                process.stderr.write("\n[gaia] stopping the sidecar ...\n");
+                void shutdown(sidecar).catch(() => undefined).finally(resolve);
+            };
+            // process.on, not once: a second Ctrl+C during the shutdown would
+            // otherwise hit Node's default disposition and kill us mid-teardown,
+            // orphaning the detached sidecar tree on port 8141. The `stopping` guard
+            // absorbs the repeats.
+            for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+                process.on(sig, stop);
+        });
+        return 0;
+    }
+    catch (e) {
+        await shutdown(sidecar).catch(() => undefined);
+        throw e;
+    }
+}
+function cmdVersion() {
+    const lock = loadLock();
+    process.stdout.write(JSON.stringify({
+        agentVersion: lock.agentVersion,
+        schemaVersion: lock.schemaVersion,
+        currentPlatform: currentPlatformKey(),
+        // Per component: each ships from its own hub lane at its own version.
+        components: Object.fromEntries(COMPONENTS.map((c) => [
+            c,
+            {
+                componentVersion: componentLock(lock, c).componentVersion,
+                baseUrl: componentBaseUrl(lock, c),
+                platforms: platformsFor(lock, c),
+            },
+        ])),
+    }, null, 2) + "\n");
+    return 0;
+}
+const KNOWN_COMMANDS = ["run", "fetch", "serve", "version", "help"];
+export async function main(argv) {
+    const args = parseArgs(argv);
+    const explicit = args._[0];
+    const cmd = explicit ?? (args.flags["help"] ? "help" : "run");
+    if (args.flags["help"] && cmd !== "help") {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (!KNOWN_COMMANDS.includes(cmd)) {
+        throw new UsageError(`unknown command '${cmd}'`);
+    }
+    // A dropped positional means a mistyped invocation whose flags may also be
+    // wrong; refuse rather than run something the user did not ask for.
+    const extra = explicit === undefined ? args._ : args._.slice(1);
+    if (extra.length > 0) {
+        throw new UsageError(`unexpected argument${extra.length > 1 ? "s" : ""} ${extra.map((a) => `'${a}'`).join(", ")}. ` +
+            "Arguments for the terminal UI go after a bare `--`.");
+    }
+    switch (cmd) {
+        case "run":
+            return cmdRun(args);
+        case "fetch":
+            return cmdFetch(args);
+        case "serve":
+            return cmdServe(args);
+        case "version":
+            return cmdVersion();
+        default:
+            process.stdout.write(HELP);
+            return 0;
+    }
+}
+/** True when this file is the entry point (so importing it for tests is a no-op). */
+function invokedDirectly() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2))
+        // exitCode rather than process.exit(): the latter can truncate the JSON
+        // `fetch`/`version` just wrote into an async stdout pipe.
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((e) => {
+        // Fail loudly with an actionable message; never swallow.
+        if (e instanceof UsageError) {
+            process.stderr.write(`error: ${e.message}\n\n${HELP}`);
+            process.exitCode = 2;
+        }
+        else if (e instanceof GaiaError) {
+            process.stderr.write(`[gaia] ${e.name}: ${e.message}\n`);
+            process.exitCode = 1;
+        }
+        else {
+            process.stderr.write(`[gaia] unexpected error: ${e.stack ?? e}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed error classes. Per the GAIA no-silent-fallback rule, every failure path
+ * raises one of these with an actionable message — never a swallowed error or a
+ * silently-degraded result.
+ */
+/** Base class so callers can `instanceof GaiaError` to catch any of ours. */
+export declare class GaiaError extends Error {
+    constructor(message: string);
+}
+/** A downloaded binary's SHA-256 did not match `binaries.lock.json`. */
+export declare class IntegrityError extends GaiaError {
+}
+/** Unsupported platform-arch, or no lock entry for a component on this host. */
+export declare class PlatformError extends GaiaError {
+}
+/** The sidecar did not become healthy within the timeout. */
+export declare class HealthTimeoutError extends GaiaError {
+}
+/** The sidecar's apiVersion is incompatible with what this package expects. */
+export declare class VersionMismatchError extends GaiaError {
+}
+/** A binary could not be located on disk for spawning. */
+export declare class BinaryNotFoundError extends GaiaError {
+}
+/** An HTTP request to the sidecar returned a non-2xx status. */
+export declare class HttpError extends GaiaError {
+    readonly status: number;
+    readonly url: string;
+    readonly bodyText: string;
+    constructor(status: number, url: string, bodyText: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,6EAA6E;AAC7E,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,qBAAa,cAAe,SAAQ,SAAS;CAAG;AAEhD,gFAAgF;AAChF,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C,6DAA6D;AAC7D,qBAAa,kBAAmB,SAAQ,SAAS;CAAG;AAEpD,+EAA+E;AAC/E,qBAAa,oBAAqB,SAAQ,SAAS;CAAG;AAEtD,0DAA0D;AAC1D,qBAAa,mBAAoB,SAAQ,SAAS;CAAG;AAErD,gEAAgE;AAChE,qBAAa,SAAU,SAAQ,SAAS;aAEpB,MAAM,EAAE,MAAM;aACd,GAAG,EAAE,MAAM;aACX,QAAQ,EAAE,MAAM;gBAFhB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM;CAInC"}

package/dist/errors.js

@@ -0,0 +1,42 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * Typed error classes. Per the GAIA no-silent-fallback rule, every failure path
+ * raises one of these with an actionable message — never a swallowed error or a
+ * silently-degraded result.
+ */
+/** Base class so callers can `instanceof GaiaError` to catch any of ours. */
+export class GaiaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** A downloaded binary's SHA-256 did not match `binaries.lock.json`. */
+export class IntegrityError extends GaiaError {
+}
+/** Unsupported platform-arch, or no lock entry for a component on this host. */
+export class PlatformError extends GaiaError {
+}
+/** The sidecar did not become healthy within the timeout. */
+export class HealthTimeoutError extends GaiaError {
+}
+/** The sidecar's apiVersion is incompatible with what this package expects. */
+export class VersionMismatchError extends GaiaError {
+}
+/** A binary could not be located on disk for spawning. */
+export class BinaryNotFoundError extends GaiaError {
+}
+/** An HTTP request to the sidecar returned a non-2xx status. */
+export class HttpError extends GaiaError {
+    status;
+    url;
+    bodyText;
+    constructor(status, url, bodyText) {
+        super(`HTTP ${status} from ${url}: ${bodyText || "(empty body)"}`);
+        this.status = status;
+        this.url = url;
+        this.bodyText = bodyText;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+BAA+B;AAC/B;;;;GAIG;AAEH,6EAA6E;AAC7E,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,cAAe,SAAQ,SAAS;CAAG;AAEhD,gFAAgF;AAChF,MAAM,OAAO,aAAc,SAAQ,SAAS;CAAG;AAE/C,6DAA6D;AAC7D,MAAM,OAAO,kBAAmB,SAAQ,SAAS;CAAG;AAEpD,+EAA+E;AAC/E,MAAM,OAAO,oBAAqB,SAAQ,SAAS;CAAG;AAEtD,0DAA0D;AAC1D,MAAM,OAAO,mBAAoB,SAAQ,SAAS;CAAG;AAErD,gEAAgE;AAChE,MAAM,OAAO,SAAU,SAAQ,SAAS;IAEpB;IACA;IACA;IAHlB,YACkB,MAAc,EACd,GAAW,EACX,QAAgB;QAEhC,KAAK,CAAC,QAAQ,MAAM,SAAS,GAAG,KAAK,QAAQ,IAAI,cAAc,EAAE,CAAC,CAAC;QAJnD,WAAM,GAAN,MAAM,CAAQ;QACd,QAAG,GAAH,GAAG,CAAQ;QACX,aAAQ,GAAR,QAAQ,CAAQ;IAGlC,CAAC;CACF"}

package/dist/fetch.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Binary fetcher for both components (`sidecar` and `tui`).
+ *
+ * Resolves the current platform → looks the component up in
+ * `binaries.lock.json` → downloads it from THAT COMPONENT's base URL
+ * (overridable) → **verifies its SHA-256 against the lock and fails loudly on
+ * any mismatch** → writes it into a cache dir → `chmod +x` on POSIX.
+ *
+ * The two components come from different hub lanes: the sidecar from
+ * `agents/gaia/<agentVersion>/`, the TUI from `agents/terminal-hub/<tuiVersion>/`
+ * (the same binary a core install runs as `gaia tui`). Each entry's base URL
+ * comes from its own component, never from a shared top-level one.
+ *
+ * The SHA verify is the security boundary: a tampered, truncated, or
+ * not-yet-published artifact is rejected before it can ever be spawned. There is
+ * NO "use it anyway" path, and a placeholder hash in the lock blocks the fetch
+ * outright rather than degrading to an unverified download.
+ */
+import { type BinaryLock, type ComponentName } from "./platform.js";
+/**
+ * Where verified binaries are cached, keyed by agent version so a version bump
+ * never reuses the previous release's executables.
+ */
+export declare function defaultCacheDir(agentVersion: string): string;
+/**
+ * The daemon's own sidecar cache — `~/.gaia/agents/gaia/`, mirroring
+ * `gaia.daemon.sidecars.fetch.default_cache_dir("gaia")`. Staging the verified
+ * sidecar here means the daemon's own fetch is a SHA-256 cache hit instead of a
+ * second download. This path is a cross-repo contract with the daemon.
+ */
+export declare function daemonSidecarCacheDir(agentId?: string): string;
+export interface FetchOptions {
+    /** Which binary to fetch. */
+    component: ComponentName;
+    /** Directory the verified binary is written into. Required. */
+    outDir: string;
+    /**
+     * Override this component's `baseUrl` (e.g. a local mirror). Trailing slash
+     * optional. Applies to whichever component is being fetched — the two lanes'
+     * filenames never collide, so one flat mirror directory can serve both.
+     */
+    baseUrl?: string;
+    /** Override the platform key (defaults to the current host). */
+    platformKey?: string;
+    /** Path to the lock file (defaults to the packaged binaries.lock.json). */
+    lockPath?: string;
+    /** A pre-loaded lock, to avoid re-reading it per component. */
+    lock?: BinaryLock;
+    /** Fetch override (tests). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Re-download even when a verified binary is already cached. Default false. */
+    force?: boolean;
+    /** Abort the download after this many ms. Default 300000 (the sidecar is ~200MB). */
+    timeoutMs?: number;
+}
+export interface FetchResult {
+    component: ComponentName;
+    /** Absolute path to the written, verified executable. */
+    binaryPath: string;
+    /** The platform key resolved. */
+    platformKey: string;
+    /** The verified SHA-256 (lowercase hex). */
+    sha256: string;
+    /** Source URL the artifact was downloaded from. */
+    url: string;
+    /** True when the on-disk binary was reused (hash already matched). */
+    cached: boolean;
+}
+/**
+ * SHA-256 of a file on disk, or null when it is simply absent. Any other error
+ * (a permission problem, a directory in the way) is re-raised: reading it as
+ * "no cache" would trigger a re-download that then fails on write with a far
+ * less useful message.
+ */
+export declare function fileSha256(filePath: string): Promise<string | null>;
+/**
+ * Verify a buffer against an expected SHA-256. Throws `IntegrityError` loudly on
+ * mismatch — this is the no-silent-fallback integrity gate.
+ */
+export declare function verifySha256(buf: Buffer, expected: string, sourceLabel: string): string;
+/**
+ * Fetch + verify + install one component's binary for the current platform.
+ *
+ * @throws PlatformError   unsupported platform / incomplete entry / placeholder hash
+ * @throws IntegrityError  SHA-256 mismatch
+ * @throws Error           download/network failure (HTTP status surfaced)
+ */
+export declare function fetchBinary(opts: FetchOptions): Promise<FetchResult>;
+export interface FetchAllOptions extends Omit<FetchOptions, "component" | "outDir"> {
+    /** Cache dir for the TUI. Defaults to `defaultCacheDir(lock.agentVersion)`. */
+    tuiDir?: string;
+    /** Cache dir for the sidecar. Defaults to the daemon's `~/.gaia/agents/gaia`. */
+    sidecarDir?: string;
+}
+export interface FetchAllResult {
+    sidecar: FetchResult;
+    tui: FetchResult;
+    lock: BinaryLock;
+}
+/**
+ * Fetch + verify BOTH binaries. Sequential on purpose: the sidecar is the large
+ * download and a failure there should not race a half-finished TUI download.
+ *
+ * The sidecar lands in the daemon's own cache dir so the daemon — which owns
+ * spawning it — finds it already verified instead of downloading it again.
+ */
+export declare function fetchAll(opts?: FetchAllOptions): Promise<FetchAllResult>;
+/** Sync existence check, for the lifecycle layer. */
+export declare function binaryExists(binaryPath: string): boolean;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,aAAa,EAOnB,MAAM,eAAe,CAAC;AAIvB;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,GAAG,MAAM,CAE9D;AAED,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,SAAS,EAAE,aAAa,CAAC;IACzB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,aAAa,CAAC;IACzB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYzE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA0G1E;AAED,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjF,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,GAAG,EAAE,WAAW,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAelF;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAExD"}