@gaia-ai/core 0.5.4 → 0.6.0

package/dist/src/cli/commands.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from 'commander';
+/**
+ * What the host hands each command plugin at mount time. `resolveBases` is the
+ * ESLint-style base order the plugin passes to `resolveModuleEslintStyle` for
+ * pnpm-safe sibling resolution (renderer, dropsh auth plugins) — the host owns
+ * it because only the host knows its own install location; a plugin resolving
+ * from its own `import.meta.url` breaks under pnpm's isolated store.
+ */
+export interface GaiaCommandHost {
+    /** Base dirs/URLs for ESLint-style module resolution: host install → cwd. */
+    resolveBases: string[];
+}
+/**
+ * A command plugin the host mounts under its `name` (`gaia <name> …`).
+ * `describe` is shown in `gaia --help` even when the plugin is NOT loaded (the
+ * host renders a describe-only stub), so lazy mounting keeps `--help` complete.
+ * `register` receives the top-level `commander` program and the host; it adds
+ * the plugin's subcommand tree.
+ */
+export interface GaiaCommandPlugin {
+    /** GAIA-215: the total-tag discriminant — a command plugin self-identifies its
+     *  surface, like every other GAIA plugin carries a `.kind`. */
+    readonly kind: 'command';
+    name: string;
+    describe: string;
+    register(program: Command, host: GaiaCommandHost): void | Promise<void>;
+}

package/dist/src/cli/commands.js

@@ -0,0 +1 @@
+export {};

package/dist/src/cli/gaia-dir.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
+ * `.gaia/` dir holds at least one conductor config; return that `.gaia/` dir, or
+ * `undefined` if none is found up to the filesystem root.
+ */
+export declare function findGaiaDir(cwd: string): string | undefined;
+/**
+ * Resolve the ENGINE (`conductor.config.js`) config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$GAIA_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.gaia/` dir holding a conductor
+ *    config — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves the stem's
+ *      file (`conductor` → `conductor.config.js`, else `<name>.conductor.config.js`).
+ *    - No selector: `conductor.config.js` present → the default; else exactly
+ *      one config → use it (back-compat); else → error naming the stems.
+ * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error.
+ */
+export declare function resolveConfigPath(override?: string, cwd?: string, conductorName?: string): string;
+/** A resolved connection-config file: its path, whether it is the shipped
+ *  machine-context fallback, and whether it is a legacy `conductor.config.js`. */
+export interface GaiaConfigResolution {
+    path: string;
+    /** true only for the shipped fallback (needs `$GAIA_MACHINE_CONTEXT`). */
+    fallback: boolean;
+    /** true when the resolved file is a legacy `conductor.config.js` connection. */
+    legacy: boolean;
+}
+/**
+ * Walk root-ward for the nearest `.gaia/` connection config: prefer
+ * `gaia.config.js`; fall back to a legacy `conductor.config.js` in the same dir
+ * (back-compat). Returns `undefined` when neither is found up the tree.
+ */
+export declare function findGaiaConfig(cwd: string): {
+    path: string;
+    legacy: boolean;
+} | undefined;
+/**
+ * Resolve the CONNECTION (`gaia.config.js`) config path. Precedence (AC-4):
+ * 1. `explicit` (`--config` / `$GAIA_CONFIG` / `$DROPSH_CONFIG`) wins verbatim.
+ * 2. Project `./.gaia/gaia.config.js` found by walk-up (legacy
+ *    `conductor.config.js` accepted as a connection source).
+ * 3. Home `~/.gaia/gaia.config.js` when present.
+ * 4. The shipped fallback (`homeFallbackGaiaConfigPath`, reads the machine context).
+ */
+export declare function resolveGaiaConfigPath(opts?: {
+    cwd?: string;
+    explicit?: string | undefined;
+    home?: string;
+    shippedFallback?: string;
+}): GaiaConfigResolution;

package/dist/src/cli/gaia-dir.js

