@amd-gaia/gaia 0.1.0 → 0.2.0

package/dist/lifecycle.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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";
+import { type BinaryLock } from "./platform.js";
+export declare const DEFAULT_HOST = "127.0.0.1";
+/** Matches `gaia_agent.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;
+    /**
+     * Re-verify the file's SHA-256 against `binaries.lock.json` before handing
+     * back a path that is about to be spawned. Default `true` — the cache dir is
+     * predictable, so anything that can write it could otherwise get code run.
+     * Set `false` only for a binary you built yourself, which no lock describes.
+     */
+    verify?: boolean;
+    /** Pre-loaded lock, to avoid re-reading it per call. */
+    lock?: BinaryLock;
+}
+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, signal?: AbortSignal): 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 → assert the child is still ours → (optionally)
+ * version-check. On any failure the sidecar is shut down before rethrowing, so a
+ * failed start never leaks a process.
+ *
+ * The port is checked BEFORE the spawn. Without that, the frozen sidecar spends
+ * seconds unpacking before it even attempts its bind, while an incumbent answers
+ * `/health` in milliseconds — so the health wait succeeds, the still-unpacking
+ * child looks alive, and we would hand back a handle for a server we do not own.
+ * `assertOurs` / `assertNotAForeignServer` stay as backstops for the narrower
+ * race where something binds after this check.
+ */
+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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"}