@amd-gaia/gaia 0.1.0 → 0.1.1

package/dist/lifecycle.js

@@ -0,0 +1,397 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * Process lifecycle for the two binaries this package installs.
+ *
+ * **Sidecar** — locate the frozen binary, spawn it, poll `GET /health`, check the
+ * contract version via `GET /version`, and shut it down killing the whole process
+ * tree. Tree-kill matters: a PyInstaller one-file build spawns a child uvicorn
+ * process that `child.kill()` on the parent does NOT reap, leaving the port held.
+ *
+ * **TUI** — exec it with stdio inherited and propagate its exit code, so the
+ * terminal UI owns the terminal completely.
+ *
+ * Note on who spawns the sidecar in the normal `gaia` flow: the GAIA daemon does.
+ * The TUI reaches agents through the daemon's relay and deliberately never holds a
+ * sidecar bearer token, so `gaia run` stages the *verified* sidecar binary into the
+ * daemon's cache and lets the daemon own its process. The helpers below are the
+ * direct path — used by `gaia serve` and by programmatic integrators who want the
+ * REST surface without a daemon.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { BinaryNotFoundError, HealthTimeoutError, HttpError, VersionMismatchError, } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { currentPlatformKey } from "./platform.js";
+const log = createLogger("lifecycle");
+export const DEFAULT_HOST = "127.0.0.1";
+/** Matches `gaia_agent_gaia.server.DEFAULT_PORT`. NEVER 4001 (repo-reserved). */
+export const DEFAULT_PORT = 8141;
+/** Repo-wide reserved port. Nothing here may ever bind it. */
+export const RESERVED_PORT = 4001;
+/** The apiVersion this package is built against (`server.py: API_VERSION`). */
+export const API_VERSION = "2.12";
+/** The agent id in the sidecar's route prefix (`/v1/gaia/...`). */
+export const AGENT_ID = "gaia";
+/** Basename the sidecar executable is written as (matches the lock). */
+export function sidecarExecutableName(platform = process.platform) {
+    return platform === "win32" ? "gaia-agent.exe" : "gaia-agent";
+}
+/**
+ * Basename the TUI executable is written as. Deliberately `gaia-tui`, not
+ * `gaia`: npm installs its own `gaia` bin shim, and a same-named executable in a
+ * cache dir on PATH would shadow it.
+ */
+export function tuiExecutableName(platform = process.platform) {
+    return platform === "win32" ? "gaia-tui.exe" : "gaia-tui";
+}
+/** Resolve a fetched binary's path, failing loudly if it is not there. */
+function resolveIn(opts, fallback, what) {
+    if (!opts?.resourcesDir) {
+        throw new TypeError("resolve requires { resourcesDir }");
+    }
+    const full = path.resolve(opts.resourcesDir, opts.executable ?? fallback);
+    if (!fs.existsSync(full)) {
+        throw new BinaryNotFoundError(`${what} binary not found at ${full} (platform ${currentPlatformKey()}). ` +
+            "Run the fetch step first: `npx @amd-gaia/gaia fetch`.");
+    }
+    return full;
+}
+export function resolveSidecarPath(opts) {
+    return resolveIn(opts, sidecarExecutableName(), "gaia-agent sidecar");
+}
+export function resolveTuiPath(opts) {
+    return resolveIn(opts, tuiExecutableName(), "gaia-tui");
+}
+// --- Auto-cleanup: reap orphaned sidecars when the parent process goes away ---
+// The sidecar is spawned detached (its own process group), so a parent Ctrl+C,
+// crash, or plain exit does NOT propagate to it — without this it keeps running
+// and holds its port. Handlers are installed once and SIGKILL the tree
+// synchronously on the way out. A hard SIGKILL of the parent is the one case no
+// in-process handler can catch.
+const liveSidecars = new Set();
+let cleanupInstalled = false;
+const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+function killTreeSync(sidecar) {
+    const { child } = sidecar;
+    if (child.pid === undefined)
+        return;
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        if (process.platform === "win32") {
+            spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+        }
+        else {
+            process.kill(-child.pid, "SIGKILL");
+        }
+    }
+    catch {
+        /* already gone */
+    }
+}
+function reapAllSync() {
+    for (const s of liveSidecars)
+        killTreeSync(s);
+    liveSidecars.clear();
+}
+function crashHandler(err) {
+    reapAllSync();
+    try {
+        // Synchronous write — console.error can truncate on a piped stderr before
+        // process.exit flushes.
+        fs.writeSync(2, `${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    }
+    catch {
+        /* stderr unavailable */
+    }
+    process.exit(1);
+}
+function installCleanupHandlers() {
+    if (cleanupInstalled)
+        return;
+    cleanupInstalled = true;
+    process.on("exit", reapAllSync);
+    process.on("uncaughtException", (err) => {
+        reapAllSync();
+        if (process.listenerCount("uncaughtException") === 1)
+            crashHandler(err);
+    });
+    process.on("unhandledRejection", (err) => {
+        reapAllSync();
+        if (process.listenerCount("unhandledRejection") === 1)
+            crashHandler(err);
+    });
+    for (const sig of CLEANUP_SIGNALS) {
+        const handler = () => {
+            reapAllSync();
+            // Sole listener → restore the default disposition and re-raise so the
+            // process still terminates (Ctrl+C).
+            if (process.listenerCount(sig) === 1) {
+                process.removeListener(sig, handler);
+                process.kill(process.pid, sig);
+            }
+        };
+        process.on(sig, handler);
+    }
+}
+function registerForCleanup(sidecar) {
+    installCleanupHandlers();
+    liveSidecars.add(sidecar);
+    sidecar.child.once("exit", () => liveSidecars.delete(sidecar));
+}
+/**
+ * Spawn the frozen sidecar. Does NOT wait for readiness — call `waitForHealth`
+ * (or `startSidecar`, which does both).
+ */
+export function spawnSidecar(opts) {
+    if (!opts?.binaryPath) {
+        throw new TypeError("spawnSidecar requires { binaryPath }");
+    }
+    if (!fs.existsSync(opts.binaryPath)) {
+        throw new BinaryNotFoundError(`binary does not exist: ${opts.binaryPath}`);
+    }
+    const host = opts.host ?? DEFAULT_HOST;
+    const port = opts.port ?? DEFAULT_PORT;
+    if (port === RESERVED_PORT) {
+        throw new RangeError(`port ${RESERVED_PORT} is reserved and must never be used`);
+    }
+    const args = ["--host", host, "--port", String(port)];
+    if (opts.extraArgs?.length)
+        args.push(...opts.extraArgs);
+    log.info(`spawning ${opts.binaryPath} ${args.join(" ")}`);
+    const child = spawn(opts.binaryPath, args, {
+        // detached on POSIX → the child leads its own process group so we can signal
+        // the whole tree. Windows has different detach semantics; we use taskkill /T.
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, ...(opts.env ?? {}) },
+    });
+    child.stdout?.on("data", (d) => log.debug(`[sidecar stdout] ${String(d).trimEnd()}`));
+    child.stderr?.on("data", (d) => log.debug(`[sidecar stderr] ${String(d).trimEnd()}`));
+    child.on("exit", (code, signal) => log.debug(`sidecar exited code=${code} signal=${signal}`));
+    child.on("error", (e) => log.error(`sidecar process error: ${e.message}`));
+    const sidecar = { child, host, port, baseUrl: `http://${host}:${port}` };
+    if (opts.autoCleanup !== false)
+        registerForCleanup(sidecar);
+    return sidecar;
+}
+async function getJson(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new HttpError(res.status, url, text);
+        return JSON.parse(text);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** `GET /health` — liveness only; it does not mean a model is loaded. */
+export function health(baseUrl, timeoutMs = 1000) {
+    return getJson(`${baseUrl}/health`, timeoutMs);
+}
+/** `GET /version` — the contract probe (`{ apiVersion, agentVersion }`). */
+export function version(baseUrl, timeoutMs = 5000) {
+    return getJson(`${baseUrl}/version`, timeoutMs);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Poll `GET /health` until the sidecar reports ok, or throw `HealthTimeoutError`.
+ * Never silently assumes ready.
+ */
+export async function waitForHealth(baseUrl, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const intervalMs = opts.intervalMs ?? 250;
+    const deadline = Date.now() + timeoutMs;
+    let lastErr = "";
+    let attempts = 0;
+    while (Date.now() < deadline) {
+        if (opts.signal?.aborted) {
+            throw new HealthTimeoutError(`health wait for ${baseUrl} was aborted after ${attempts} probe(s) ` +
+                "(the process being probed exited).");
+        }
+        attempts++;
+        try {
+            const h = await health(baseUrl, intervalMs * 4);
+            if (h.status === "ok") {
+                log.debug(`sidecar healthy after ${attempts} probe(s)`);
+                return;
+            }
+            lastErr = `unexpected health status: ${JSON.stringify(h)}`;
+        }
+        catch (e) {
+            lastErr = e.message;
+        }
+        await sleep(intervalMs);
+    }
+    throw new HealthTimeoutError(`the gaia sidecar at ${baseUrl} did not become healthy within ${timeoutMs}ms ` +
+        `(${attempts} probes). Last error: ${lastErr}. ` +
+        "Re-run with DEBUG=gaia to see the sidecar's own output, and check the port is free.");
+}
+/** Parse "2.12" → 2 (major). Throws on a non-numeric major. */
+function majorOf(v) {
+    const major = Number.parseInt(String(v).split(".")[0] ?? "", 10);
+    if (Number.isNaN(major)) {
+        throw new VersionMismatchError(`cannot parse apiVersion major from '${v}'`);
+    }
+    return major;
+}
+/**
+ * Fetch `/version` and refuse a sidecar whose apiVersion MAJOR differs from what
+ * this package expects. A major bump is a breaking contract change; a higher
+ * minor (same major) is a backward-compatible addition and is accepted.
+ */
+export async function checkVersion(baseUrl, opts = {}) {
+    const expected = opts.expectedApiVersion ?? API_VERSION;
+    const info = await version(baseUrl);
+    const expectedMajor = majorOf(expected);
+    const actualMajor = majorOf(info.apiVersion);
+    if (actualMajor !== expectedMajor) {
+        throw new VersionMismatchError(`incompatible gaia sidecar apiVersion: it reports '${info.apiVersion}' ` +
+            `(major ${actualMajor}) but this package expects major ${expectedMajor} ` +
+            `('${expected}'). A major bump is a breaking contract change. ` +
+            "Upgrade @amd-gaia/gaia to a version matching the sidecar.");
+    }
+    log.debug(`version OK: apiVersion=${info.apiVersion} agentVersion=${info.agentVersion}`);
+    return info;
+}
+/**
+ * Shut the sidecar down, killing the whole process tree. Resolves once the
+ * process has exited (or immediately if it already had).
+ */
+export async function shutdown(sidecar, timeoutMs = 5000) {
+    const { child } = sidecar;
+    liveSidecars.delete(sidecar); // an explicit shutdown owns the lifecycle now
+    if (child.exitCode !== null || child.signalCode !== null || child.pid === undefined) {
+        log.debug("shutdown: sidecar already exited");
+        return;
+    }
+    const pid = child.pid;
+    log.info(`shutting down sidecar pid=${pid} (tree-kill)`);
+    const exited = new Promise((resolve) => {
+        child.once("exit", () => resolve());
+    });
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+            stdio: "ignore",
+        });
+        killer.on("error", (e) => log.error(`taskkill failed: ${e.message}`));
+    }
+    else {
+        try {
+            process.kill(-pid, "SIGTERM"); // negative pid → the whole process group
+        }
+        catch (e) {
+            log.debug(`SIGTERM to group failed (${e.message}); trying direct`);
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    const raceExit = async (ms) => {
+        let t;
+        const timer = new Promise((resolve) => {
+            t = setTimeout(() => resolve("timeout"), ms);
+        });
+        return Promise.race([exited.then(() => "exited"), timer]).finally(() => clearTimeout(t));
+    };
+    if ((await raceExit(timeoutMs)) === "timeout") {
+        log.warn(`sidecar did not exit within ${timeoutMs}ms; forcing`);
+        if (process.platform !== "win32") {
+            try {
+                process.kill(-pid, "SIGKILL");
+            }
+            catch {
+                /* gone */
+            }
+        }
+        // Bound the final wait too. On Windows there is no second escalation after
+        // taskkill, so an unbounded await here would hang Ctrl+C forever.
+        if ((await raceExit(timeoutMs)) === "timeout") {
+            throw new Error(`the gaia sidecar (pid ${pid}) did not exit after a forced kill. ` +
+                "Kill it manually — " +
+                (process.platform === "win32"
+                    ? `taskkill /PID ${pid} /T /F`
+                    : `kill -9 -${pid}`) +
+                ` — or the port it holds stays bound.`);
+        }
+    }
+    log.info("sidecar shut down");
+}
+/**
+ * Spawn → wait for health → (optionally) version-check. On any failure the
+ * sidecar is shut down before rethrowing, so a failed start never leaks a
+ * process.
+ */
+export async function startSidecar(opts) {
+    const sidecar = spawnSidecar(opts);
+    // A sidecar that dies immediately (missing runtime lib, port already bound)
+    // must not make the caller wait out the full health timeout.
+    const died = new AbortController();
+    sidecar.child.once("exit", () => died.abort());
+    try {
+        await waitForHealth(sidecar.baseUrl, {
+            timeoutMs: opts.healthTimeoutMs,
+            signal: died.signal,
+        });
+        if (opts.verifyVersion ?? true) {
+            await checkVersion(sidecar.baseUrl, {
+                expectedApiVersion: opts.expectedApiVersion,
+            });
+        }
+        return sidecar;
+    }
+    catch (e) {
+        log.error(`startSidecar failed (${e.message}); shutting down`);
+        await shutdown(sidecar).catch(() => undefined);
+        throw e;
+    }
+}
+/**
+ * Run the TUI in the foreground with stdio inherited and resolve with its exit
+ * code. A signal-terminated TUI resolves as 128 + signum, the shell convention,
+ * so a Ctrl+C is distinguishable from a clean exit 0.
+ */
+export function runTui(opts) {
+    if (!opts?.binaryPath) {
+        throw new TypeError("runTui requires { binaryPath }");
+    }
+    if (!fs.existsSync(opts.binaryPath)) {
+        throw new BinaryNotFoundError(`gaia-tui binary does not exist: ${opts.binaryPath}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(opts.binaryPath, opts.args ?? [], {
+            stdio: "inherit",
+            env: { ...process.env, ...(opts.env ?? {}) },
+        });
+        child.on("error", (e) => reject(new BinaryNotFoundError(`could not launch the TUI at ${opts.binaryPath}: ${e.message}`)));
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                resolve(128 + (SIGNUM[signal] ?? 0));
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}
+// Only the signals a foreground TUI realistically dies from; anything else maps
+// to 128, which still reads as "terminated by a signal".
+const SIGNUM = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGKILL: 9,
+    SIGTERM: 15,
+};
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+BAA+B;AAC/B;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAqB,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,SAAS,EACT,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;AAEtC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAEjC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAElC,mEAAmE;AACnE,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAc/B,wEAAwE;AACxE,MAAM,UAAU,qBAAqB,CACnC,WAA4B,OAAO,CAAC,QAAQ;IAE5C,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,YAAY,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAA4B,OAAO,CAAC,QAAQ;IAE5C,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC;AAC5D,CAAC;AASD,0EAA0E;AAC1E,SAAS,SAAS,CAAC,IAAoB,EAAE,QAAgB,EAAE,IAAY;IACrE,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC,CAAC;IAC1E,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,mBAAmB,CAC3B,GAAG,IAAI,wBAAwB,IAAI,cAAc,kBAAkB,EAAE,KAAK;YACxE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAoB;IACrD,OAAO,SAAS,CAAC,IAAI,EAAE,qBAAqB,EAAE,EAAE,oBAAoB,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAoB;IACjD,OAAO,SAAS,CAAC,IAAI,EAAE,iBAAiB,EAAE,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AA6BD,iFAAiF;AACjF,+EAA+E;AAC/E,gFAAgF;AAChF,uEAAuE;AACvE,gFAAgF;AAChF,gCAAgC;AAChC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAW,CAAC;AACxC,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAC7B,MAAM,eAAe,GAAqB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAE1E,SAAS,YAAY,CAAC,OAAgB;IACpC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1B,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO;IACpC,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO;IACjE,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,SAAS,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;AACH,CAAC;AAED,SAAS,WAAW;IAClB,KAAK,MAAM,CAAC,IAAI,YAAY;QAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9C,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,WAAW,EAAE,CAAC;IACd,IAAI,CAAC;QACH,0EAA0E;QAC1E,wBAAwB;QACxB,EAAE,CAAC,SAAS,CACV,CAAC,EACD,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACvE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,wBAAwB;IAC1B,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,sBAAsB;IAC7B,IAAI,gBAAgB;QAAE,OAAO;IAC7B,gBAAgB,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,WAAW,EAAE,CAAC;QACd,IAAI,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,KAAK,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;QACvC,WAAW,EAAE,CAAC;QACd,IAAI,OAAO,CAAC,aAAa,CAAC,oBAAoB,CAAC,KAAK,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IACH,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,WAAW,EAAE,CAAC;YACd,sEAAsE;YACtE,qCAAqC;YACrC,IAAI,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBACrC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACjC,CAAC;QACH,CAAC,CAAC;QACF,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,sBAAsB,EAAE,CAAC;IACzB,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAkB;IAC7C,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,mBAAmB,CAAC,0BAA0B,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,YAAY,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,YAAY,CAAC;IACvC,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;QAC3B,MAAM,IAAI,UAAU,CAAC,QAAQ,aAAa,qCAAqC,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,IAAI,IAAI,CAAC,SAAS,EAAE,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAEzD,GAAG,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAE1D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE;QACzC,6EAA6E;QAC7E,8EAA8E;QAC9E,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO;QACtC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;QACjC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE;KAC7C,CAAC,CAAC;IAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IACtF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IACtF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAChC,GAAG,CAAC,KAAK,CAAC,uBAAuB,IAAI,WAAW,MAAM,EAAE,CAAC,CAC1D,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAE3E,MAAM,OAAO,GAAY,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;IAClF,IAAI,IAAI,CAAC,WAAW,KAAK,KAAK;QAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,OAAO,CAAI,GAAW,EAAE,SAAiB;IACtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;YACvC,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,SAAS,GAAG,IAAI;IACtD,OAAO,OAAO,CAAiB,GAAG,OAAO,SAAS,EAAE,SAAS,CAAC,CAAC;AACjE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,SAAS,GAAG,IAAI;IACvD,OAAO,OAAO,CAAkB,GAAG,OAAO,UAAU,EAAE,SAAS,CAAC,CAAC;AACnE,CAAC;AAWD,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,OAA6B,EAAE;IAE/B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,kBAAkB,CAC1B,mBAAmB,OAAO,sBAAsB,QAAQ,YAAY;gBAClE,oCAAoC,CACvC,CAAC;QACJ,CAAC;QACD,QAAQ,EAAE,CAAC;QACX,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;YAChD,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBACtB,GAAG,CAAC,KAAK,CAAC,yBAAyB,QAAQ,WAAW,CAAC,CAAC;gBACxD,OAAO;YACT,CAAC;YACD,OAAO,GAAG,6BAA6B,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,GAAI,CAAW,CAAC,OAAO,CAAC;QACjC,CAAC;QACD,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,IAAI,kBAAkB,CAC1B,uBAAuB,OAAO,kCAAkC,SAAS,KAAK;QAC5E,IAAI,QAAQ,yBAAyB,OAAO,IAAI;QAChD,qFAAqF,CACxF,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,SAAS,OAAO,CAAC,CAAS;IACxB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACjE,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAAC,uCAAuC,CAAC,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAOD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,OAA4B,EAAE;IAE9B,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,IAAI,WAAW,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,WAAW,KAAK,aAAa,EAAE,CAAC;QAClC,MAAM,IAAI,oBAAoB,CAC5B,qDAAqD,IAAI,CAAC,UAAU,IAAI;YACtE,UAAU,WAAW,oCAAoC,aAAa,GAAG;YACzE,KAAK,QAAQ,kDAAkD;YAC/D,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,KAAK,CAAC,0BAA0B,IAAI,CAAC,UAAU,iBAAiB,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IACzF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,SAAS,GAAG,IAAI;IAC/D,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1B,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,8CAA8C;IAC5E,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACpF,GAAG,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QAC9C,OAAO;IACT,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACtB,GAAG,CAAC,IAAI,CAAC,6BAA6B,GAAG,cAAc,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC3C,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE;YAClE,KAAK,EAAE,QAAQ;SAChB,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,yCAAyC;QAC1E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,KAAK,CAAC,4BAA6B,CAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC;YAC9E,IAAI,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,EAAE,EAAU,EAAiC,EAAE;QACnE,IAAI,CAAiB,CAAC;QACtB,MAAM,KAAK,GAAG,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE;YAC/C,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAiB,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAC9E,YAAY,CAAC,CAAC,CAAC,CAChB,CAAC;IACJ,CAAC,CAAC;IAEF,IAAI,CAAC,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,+BAA+B,SAAS,aAAa,CAAC,CAAC;QAChE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU;YACZ,CAAC;QACH,CAAC;QACD,2EAA2E;QAC3E,kEAAkE;QAClE,IAAI,CAAC,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CACb,yBAAyB,GAAG,sCAAsC;gBAChE,qBAAqB;gBACrB,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO;oBAC3B,CAAC,CAAC,iBAAiB,GAAG,QAAQ;oBAC9B,CAAC,CAAC,YAAY,GAAG,EAAE,CAAC;gBACtB,sCAAsC,CACzC,CAAC;QACJ,CAAC;IACH,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AAChC,CAAC;AAWD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAkB;IACnD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,4EAA4E;IAC5E,6DAA6D;IAC7D,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IACnC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE;YACnC,SAAS,EAAE,IAAI,CAAC,eAAe;YAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,EAAE,CAAC;YAC/B,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE;gBAClC,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;aAC5C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,KAAK,CAAC,wBAAyB,CAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC;QAC1E,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAmB;IACxC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,mBAAmB,CAAC,mCAAmC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE;YACpD,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE;SAC7C,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CACtB,MAAM,CACJ,IAAI,mBAAmB,CACrB,+BAA+B,IAAI,CAAC,UAAU,KAAK,CAAC,CAAC,OAAO,EAAE,CAC/D,CACF,CACF,CAAC;QACF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAChC,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACrC,OAAO;YACT,CAAC;YACD,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,yDAAyD;AACzD,MAAM,MAAM,GAA2B;IACrC,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,EAAE;CACZ,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal namespaced logger. Debug output is OFF by default and enabled via the
+ * `DEBUG` env var (substring match on `gaia`, or `*`). Everything goes to stderr
+ * so it never corrupts stdout — which the TUI owns once it is exec'd.
+ */
+export interface Logger {
+    debug(msg: string, ...rest: unknown[]): void;
+    info(msg: string, ...rest: unknown[]): void;
+    warn(msg: string, ...rest: unknown[]): void;
+    error(msg: string, ...rest: unknown[]): void;
+}
+export declare function createLogger(namespace: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAOH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC9C;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBtD"}

package/dist/logger.js

@@ -0,0 +1,30 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * Minimal namespaced logger. Debug output is OFF by default and enabled via the
+ * `DEBUG` env var (substring match on `gaia`, or `*`). Everything goes to stderr
+ * so it never corrupts stdout — which the TUI owns once it is exec'd.
+ */
+function debugEnabled() {
+    const d = (typeof process !== "undefined" && process.env?.["DEBUG"]) || "";
+    return d === "*" || d.includes("gaia");
+}
+export function createLogger(namespace) {
+    const tag = `[gaia:${namespace}]`;
+    return {
+        debug(msg, ...rest) {
+            if (debugEnabled())
+                console.error(`${tag} ${msg}`, ...rest);
+        },
+        info(msg, ...rest) {
+            console.error(`${tag} ${msg}`, ...rest);
+        },
+        warn(msg, ...rest) {
+            console.error(`${tag} WARN ${msg}`, ...rest);
+        },
+        error(msg, ...rest) {
+            console.error(`${tag} ERROR ${msg}`, ...rest);
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+BAA+B;AAC/B;;;;GAIG;AAEH,SAAS,YAAY;IACnB,MAAM,CAAC,GAAG,CAAC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3E,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC;AASD,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,MAAM,GAAG,GAAG,SAAS,SAAS,GAAG,CAAC;IAClC,OAAO;QACL,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI;YAChB,IAAI,YAAY,EAAE;gBAAE,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI;YACf,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI;YACf,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,SAAS,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;QACD,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI;YAChB,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,UAAU,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/platform.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Platform/arch resolution and binary-lock loading.
+ *
+ * The lock file (`binaries.lock.json`, shipped in the published package) is the
+ * single source of truth for which artifacts to download for the current host
+ * and what their SHA-256 must be. Platform keys are
+ * `${process.platform}-${process.arch}`.
+ *
+ * The lock is keyed by COMPONENT first (`sidecar` and `tui`), because
+ * `npx @amd-gaia/gaia` needs both and they differ in three ways: platform
+ * coverage (the Go TUI cross-compiles to arm64 Linux/Windows, the frozen Python
+ * sidecar does not), version, and — since schemaVersion 3.0 — the hub lane they
+ * are published in.
+ *
+ * The two lanes:
+ *
+ *   sidecar  agents/gaia/<agentVersion>/          built by this package's release
+ *   tui      agents/terminal-hub/<tuiVersion>/    the `terminal-hub` component,
+ *                                                 published by the core release
+ *
+ * The TUI is therefore the SAME binary as `gaia tui` from a core install — this
+ * package consumes it rather than building a second copy, so the two can never
+ * drift in behaviour or version. Each component carries its own `baseUrl`, which
+ * is what schemaVersion 2.0's single top-level `baseUrl` could not express.
+ *
+ * The terminal-hub lane spells its Windows artifacts `win-x64` / `win-arm64`,
+ * while Node's `process.platform` gives `win32`. That difference is carried by
+ * the entry's `filename` (data), never by a code path — see `TUI_ARTIFACT_NAMES`.
+ */
+/** The two binaries `npx @amd-gaia/gaia` needs. */
+export declare const COMPONENTS: readonly ["sidecar", "tui"];
+export type ComponentName = (typeof COMPONENTS)[number];
+/** The lock schema this package reads. Loading any other major fails loudly. */
+export declare const SCHEMA_MAJOR = 3;
+/** One component+platform artifact entry in the lock file. */
+export interface BinaryLockEntry {
+    /** Artifact filename as published under the component's base URL. */
+    filename: string;
+    /** Lowercase hex SHA-256 of the downloaded artifact. */
+    sha256: string;
+    /** Size in bytes (informational; not enforced). */
+    size?: number;
+    /** Basename the executable is written as on disk (with platform ext). */
+    executable: string;
+}
+/** One component's lane: where it is published, at what version, for which platforms. */
+export interface ComponentLock {
+    /** The component's own released version — not necessarily `agentVersion`. */
+    componentVersion: string;
+    /** Download base URL for THIS component. Overridable at fetch time. */
+    baseUrl: string;
+    platforms: Record<string, BinaryLockEntry>;
+}
+/** The whole lock file (`binaries.lock.json`), schemaVersion 3.x. */
+export interface BinaryLock {
+    schemaVersion: string;
+    agentVersion: string;
+    components: Record<string, ComponentLock>;
+}
+/**
+ * Platform keys the sidecar publishes for. PyInstaller freezes on the host it
+ * runs on and there is no arm64 Linux/Windows CI runner for it, so this is a
+ * strict subset of the TUI's coverage.
+ */
+export declare const SUPPORTED_SIDECAR_PLATFORMS: readonly ["win32-x64", "darwin-arm64", "darwin-x64", "linux-x64"];
+/** Platform keys the TUI publishes for (Go cross-compiles all six). */
+export declare const SUPPORTED_TUI_PLATFORMS: readonly ["win32-x64", "win32-arm64", "darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+/** Every platform key at least one component publishes for. */
+export declare const SUPPORTED_PLATFORMS: readonly ["win32-x64", "win32-arm64", "darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+/**
+ * npm platform key → the artifact name the terminal-hub lane publishes.
+ *
+ * The mapping exists for exactly one reason: terminal-hub names its Windows
+ * builds `win-x64` / `win-arm64` (Go's GOOS vocabulary), while our keys come
+ * from `process.platform`, which says `win32`. Everything else is identical.
+ * This table is the assertion, not the lookup — the lock's `filename` is what
+ * the fetcher uses, and `test/lock.test.ts` checks the two agree, so a hub-side
+ * rename shows up as a failing test rather than a 404 on a user's first run.
+ */
+export declare const TUI_ARTIFACT_NAMES: Record<string, string>;
+/** Resolve the current host's platform key, e.g. "win32-x64". */
+export declare function currentPlatformKey(platform?: NodeJS.Platform, arch?: string): string;
+/** Locate `binaries.lock.json` (package root, one level up from dist/ or src/). */
+export declare function defaultLockPath(): string;
+/** Load and minimally validate the lock file. */
+export declare function loadLock(lockPath?: string): BinaryLock;
+/** One component's lane, failing loudly when the lock does not declare it. */
+export declare function componentLock(lock: BinaryLock, component: ComponentName): ComponentLock;
+/** The download base URL for one component. */
+export declare function componentBaseUrl(lock: BinaryLock, component: ComponentName): string;
+/** The platform keys a component publishes for, per the lock. */
+export declare function platformsFor(lock: BinaryLock, component: ComponentName): string[];
+/**
+ * Resolve one component's lock entry for a platform key, failing loudly when the
+ * component has no build for it (e.g. the sidecar on linux-arm64).
+ */
+export declare function resolveEntry(lock: BinaryLock, component: ComponentName, platformKey: string): BinaryLockEntry;
+/** True when an entry's sha256 is the not-yet-published placeholder sentinel. */
+export declare function isPlaceholderSha(sha256: string): boolean;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,mDAAmD;AACnD,eAAO,MAAM,UAAU,6BAA8B,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,gFAAgF;AAChF,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC5C;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,mEAK9B,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,iGAO1B,CAAC;AAEX,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iGAA0B,CAAC;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOrD,CAAC;AAEF,iEAAiE;AACjE,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,IAAI,GAAE,MAAqB,GAC1B,MAAM,CAER;AAED,mFAAmF;AACnF,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,QAAQ,GAAE,MAA0B,GAAG,UAAU,CA2DzE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,GAAG,aAAa,CASvF;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,GAAG,MAAM,CASnF;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,GAAG,MAAM,EAAE,CAEjF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,MAAM,GAClB,eAAe,CAqCjB;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGxD"}