@@ -0,0 +1,152 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { homeFallbackGaiaConfigPath } from './paths.js';
+// GAIA-201: the pure `.gaia/` walk-up, hoisted from the conductor's `config.ts`.
+// Two config kinds now live under `.gaia/`:
+//   - ENGINE   `conductor.config.js` (+ `<variant>.conductor.config.js`) —
+//              project-only; resolved by `resolveConfigPath` (unchanged logic).
+//   - CONNECTION `gaia.config.js` — project walk-up → home `~/.gaia/gaia.config.js`
+//              → shipped fallback; resolved by `resolveGaiaConfigPath`. A legacy
+//              `conductor.config.js` still carrying `site`/`plugins` is accepted
+//              as a connection source (back-compat) when no `gaia.config.js` is
+//              found, so an un-migrated repo keeps working.
+/** A repo's config files live in this dir, one conductor config per conductor. */
+const GAIA_DIR = '.gaia';
+/** The default conductor's file name; its stem is `conductor`. */
+const DEFAULT_CONFIG = 'conductor.config.js';
+/** Variant files are `<stem>.conductor.config.js`. */
+const VARIANT_SUFFIX = '.conductor.config.js';
+/** The connection config file name (project + home). */
+const GAIA_CONFIG = 'gaia.config.js';
+/**
+ * List the conductor-config stems in a `.gaia/` dir. A file is a conductor
+ * config iff it is exactly `conductor.config.js` (stem `conductor`, the
+ * default) or ends with `.conductor.config.js` (stem = the leading part).
+ * Every other file (`vite.config.js`, the near-miss `myconductor.config.js`,
+ * and `gaia.config.js` itself) is ignored.
+ */
+function configStems(gaiaDir) {
+    return readdirSync(gaiaDir)
+        .map((f) => f === DEFAULT_CONFIG
+        ? 'conductor'
+        : f.endsWith(VARIANT_SUFFIX)
+            ? f.slice(0, -VARIANT_SUFFIX.length)
+            : undefined)
+        .filter((s) => s !== undefined)
+        .sort();
+}
+/** Map a conductor stem back to its file name. */
+function fileForStem(stem) {
+    return stem === 'conductor' ? DEFAULT_CONFIG : `${stem}${VARIANT_SUFFIX}`;
+}
+/**
+ * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
+ * `.gaia/` dir holds at least one conductor config; return that `.gaia/` dir, or
+ * `undefined` if none is found up to the filesystem root.
+ */
+export function findGaiaDir(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const gaiaDir = join(dir, GAIA_DIR);
+        if (existsSync(gaiaDir) && configStems(gaiaDir).length > 0) {
+            return gaiaDir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Resolve the ENGINE (`conductor.config.js`) config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$GAIA_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.gaia/` dir holding a conductor
+ *    config — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves the stem's
+ *      file (`conductor` → `conductor.config.js`, else `<name>.conductor.config.js`).
+ *    - No selector: `conductor.config.js` present → the default; else exactly
+ *      one config → use it (back-compat); else → error naming the stems.
+ * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error.
+ */
+export function resolveConfigPath(override, cwd = process.cwd(), conductorName) {
+    const explicit = override ?? process.env.GAIA_CONDUCTOR_CONFIG;
+    if (explicit) {
+        return explicit;
+    }
+    const gaiaDir = findGaiaDir(cwd);
+    if (gaiaDir === undefined) {
+        throw new Error(`no .gaia/conductor.config.js found from ${cwd} upward; run \`gaia init\``);
+    }
+    const stems = configStems(gaiaDir);
+    const name = conductorName ?? process.env.GAIA_CONDUCTOR;
+    if (name !== undefined && name !== '') {
+        const candidate = join(gaiaDir, fileForStem(name));
+        if (!existsSync(candidate)) {
+            throw new Error(`no conductor '${name}' in ${gaiaDir}; available: ${stems.join(', ')}`);
+        }
+        return candidate;
+    }
+    if (stems.includes('conductor')) {
+        return join(gaiaDir, DEFAULT_CONFIG);
+    }
+    if (stems.length === 1) {
+        return join(gaiaDir, fileForStem(stems[0]));
+    }
+    throw new Error(`${stems.length} conductors in ${gaiaDir} (${stems.join(', ')}); ` +
+        'select one with --conductor <name> or $GAIA_CONDUCTOR');
+}
+/**
+ * Walk root-ward for the nearest `.gaia/` connection config: prefer
+ * `gaia.config.js`; fall back to a legacy `conductor.config.js` in the same dir
+ * (back-compat). Returns `undefined` when neither is found up the tree.
+ */
+export function findGaiaConfig(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const gaiaDir = join(dir, GAIA_DIR);
+        if (existsSync(gaiaDir)) {
+            const gaiaCfg = join(gaiaDir, GAIA_CONFIG);
+            if (existsSync(gaiaCfg))
+                return { path: gaiaCfg, legacy: false };
+            const legacy = join(gaiaDir, DEFAULT_CONFIG);
+            if (existsSync(legacy))
+                return { path: legacy, legacy: true };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Resolve the CONNECTION (`gaia.config.js`) config path. Precedence (AC-4):
+ * 1. `explicit` (`--config` / `$GAIA_CONFIG` / `$DROPSH_CONFIG`) wins verbatim.
+ * 2. Project `./.gaia/gaia.config.js` found by walk-up (legacy
+ *    `conductor.config.js` accepted as a connection source).
+ * 3. Home `~/.gaia/gaia.config.js` when present.
+ * 4. The shipped fallback (`homeFallbackGaiaConfigPath`, reads the machine context).
+ */
+export function resolveGaiaConfigPath(opts = {}) {
+    const explicit = opts.explicit;
+    if (explicit !== undefined && explicit.trim() !== '') {
+        return { path: explicit, fallback: false, legacy: false };
+    }
+    const cwd = opts.cwd ?? process.cwd();
+    const project = findGaiaConfig(cwd);
+    if (project !== undefined) {
+        return { path: project.path, fallback: false, legacy: project.legacy };
+    }
+    const home = opts.home ?? homedir();
+    const homeCfg = join(home, GAIA_DIR, GAIA_CONFIG);
+    if (existsSync(homeCfg)) {
+        return { path: homeCfg, fallback: false, legacy: false };
+    }
+    return {
+        path: opts.shippedFallback ?? homeFallbackGaiaConfigPath(),
+        fallback: true,
+        legacy: false,
+    };
+}

package/dist/src/cli/load-gaia-config.d.ts

@@ -0,0 +1,25 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { GaiaCommandHost } from './commands.js';
+/** The resolved control-plane connection: site + constructed auth plugins. */
+export interface GaiaConnectionConfig {
+    site: {
+        base_url: string;
+        jsonapi_prefix: string;
+    };
+    plugins: DropSHPlugin[];
+    /** Absolute path of the loaded connection config. */
+    config_path: string;
+    /** true when this is the shipped machine-context fallback. */
+    fallback: boolean;
+}
+/**
+ * Load the connection config for `gaia ui` / `gaia dropsh` / conductor-auth.
+ * Resolves the path (explicit → project walk-up → home → shipped fallback),
+ * sets `$GAIA_MACHINE_CONTEXT` before importing the shipped fallback, imports
+ * the module, reads ONLY `{ site, plugins }` (a legacy `conductor.config.js` is
+ * read the same way), and constructs the auth `plugins[]`.
+ */
+export declare function loadGaiaConfig(host: GaiaCommandHost, opts?: {
+    cwd?: string;
+    explicit?: string | undefined;
+}): Promise<GaiaConnectionConfig>;

package/dist/src/cli/load-gaia-config.js

@@ -0,0 +1,110 @@
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { discoverAddons } from '../plugins/discover-addons.js';
+import { resolveGaiaConfigPath } from './gaia-dir.js';
+import { resolveMachineContextPath } from './machine-context.js';
+import { resolveModuleEslintStyle } from './resolve-module.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPluginDescriptor(entry) {
+    return isRecord(entry) && typeof entry.plugin === 'string';
+}
+/**
+ * Construct a `{ plugin, export?, with?/options? }` descriptor. Resolution base
+ * order: the config's own dir first (so a project config can name a locally
+ * installed plugin), then the host's `resolveBases` (host install → cwd) for
+ * pnpm-safe resolution of the shipped fallback's `@dropsh/plugin-*`.
+ */
+async function loadDescriptor(entry, bases) {
+    const resolved = resolveModuleEslintStyle(entry.plugin, bases);
+    if (resolved === undefined) {
+        throw new Error(`gaia.config.js cannot resolve plugin '${entry.plugin}'`);
+    }
+    const mod = (await import(pathToFileURL(resolved).href));
+    let factory;
+    if (typeof entry.export === 'string') {
+        factory = mod[entry.export];
+        if (typeof factory !== 'function') {
+            throw new Error(`plugin '${entry.plugin}' has no callable export '${entry.export}'`);
+        }
+    }
+    else if (typeof mod.default === 'function') {
+        factory = mod.default;
+    }
+    else {
+        const fns = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
+        if (fns.length === 1) {
+            factory = mod[fns[0]];
+        }
+        else {
+            throw new Error(`plugin '${entry.plugin}' has no default export and ${fns.length} function exports (${fns.join(', ')}); specify "export"`);
+        }
+    }
+    return factory(entry.with ?? entry.options);
+}
+/** Resolve the `plugins[]` array: descriptors constructed, constructed entries
+ *  passed through; a factory returning an array is flattened one level (dropsh
+ *  `composePlugins` semantics), mirroring the engine loader. */
+async function resolvePlugins(raw, bases) {
+    if (!Array.isArray(raw))
+        return [];
+    const resolved = await Promise.all(raw.map((entry) => isPluginDescriptor(entry) ? loadDescriptor(entry, bases) : entry));
+    return resolved.flat();
+}
+/**
+ * Load the connection config for `gaia ui` / `gaia dropsh` / conductor-auth.
+ * Resolves the path (explicit → project walk-up → home → shipped fallback),
+ * sets `$GAIA_MACHINE_CONTEXT` before importing the shipped fallback, imports
+ * the module, reads ONLY `{ site, plugins }` (a legacy `conductor.config.js` is
+ * read the same way), and constructs the auth `plugins[]`.
+ */
+export async function loadGaiaConfig(host, opts = {}) {
+    const resolution = resolveGaiaConfigPath({
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        explicit: opts.explicit,
+    });
+    const configPath = resolve(resolution.path);
+    // The shipped fallback derives the connection from the machine context, which
+    // it reads via this env var. Set it (canonical path) unless already set.
+    if (resolution.fallback && !process.env.GAIA_MACHINE_CONTEXT) {
+        // Prefer the canonical ~/.gaia/machine.config.js; fall back to the legacy
+        // path on an un-migrated machine so the shipped fallback still finds it.
+        process.env.GAIA_MACHINE_CONTEXT = resolveMachineContextPath();
+    }
+    const module = (await import(pathToFileURL(configPath).href));
+    const raw = module.default;
+    if (!isRecord(raw)) {
+        throw new Error(`gaia connection config default export must be an object (${configPath})`);
+    }
+    const site = isRecord(raw.site) ? raw.site : {};
+    const baseUrl = typeof site.base_url === 'string' ? site.base_url : '';
+    if (baseUrl.trim() === '') {
+        throw new Error(`gaia connection config requires site.base_url (${configPath})`);
+    }
+    const jsonapiPrefix = typeof site.jsonapi_prefix === 'string' && site.jsonapi_prefix.trim() !== ''
+        ? site.jsonapi_prefix
+        : '/jsonapi';
+    // Config dir first, then the host bases (pnpm-safe for the shipped fallback).
+    const bases = [
+        pathToFileURL(`${dirname(configPath)}/`).href,
+        ...host.resolveBases,
+    ];
+    // GAIA-215: the connection surface has TWO input forms that both still load —
+    // the legacy `plugins:[]` descriptor array AND the Storybook-style `addons:[]`
+    // discovered via the shared engine (connection surface = the auth/renderer
+    // plugins). Concatenate legacy first, then discovered.
+    const legacy = await resolvePlugins(raw.plugins, bases);
+    const discovered = Array.isArray(raw.addons)
+        ? await discoverAddons(raw.addons, 'connection', bases)
+        : undefined;
+    const plugins = discovered
+        ? [...legacy, ...discovered.connectionPlugins]
+        : legacy;
+    return {
+        site: { base_url: baseUrl, jsonapi_prefix: jsonapiPrefix },
+        plugins,
+        config_path: configPath,
+        fallback: resolution.fallback,
+    };
+}

package/dist/src/cli/machine-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The user-global machine context: identity + connection (incl. the OAuth
+ * client secret). Committed configs compose `machine_id` from it and read
+ * base_url / client_id / client_secret. Gitignored, user-only (chmod 0600).
+ */
+export interface MachineContext {
+    machine_id: string;
+    user_id: string;
+    base_url: string;
+    client_id: string;
+    client_secret: string;
+}
+/** Canonical machine-context path: `~/.gaia/machine.config.js` (GAIA-201). */
+export declare function machineContextPath(): string;
+/** Legacy machine-context path (pre-GAIA-201), read as a fallback. */
+export declare function legacyMachineContextPath(): string;
+/**
+ * Resolve the machine-context path to read: the caller's explicit `path`, else
+ * the canonical `~/.gaia/machine.config.js` when it exists, else the legacy
+ * path. This is the single place the read-time canonical→legacy fallback lives.
+ */
+export declare function resolveMachineContextPath(path?: string): string;
+/** Import an existing context module's default export, or `{}` if absent/broken. */
+export declare function readMachineContext(path?: string): Promise<Partial<MachineContext>>;

package/dist/src/cli/machine-context.js

@@ -0,0 +1,45 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Canonical machine-context path: `~/.gaia/machine.config.js` (GAIA-201). */
+export function machineContextPath() {
+    return join(homedir(), '.gaia', 'machine.config.js');
+}
+/** Legacy machine-context path (pre-GAIA-201), read as a fallback. */
+export function legacyMachineContextPath() {
+    return join(homedir(), '.config', 'conductor', 'conductor.config.machine.js');
+}
+/**
+ * Resolve the machine-context path to read: the caller's explicit `path`, else
+ * the canonical `~/.gaia/machine.config.js` when it exists, else the legacy
+ * path. This is the single place the read-time canonical→legacy fallback lives.
+ */
+export function resolveMachineContextPath(path) {
+    if (path !== undefined && path !== '')
+        return path;
+    const canonical = machineContextPath();
+    if (existsSync(canonical))
+        return canonical;
+    const legacy = legacyMachineContextPath();
+    if (existsSync(legacy))
+        return legacy;
+    return canonical;
+}
+/** Import an existing context module's default export, or `{}` if absent/broken. */
+export async function readMachineContext(path) {
+    const resolved = resolveMachineContextPath(path);
+    if (!existsSync(resolved))
+        return {};
+    try {
+        // Cache-bust so a re-render within one process re-reads fresh.
+        const mod = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
+        const raw = mod.default;
+        return raw && typeof raw === 'object'
+            ? raw
+            : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/src/cli/paths.d.ts

@@ -0,0 +1,11 @@
+/** Walk from this module to the `@gaia-ai/core` package root (first ancestor
+ *  holding a `package.json`). Works from `src/` (dev) and `dist/` (built). */
+export declare function corePackageRoot(): string;
+/**
+ * The shipped fallback connection config. It reads the machine context named by
+ * `$GAIA_MACHINE_CONTEXT` for base_url + credentials and constructs a `session`
+ * oauth2 plugin, so a home-rooted `gaia ui` / `gaia dropsh` works with no
+ * hand-authored config. `loadGaiaConfig` sets `$GAIA_MACHINE_CONTEXT` before
+ * importing it.
+ */
+export declare function homeFallbackGaiaConfigPath(): string;

package/dist/src/cli/paths.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// GAIA-201: filesystem anchors for the split config model. Core ships the
+// fallback connection config `gaia.config.js` (used home-rooted when neither a
+// project nor a home `~/.gaia/gaia.config.js` exists), so it must be able to
+// find its own package root in both `src/` (dev via tsx) and `dist/` (built).
+/** Walk from this module to the `@gaia-ai/core` package root (first ancestor
+ *  holding a `package.json`). Works from `src/` (dev) and `dist/` (built). */
+export function corePackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error('@gaia-ai/core package root not found');
+        }
+        dir = parent;
+    }
+}
+/**
+ * The shipped fallback connection config. It reads the machine context named by
+ * `$GAIA_MACHINE_CONTEXT` for base_url + credentials and constructs a `session`
+ * oauth2 plugin, so a home-rooted `gaia ui` / `gaia dropsh` works with no
+ * hand-authored config. `loadGaiaConfig` sets `$GAIA_MACHINE_CONTEXT` before
+ * importing it.
+ */
+export function homeFallbackGaiaConfigPath() {
+    return join(corePackageRoot(), 'gaia.config.js');
+}

