@amd-gaia/gaia 0.1.0 → 0.1.1

package/dist/fetch.js

@@ -0,0 +1,217 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * 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 crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { IntegrityError, PlatformError } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { joinUrl } from "./url.js";
+import { componentBaseUrl, currentPlatformKey, defaultLockPath, isPlaceholderSha, loadLock, resolveEntry, } from "./platform.js";
+const log = createLogger("fetch");
+/**
+ * Where verified binaries are cached, keyed by agent version so a version bump
+ * never reuses the previous release's executables.
+ */
+export function defaultCacheDir(agentVersion) {
+    return path.join(os.homedir(), ".gaia", "npm-cache", `gaia-${agentVersion}`);
+}
+/**
+ * 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 function daemonSidecarCacheDir(agentId = "gaia") {
+    return path.join(os.homedir(), ".gaia", "agents", agentId);
+}
+function sha256Hex(buf) {
+    return crypto.createHash("sha256").update(buf).digest("hex");
+}
+/**
+ * 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 async function fileSha256(filePath) {
+    try {
+        return sha256Hex(await fsp.readFile(filePath));
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return null;
+        throw new Error(`cannot read the cached binary at ${filePath} to check its hash: ${e.message}. ` +
+            "Fix the permissions on that path, or pass a different --cache-dir / --sidecar-dir.", { cause: e });
+    }
+}
+/**
+ * Verify a buffer against an expected SHA-256. Throws `IntegrityError` loudly on
+ * mismatch — this is the no-silent-fallback integrity gate.
+ */
+export function verifySha256(buf, expected, sourceLabel) {
+    const actual = sha256Hex(buf);
+    if (actual.toLowerCase() !== expected.toLowerCase()) {
+        throw new IntegrityError(`SHA-256 mismatch for ${sourceLabel}:\n` +
+            `  expected ${expected}\n` +
+            `  actual   ${actual}\n` +
+            "Refusing to use a binary that does not match binaries.lock.json. " +
+            "The download may be corrupt, truncated, or tampered with. Re-run the fetch; " +
+            "if it persists, the lock is stale relative to the published artifact — " +
+            "report it at https://github.com/amd/gaia/issues.");
+    }
+    return actual;
+}
+/**
+ * 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 async function fetchBinary(opts) {
+    if (!opts?.outDir) {
+        throw new TypeError("fetchBinary requires an outDir to write the binary into");
+    }
+    if (!opts?.component) {
+        throw new TypeError('fetchBinary requires a component ("sidecar" or "tui")');
+    }
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new TypeError("global fetch unavailable — use Node >= 18 or pass fetchImpl");
+    }
+    const lock = opts.lock ?? loadLock(opts.lockPath ?? defaultLockPath());
+    const platformKey = opts.platformKey ?? currentPlatformKey();
+    const entry = resolveEntry(lock, opts.component, platformKey);
+    // Per-component: the sidecar and the TUI live in different hub lanes at
+    // different versions, so there is no single base URL to fall back to.
+    const baseUrl = opts.baseUrl ?? componentBaseUrl(lock, opts.component);
+    if (isPlaceholderSha(entry.sha256)) {
+        throw new PlatformError(`binaries.lock.json has a placeholder sha256 for ${opts.component}/'${platformKey}' ` +
+            `(${entry.sha256}), so no verifiable binary is published for it in this build. ` +
+            "Fetch is blocked so an unverifiable binary can never be trusted. " +
+            "Install a released @amd-gaia/gaia, or build the binary locally " +
+            "(hub/agents/gaia/python/packaging for the sidecar, `make -C tui cross-compile` " +
+            "for the TUI) and point the lifecycle helpers at it directly.");
+    }
+    const outDir = path.resolve(opts.outDir);
+    await fsp.mkdir(outDir, { recursive: true });
+    const binaryPath = path.join(outDir, entry.executable);
+    const url = joinUrl(baseUrl, entry.filename);
+    if (!opts.force) {
+        const existing = await fileSha256(binaryPath);
+        if (existing && existing.toLowerCase() === entry.sha256.toLowerCase()) {
+            log.debug(`cache hit: ${binaryPath} already matches lock sha256`);
+            // Re-apply the exec bit: an interrupted earlier run or a restrictive umask
+            // can leave correct bytes that still cannot be spawned.
+            if (process.platform !== "win32")
+                await fsp.chmod(binaryPath, 0o755);
+            return {
+                component: opts.component,
+                binaryPath,
+                platformKey,
+                sha256: existing,
+                url,
+                cached: true,
+            };
+        }
+    }
+    log.info(`downloading ${opts.component} for ${platformKey} from ${url}`);
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let buf;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { accept: "application/octet-stream" },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`download failed: HTTP ${res.status} ${res.statusText} for ${url}. ` +
+                "Check the base URL and that the artifact is published for this platform.");
+        }
+        buf = Buffer.from(await res.arrayBuffer());
+    }
+    catch (e) {
+        if (e.name === "AbortError") {
+            throw new Error(`download timed out after ${timeoutMs}ms for ${url}`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    log.debug(`downloaded ${buf.length} bytes`);
+    const sha = verifySha256(buf, entry.sha256, `${opts.component} ${platformKey} (${url})`);
+    // Write to a temp then rename, so a crash mid-write never leaves a
+    // half-written file that a later run would treat as a real binary.
+    const tmp = `${binaryPath}.download.${process.pid}`;
+    try {
+        await fsp.writeFile(tmp, buf);
+        await fsp.rename(tmp, binaryPath);
+    }
+    catch (e) {
+        await fsp.rm(tmp, { force: true }).catch(() => undefined);
+        throw e;
+    }
+    if (process.platform !== "win32") {
+        await fsp.chmod(binaryPath, 0o755);
+    }
+    log.info(`installed verified ${opts.component} -> ${binaryPath}`);
+    return {
+        component: opts.component,
+        binaryPath,
+        platformKey,
+        sha256: sha,
+        url,
+        cached: false,
+    };
+}
+/**
+ * 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 async function fetchAll(opts = {}) {
+    const lock = opts.lock ?? loadLock(opts.lockPath ?? defaultLockPath());
+    const platformKey = opts.platformKey ?? currentPlatformKey();
+    const common = { ...opts, lock, platformKey };
+    const sidecar = await fetchBinary({
+        ...common,
+        component: "sidecar",
+        outDir: opts.sidecarDir ?? daemonSidecarCacheDir(),
+    });
+    const tui = await fetchBinary({
+        ...common,
+        component: "tui",
+        outDir: opts.tuiDir ?? defaultCacheDir(lock.agentVersion),
+    });
+    return { sidecar, tui, lock };
+}
+/** Sync existence check, for the lifecycle layer. */
+export function binaryExists(binaryPath) {
+    return fs.existsSync(binaryPath);
+}
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @amd-gaia/gaia — binary fetcher + process lifecycle for the GAIA flagship
+ * agent sidecar and the GAIA terminal UI.
+ *
+ * The CLI (`npx @amd-gaia/gaia`) is the normal way in. These exports are for
+ * integrators who want the pieces:
+ *
+ *   import { fetchAll, startSidecar, shutdown } from "@amd-gaia/gaia";
+ *
+ *   const { sidecar, tui } = await fetchAll();          // both, SHA-256 verified
+ *   const proc = await startSidecar({ binaryPath: sidecar.binaryPath });
+ *   const res  = await fetch(`${proc.baseUrl}/v1/gaia/query`, { ... });
+ *   await shutdown(proc);
+ */
+export { fetchAll, fetchBinary, verifySha256, fileSha256, binaryExists, defaultCacheDir, daemonSidecarCacheDir, } from "./fetch.js";
+export type { FetchOptions, FetchResult, FetchAllOptions, FetchAllResult, } from "./fetch.js";
+export { AGENT_ID, API_VERSION, DEFAULT_HOST, DEFAULT_PORT, RESERVED_PORT, checkVersion, health, resolveSidecarPath, resolveTuiPath, runTui, shutdown, sidecarExecutableName, spawnSidecar, startSidecar, tuiExecutableName, version, waitForHealth, } from "./lifecycle.js";
+export type { HealthResponse, ResolveOptions, RunTuiOptions, Sidecar, SpawnOptions, StartOptions, VersionCheckOptions, VersionResponse, WaitForHealthOptions, } from "./lifecycle.js";
+export { COMPONENTS, SCHEMA_MAJOR, SUPPORTED_PLATFORMS, SUPPORTED_SIDECAR_PLATFORMS, SUPPORTED_TUI_PLATFORMS, TUI_ARTIFACT_NAMES, componentBaseUrl, componentLock, currentPlatformKey, defaultLockPath, isPlaceholderSha, loadLock, platformsFor, resolveEntry, } from "./platform.js";
+export type { BinaryLock, BinaryLockEntry, ComponentLock, ComponentName, } from "./platform.js";
+export { BinaryNotFoundError, GaiaError, HealthTimeoutError, HttpError, IntegrityError, PlatformError, VersionMismatchError, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,eAAe,EACf,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,cAAc,EACd,MAAM,EACN,QAAQ,EACR,qBAAqB,EACrB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACb,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,aAAa,EACb,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * @amd-gaia/gaia — binary fetcher + process lifecycle for the GAIA flagship
+ * agent sidecar and the GAIA terminal UI.
+ *
+ * The CLI (`npx @amd-gaia/gaia`) is the normal way in. These exports are for
+ * integrators who want the pieces:
+ *
+ *   import { fetchAll, startSidecar, shutdown } from "@amd-gaia/gaia";
+ *
+ *   const { sidecar, tui } = await fetchAll();          // both, SHA-256 verified
+ *   const proc = await startSidecar({ binaryPath: sidecar.binaryPath });
+ *   const res  = await fetch(`${proc.baseUrl}/v1/gaia/query`, { ... });
+ *   await shutdown(proc);
+ */
+export { fetchAll, fetchBinary, verifySha256, fileSha256, binaryExists, defaultCacheDir, daemonSidecarCacheDir, } from "./fetch.js";
+export { AGENT_ID, API_VERSION, DEFAULT_HOST, DEFAULT_PORT, RESERVED_PORT, checkVersion, health, resolveSidecarPath, resolveTuiPath, runTui, shutdown, sidecarExecutableName, spawnSidecar, startSidecar, tuiExecutableName, version, waitForHealth, } from "./lifecycle.js";
+export { COMPONENTS, SCHEMA_MAJOR, SUPPORTED_PLATFORMS, SUPPORTED_SIDECAR_PLATFORMS, SUPPORTED_TUI_PLATFORMS, TUI_ARTIFACT_NAMES, componentBaseUrl, componentLock, currentPlatformKey, defaultLockPath, isPlaceholderSha, loadLock, platformsFor, resolveEntry, } from "./platform.js";
+export { BinaryNotFoundError, GaiaError, HealthTimeoutError, HttpError, IntegrityError, PlatformError, VersionMismatchError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+BAA+B;AAC/B;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,eAAe,EACf,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAQpB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,cAAc,EACd,MAAM,EACN,QAAQ,EACR,qBAAqB,EACrB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,aAAa,GACd,MAAM,gBAAgB,CAAC;AAaxB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC;AAQvB,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,aAAa,EACb,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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 { type ChildProcess } from "node:child_process";
+export declare const DEFAULT_HOST = "127.0.0.1";
+/** Matches `gaia_agent_gaia.server.DEFAULT_PORT`. NEVER 4001 (repo-reserved). */
+export declare const DEFAULT_PORT = 8141;
+/** Repo-wide reserved port. Nothing here may ever bind it. */
+export declare const RESERVED_PORT = 4001;
+/** The apiVersion this package is built against (`server.py: API_VERSION`). */
+export declare const API_VERSION = "2.12";
+/** The agent id in the sidecar's route prefix (`/v1/gaia/...`). */
+export declare const AGENT_ID = "gaia";
+/** `GET /health` response. */
+export interface HealthResponse {
+    status: string;
+    service?: string;
+}
+/** `GET /version` response — the key names are a contract, not a convention. */
+export interface VersionResponse {
+    apiVersion: string;
+    agentVersion: string;
+}
+/** Basename the sidecar executable is written as (matches the lock). */
+export declare function sidecarExecutableName(platform?: NodeJS.Platform): string;
+/**
+ * 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 declare function tuiExecutableName(platform?: NodeJS.Platform): string;
+export interface ResolveOptions {
+    /** Directory the binary was fetched into. */
+    resourcesDir: string;
+    /** Override the executable basename (defaults per-platform). */
+    executable?: string;
+}
+export declare function resolveSidecarPath(opts: ResolveOptions): string;
+export declare function resolveTuiPath(opts: ResolveOptions): string;
+export interface SpawnOptions {
+    /** Absolute path to the sidecar binary. */
+    binaryPath: string;
+    /** Bind host. Default 127.0.0.1. */
+    host?: string;
+    /** Bind port. Default 8141. NEVER 4001. */
+    port?: number;
+    /** Extra CLI args appended verbatim. */
+    extraArgs?: string[];
+    /** Extra env vars merged over process.env. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Reap this sidecar if the parent exits, crashes, or is interrupted without an
+     * explicit `shutdown()`. Default `true` — the frozen binary's detached child
+     * must never outlive us holding the port. Set `false` to own the lifecycle.
+     */
+    autoCleanup?: boolean;
+}
+/** A running sidecar handle. */
+export interface Sidecar {
+    child: ChildProcess;
+    host: string;
+    port: number;
+    baseUrl: string;
+}
+/**
+ * Spawn the frozen sidecar. Does NOT wait for readiness — call `waitForHealth`
+ * (or `startSidecar`, which does both).
+ */
+export declare function spawnSidecar(opts: SpawnOptions): Sidecar;
+/** `GET /health` — liveness only; it does not mean a model is loaded. */
+export declare function health(baseUrl: string, timeoutMs?: number): Promise<HealthResponse>;
+/** `GET /version` — the contract probe (`{ apiVersion, agentVersion }`). */
+export declare function version(baseUrl: string, timeoutMs?: number): Promise<VersionResponse>;
+export interface WaitForHealthOptions {
+    /** Total time to wait before failing loudly. Default 60000ms. */
+    timeoutMs?: number;
+    /** Poll interval. Default 250ms. */
+    intervalMs?: number;
+    /** Abort the wait early (e.g. the process being probed died). */
+    signal?: AbortSignal;
+}
+/**
+ * Poll `GET /health` until the sidecar reports ok, or throw `HealthTimeoutError`.
+ * Never silently assumes ready.
+ */
+export declare function waitForHealth(baseUrl: string, opts?: WaitForHealthOptions): Promise<void>;
+export interface VersionCheckOptions {
+    /** apiVersion this package was built against. Default API_VERSION ("2.12"). */
+    expectedApiVersion?: string;
+}
+/**
+ * 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 declare function checkVersion(baseUrl: string, opts?: VersionCheckOptions): Promise<VersionResponse>;
+/**
+ * Shut the sidecar down, killing the whole process tree. Resolves once the
+ * process has exited (or immediately if it already had).
+ */
+export declare function shutdown(sidecar: Sidecar, timeoutMs?: number): Promise<void>;
+export interface StartOptions extends SpawnOptions {
+    /** Health-wait timeout. Default 60000ms (a cold frozen binary unpacks first). */
+    healthTimeoutMs?: number;
+    /** Verify the contract apiVersion after health. Default true. */
+    verifyVersion?: boolean;
+    /** apiVersion this package expects. Default API_VERSION. */
+    expectedApiVersion?: string;
+}
+/**
+ * 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 declare function startSidecar(opts: StartOptions): Promise<Sidecar>;
+export interface RunTuiOptions {
+    /** Absolute path to the gaia-tui binary. */
+    binaryPath: string;
+    /** Args forwarded verbatim to the TUI. */
+    args?: string[];
+    /** Extra env merged over process.env. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * 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 declare function runTui(opts: RunTuiOptions): Promise<number>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

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