package/dist/src/cli/resolve-module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve `spec` against `bases`, ESLint-style: the first base whose
+ * `createRequire(base).resolve(spec)` succeeds wins; returns that absolute
+ * filesystem path. Returns `undefined` when no base resolves it.
+ */
+export declare function resolveModuleEslintStyle(spec: string, bases: string[]): string | undefined;

package/dist/src/cli/resolve-module.js

@@ -0,0 +1,24 @@
+import { createRequire } from 'node:module';
+// GAIA-201: the ESLint-style module resolver, hoisted from the conductor's
+// `config.ts` (`loadNamedPlugin`). A plugin name is resolved by trying each base
+// in order (config dir → cwd → install) and returning the first
+// `createRequire(base).resolve(name)` that succeeds. Bases are node module
+// parents — an absolute file path OR a `file://` URL string; both are accepted
+// by `createRequire`. Keeping this pure + shared lets the host, the connection
+// loader, and the engine plugin loader all resolve identically.
+/**
+ * Resolve `spec` against `bases`, ESLint-style: the first base whose
+ * `createRequire(base).resolve(spec)` succeeds wins; returns that absolute
+ * filesystem path. Returns `undefined` when no base resolves it.
+ */
+export function resolveModuleEslintStyle(spec, bases) {
+    for (const base of bases) {
+        try {
+            return createRequire(base).resolve(spec);
+        }
+        catch {
+            // try the next base
+        }
+    }
+    return undefined;
+}

package/dist/src/conductor-registry/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One registered conductor in the local machine registry
+ * (`${GAIA_HOME ?? ~}/.gaia/conductors.json`). The registry is inherently
+ * machine + user scoped: it lists the conductors this user can drive locally.
+ */
+export interface ConductorRegistryEntry {
+    id: string;
+    path: string;
+    project: string;
+    label: string;
+    host: 'herdr' | 'process' | 'systemd';
+    handle: string;
+}
+/** `${GAIA_HOME ?? ~}/.gaia/conductors.json`. */
+export declare function conductorRegistryPath(): string;
+/** All registered conductors, in insertion order. */
+export declare function listRegisteredConductors(): Promise<ConductorRegistryEntry[]>;
+/** One registered conductor by id, or `null` when absent. */
+export declare function getRegisteredConductor(id: string): Promise<ConductorRegistryEntry | null>;
+/** Insert or overwrite a conductor by id (idempotent). */
+export declare function registerConductor(entry: ConductorRegistryEntry): Promise<void>;
+/** Remove a conductor by id; a no-op when it is not present. */
+export declare function removeConductor(id: string): Promise<void>;

package/dist/src/conductor-registry/index.js

@@ -0,0 +1,59 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** `${GAIA_HOME ?? ~}/.gaia/conductors.json`. */
+export function conductorRegistryPath() {
+    const home = process.env.GAIA_HOME ?? homedir();
+    return join(home, '.gaia', 'conductors.json');
+}
+async function read() {
+    let raw;
+    try {
+        raw = await readFile(conductorRegistryPath(), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim() === '') {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+async function write(data) {
+    const path = conductorRegistryPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+/** All registered conductors, in insertion order. */
+export async function listRegisteredConductors() {
+    return Object.values(await read());
+}
+/** One registered conductor by id, or `null` when absent. */
+export async function getRegisteredConductor(id) {
+    return (await read())[id] ?? null;
+}
+/** Insert or overwrite a conductor by id (idempotent). */
+export async function registerConductor(entry) {
+    const data = await read();
+    data[entry.id] = entry;
+    await write(data);
+}
+/** Remove a conductor by id; a no-op when it is not present. */
+export async function removeConductor(id) {
+    const data = await read();
+    if (data[id]) {
+        delete data[id];
+        await write(data);
+    }
+}

package/dist/src/index.d.ts

@@ -1,13 +1,24 @@
+export type { GaiaCommandHost, GaiaCommandPlugin } from './cli/commands.js';
+export type { GaiaConfigResolution } from './cli/gaia-dir.js';
+export { findGaiaConfig, findGaiaDir, resolveConfigPath, resolveGaiaConfigPath, } from './cli/gaia-dir.js';
+export { type GaiaConnectionConfig, loadGaiaConfig, } from './cli/load-gaia-config.js';
+export { legacyMachineContextPath, type MachineContext, machineContextPath, readMachineContext, resolveMachineContextPath, } from './cli/machine-context.js';
+export { corePackageRoot, homeFallbackGaiaConfigPath, } from './cli/paths.js';
+export { resolveModuleEslintStyle } from './cli/resolve-module.js';
+export { type ConductorRegistryEntry, conductorRegistryPath, getRegisteredConductor, listRegisteredConductors, registerConductor, removeConductor, } from './conductor-registry/index.js';
 export { conductorId } from './core/conductor-id.js';
 export { CommandRunner, ExecError, exec, setDefaultCommandRunner, } from './core/exec.js';
 export { type ConductorLogger, createLogger } from './core/logger.js';
 export { shellQuote } from './core/shell.js';
 export { DEFAULT_SLUG_MAX_LENGTH, slugify } from './core/slug.js';
 export { type AgentFootprint, emptyAgentFootprint, type GaiaAgent, } from './plugins/agent/agent.js';
+export { discoverAddons, type ResolvedConductorSlots, resolveConductorSlots, } from './plugins/discover-addons.js';
 export type * from './plugins/executor/executor.js';
 export type { AgentCandidate, AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, ResolvedAgent, WorkspacePlugin, } from './plugins/plugins.js';
 export { selectAgent, selectAgents } from './plugins/plugins.js';
+export { type AddonEntry, type CommandDescriptor, type DiscoveredContributions, emptyContributions, type GaiaPreset, type GaiaSurface, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
 export type * from './plugins/remote/remote.js';
 export { loadInstructions } from './plugins/workspace/instructions.js';
 export type { EnsuredWorkspace, GaiaWorkspace, } from './plugins/workspace/workspace.js';
 export type * from './types.js';
+export { type ExpandedLoad, expandLoad, type InputDecl, parseStepValues, readSkillWhen, type SkillContract, type SkillWhen, StepContractError, type StepValues, type Triple, validateLoad, type WhenValue, WORKFLOW_STEPS, type WorkflowStep, } from './workflow/step-contract.js';

package/dist/src/index.js

@@ -1,8 +1,22 @@
+export { findGaiaConfig, findGaiaDir, resolveConfigPath, resolveGaiaConfigPath, } from './cli/gaia-dir.js';
+export { loadGaiaConfig, } from './cli/load-gaia-config.js';
+export { legacyMachineContextPath, machineContextPath, readMachineContext, resolveMachineContextPath, } from './cli/machine-context.js';
+export { corePackageRoot, homeFallbackGaiaConfigPath, } from './cli/paths.js';
+export { resolveModuleEslintStyle } from './cli/resolve-module.js';
+export { conductorRegistryPath, getRegisteredConductor, listRegisteredConductors, registerConductor, removeConductor, } from './conductor-registry/index.js';
 export { conductorId } from './core/conductor-id.js';
 export { CommandRunner, ExecError, exec, setDefaultCommandRunner, } from './core/exec.js';
 export { createLogger } from './core/logger.js';
 export { shellQuote } from './core/shell.js';
 export { DEFAULT_SLUG_MAX_LENGTH, slugify } from './core/slug.js';
 export { emptyAgentFootprint, } from './plugins/agent/agent.js';
+// GAIA-215: the Storybook-style preset contract + the shared addon discovery.
+export { discoverAddons, resolveConductorSlots, } from './plugins/discover-addons.js';
 export { selectAgent, selectAgents } from './plugins/plugins.js';
+export { emptyContributions, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
+// GAIA-194 AC-2: the agent-host contract (`AgentLaunchHost` / `HostedAgent` /
+// `supportsAgentHost`) moved OUT of core — it is the TUI renderer's own plugin
+// seam (`@gaia-ai/plugin-gaia-ui`), and herdr types its impl locally. Core is
+// the conductor engine contract only.
 export { loadInstructions } from './plugins/workspace/instructions.js';
+export { expandLoad, parseStepValues, readSkillWhen, StepContractError, validateLoad, WORKFLOW_STEPS, } from './workflow/step-contract.js';