@gaia-ai/core 0.5.5 → 0.6.1

package/dist/src/index.d.ts

@@ -1,13 +1,16 @@
+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 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 * 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 { discoverAddons, type ResolvedConductorSlots, resolveConductorSlots, } from './plugins/discover-addons.js';
+export { type AddonEntry, type CommandDescriptor, type DiscoveredContributions, emptyContributions, type GaiaPreset, type GaiaSurface, type OpaqueAccumulator, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.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,28 @@
+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';
-export { selectAgent, selectAgents } from './plugins/plugins.js';
-export { loadInstructions } from './plugins/workspace/instructions.js';
+// GAIA-215: the Storybook-style preset contract + the shared addon discovery.
+// GAIA-224 (Finding 6): SURFACE-AGNOSTIC only. The conductor-surface interfaces
+// (`GaiaRemote`/`GaiaExecutor`/`GaiaWorkspace`/`GaiaAgent`, the four `*Plugin`
+// interfaces, `ExecutorDeps`, `AgentCandidate`/`ResolvedAgent`, the `select*`
+// selectors), the config contract (`ConductorSettings`/`ConductorFileConfig`/
+// `ConductorEngineConfig`) and every built-in IMPLEMENTATION have moved out of
+// this kernel — the contract to `@gaia-ai/conductor` (subpath
+// `@gaia-ai/conductor/contract`), the impls to their own addons
+// (`@gaia-ai/addon-remote-drupal`, `@gaia-ai/addon-workspace-git`,
+// `@gaia-ai/addon-auth-basic`, `@gaia-ai/addon-fake`). `loadInstructions` moved to
+// `@gaia-ai/addon-workspace-git`. Core ships NO plugin implementations.
+export { discoverAddons, resolveConductorSlots, } from './plugins/discover-addons.js';
+export { emptyContributions, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
+// GAIA-194 AC-2: the agent-host contract (`AgentLaunchHost` / `HostedAgent` /
+// `supportsAgentHost`) is likewise NOT here — it is the TUI renderer's own plugin
+// seam (`@gaia-ai/addon-gaia-ui`), and herdr types its impl locally.
+export { expandLoad, parseStepValues, readSkillWhen, StepContractError, validateLoad, WORKFLOW_STEPS, } from './workflow/step-contract.js';

package/dist/src/plugins/discover-addons.d.ts

@@ -0,0 +1,33 @@
+import type { ConductorLogger } from '../core/logger.js';
+import { type AddonEntry, type DiscoveredContributions, type GaiaSurface } from './preset.js';
+/**
+ * Discover + accumulate the `entries` for one `surface`. `bases` is the
+ * ESLint-style resolution order (config dir → cwd → install). Depth-first over
+ * meta-addon `addons` (children before parent), visited-set keyed by resolved
+ * path + serialized options (dedup + cycle-safe). Returns the accumulated
+ * per-extension-point arrays; singleton resolution is `resolveConductorSlots`.
+ */
+export declare function discoverAddons(entries: AddonEntry[] | undefined, surface: GaiaSurface, bases: string[], opts?: {
+    logger?: ConductorLogger;
+}): Promise<DiscoveredContributions>;
+/**
+ * The resolved conductor slots (last-wins singletons + agent candidate list).
+ * Generic over the four element types so the kernel stays surface-agnostic while
+ * the caller keeps full type-safety: the engine passes its narrowed
+ * `ConductorContributions` (see `@gaia-ai/conductor`'s
+ * `narrowConductorContributions`) and gets `RemotePlugin`/`ExecutorPlugin`/
+ * `WorkspacePlugin`/`AgentCandidate` back.
+ */
+export interface ResolvedConductorSlots<R = unknown, E = unknown, W = unknown, A = unknown> {
+    remote?: R;
+    executor?: E;
+    workspace?: W;
+    agents: A[];
+}
+/** Resolve discovered conductor contributions into the four engine slots. */
+export declare function resolveConductorSlots<R, E, W, A>(contributions: {
+    remotes: R[];
+    executors: E[];
+    workspaces: W[];
+    agents: A[];
+}, logger?: ConductorLogger): ResolvedConductorSlots<R, E, W, A>;

package/dist/src/plugins/discover-addons.js

@@ -0,0 +1,238 @@
+// GAIA-215: addon discovery. One shared `discoverAddons(entries, surface, bases)`
+// called by the conductor loader, the connection loader, and the host — each
+// runs ONLY its surface's accumulators. Resolution reuses the ESLint-style
+// resolver (`resolveModuleEslintStyle`) so an addon named in a config resolves
+// the same way a slot plugin did before (config dir → cwd → install).
+//
+// Ordering / override semantics (Storybook never wrote these down; spec'd here):
+//   1. addons apply in `addons[]` ARRAY ORDER;
+//   2. a preset's `addons` children apply DEPTH-FIRST BEFORE the declaring preset
+//      (a parent overrides its children — essentials-style composition);
+//   3. the user config file is the final preset (its own `addons[]` are the
+//      top-level entries, processed last → it always wins);
+//   4. an EXACT duplicate addon (same resolved path AND same options) is
+//      processed once (visited-set keyed by path + serialized options) and
+//      warned — this also prevents meta-addon cycles and fixes the old one-level
+//      `composePlugins` flatten. The same package with DIFFERENT options is a
+//      legitimate multi-instance (e.g. two oauth2 profiles) and both load.
+// Per entry: resolve → import `<pkg>/preset` (fallback: the package's default
+// export adapted as a single contribution, logged) → run the surface's
+// accumulators with the entry's `with` → for `agents`, attach the entry's
+// `priority`. The runtime `.kind` guard is retained at singleton resolution.
+//
+// GAIA-224 (Finding 6, decision 7): surface-AGNOSTIC. The per-surface
+// accumulators are opaque `unknown[]` here (their element types belong to the
+// surface owner — `@gaia-ai/conductor` for the conductor surface), so this module
+// keeps zero `@gaia-ai/*` edges. Everything it needs from a contribution is
+// structural: the `.kind` tag for the singleton guard, `.id` for the warn line,
+// and `.priority` for the agent-candidate attach.
+import { pathToFileURL } from 'node:url';
+import { resolveModuleEslintStyle } from '../cli/resolve-module.js';
+import { emptyContributions, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './preset.js';
+function warnFrom(logger) {
+    if (logger)
+        return (msg) => logger.warn({}, msg);
+    return (msg) => {
+        console.warn(msg);
+    };
+}
+/** Normalize an `AddonEntry` to `{ spec, opts, priority }`. */
+function normalizeEntry(entry) {
+    if (typeof entry === 'string')
+        return { spec: entry, opts: undefined };
+    const spec = entry.use ?? entry.name;
+    if (typeof spec !== 'string' || spec.trim() === '') {
+        throw new Error(`addons[] entry must name a package via a string or { use } / { name }; got ${JSON.stringify(entry)}`);
+    }
+    return {
+        spec,
+        opts: entry.with ?? entry.options,
+        ...(entry.priority ? { priority: entry.priority } : {}),
+    };
+}
+/** Does an imported module look like a preset (any accumulator fn or `addons`)? */
+function isPresetShaped(mod) {
+    if (Array.isArray(mod.addons))
+        return true;
+    return PRESET_FUNCTION_KEYS.some((k) => typeof mod[k] === 'function');
+}
+/** Pick a module's single factory: the default export, else a sole function. */
+function pickFactory(mod) {
+    if (typeof mod.default === 'function') {
+        return mod.default;
+    }
+    const fns = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
+    if (fns.length === 1)
+        return mod[fns[0]];
+    return undefined;
+}
+/**
+ * Adapt a not-yet-migrated package (no `./preset`, module not preset-shaped) by
+ * constructing its default/sole factory and routing the built plugin into the
+ * surface accumulator matching its `.kind`. Incremental-migration path; logged.
+ * A factory returning an array (dropsh `composePlugins` aggregator) is flattened.
+ */
+function adaptDefaultExport(mod, spec, warn) {
+    const factory = pickFactory(mod);
+    if (!factory) {
+        throw new Error(`addon '${spec}' has no ./preset, is not preset-shaped, and has no default/sole factory to adapt`);
+    }
+    warn(`addon '${spec}' has no ./preset export — adapting its default export (legacy; migrate it to a ./preset, GAIA-215 AC-3)`);
+    return {
+        connectionPlugins: (acc, opts) => {
+            const built = factory(opts);
+            const list = Array.isArray(built) ? built : [built];
+            // Route by kind: only plugins WITHOUT a GAIA engine kind are dropsh
+            // connection plugins; engine kinds are routed by the branches below.
+            const conn = list.filter((p) => !isEngineKind(p.kind));
+            return [
+                ...acc,
+                ...conn,
+            ];
+        },
+        remotes: (acc, opts) => routeByKind(factory, opts, 'remote', acc),
+        executors: (acc, opts) => routeByKind(factory, opts, 'executor', acc),
+        workspaces: (acc, opts) => routeByKind(factory, opts, 'workspace', acc),
+        agents: (acc, opts) => {
+            const built = factory(opts);
+            const list = Array.isArray(built) ? built : [built];
+            const agents = list.filter((p) => p.kind === 'agent');
+            return [...acc, ...agents.map((agent) => ({ agent }))];
+        },
+    };
+}
+function isEngineKind(kind) {
+    return (kind === 'remote' ||
+        kind === 'executor' ||
+        kind === 'workspace' ||
+        kind === 'agent');
+}
+function routeByKind(factory, opts, kind, acc) {
+    const built = factory(opts);
+    const list = Array.isArray(built) ? built : [built];
+    const matching = list.filter((p) => p.kind === kind);
+    return [...acc, ...matching];
+}
+/** Resolve + import the preset for one addon spec. Returns the preset + a stable
+ *  visited key (the resolved module path). */
+async function loadPreset(spec, bases, warn) {
+    // 1. the conventional `<pkg>/preset` subpath.
+    const presetPath = resolveModuleEslintStyle(`${spec}/preset`, bases);
+    if (presetPath !== undefined) {
+        const mod = (await import(pathToFileURL(presetPath).href));
+        if (!isPresetShaped(mod)) {
+            throw new Error(`addon '${spec}' exposes a ./preset that declares no contributions`);
+        }
+        return { preset: mod, key: presetPath };
+    }
+    // 2. the package's main export — either preset-shaped, or a legacy default.
+    const mainPath = resolveModuleEslintStyle(spec, bases);
+    if (mainPath === undefined) {
+        throw new Error(`addons[] cannot resolve addon '${spec}'`);
+    }
+    const mod = (await import(pathToFileURL(mainPath).href));
+    if (isPresetShaped(mod))
+        return { preset: mod, key: mainPath };
+    return { preset: adaptDefaultExport(mod, spec, warn), key: mainPath };
+}
+/** Run one preset's surface accumulators into `acc`, attaching `priority` to any
+ *  newly appended agent candidates. */
+async function applyPreset(preset, opts, priority, surface, acc) {
+    for (const key of SURFACE_KEYS[surface]) {
+        const fn = preset[key];
+        if (typeof fn !== 'function')
+            continue;
+        const before = key === 'agents' ? acc.agents.length : 0;
+        // biome-ignore lint/suspicious/noExplicitAny: heterogeneous per-key arrays
+        acc[key] = await fn(acc[key], opts);
+        if (key === 'agents' && priority) {
+            for (let i = before; i < acc.agents.length; i++) {
+                const c = acc.agents[i];
+                if (!c.priority)
+                    acc.agents[i] = { ...c, priority };
+            }
+        }
+    }
+}
+/**
+ * Discover + accumulate the `entries` for one `surface`. `bases` is the
+ * ESLint-style resolution order (config dir → cwd → install). Depth-first over
+ * meta-addon `addons` (children before parent), visited-set keyed by resolved
+ * path + serialized options (dedup + cycle-safe). Returns the accumulated
+ * per-extension-point arrays; singleton resolution is `resolveConductorSlots`.
+ */
+export async function discoverAddons(entries, surface, bases, opts = {}) {
+    const acc = emptyContributions();
+    if (!Array.isArray(entries) || entries.length === 0)
+        return acc;
+    const warn = warnFrom(opts.logger);
+    const visited = new Set();
+    const walk = async (list) => {
+        for (const entry of list) {
+            const { spec, opts: withOpts, priority } = normalizeEntry(entry);
+            const { preset, key } = await loadPreset(spec, bases, warn);
+            // Dedup on (resolved path + serialized options): an EXACT repeat is a
+            // mistake (skip + warn), but the SAME package with DIFFERENT `with` is a
+            // legitimate multi-instance (e.g. two @dropsh/plugin-oauth2 profiles —
+            // session + pm), so both must load. Cycle-safe: a meta-addon that re-lists
+            // itself with the same options hits the visited key and stops.
+            const dedupKey = `${key}${optionsKey(withOpts)}`;
+            if (visited.has(dedupKey)) {
+                warn(`addon '${spec}' already registered — skipping the exact duplicate`);
+                continue;
+            }
+            visited.add(dedupKey);
+            // Depth-first: meta-addon children apply BEFORE the declaring preset.
+            if (Array.isArray(preset.addons) && preset.addons.length > 0) {
+                await walk(preset.addons);
+            }
+            await applyPreset(preset, withOpts, priority, surface, acc);
+        }
+    };
+    await walk(entries);
+    return acc;
+}
+/** Stable-ish serialization of an addon entry's `with` options for dedup keying.
+ *  Functions collapse to a marker; unserializable values fall back to String(). */
+function optionsKey(opts) {
+    if (opts === undefined)
+        return '';
+    try {
+        return (JSON.stringify(opts, (_k, v) => (typeof v === 'function' ? '[fn]' : v)) ??
+            '');
+    }
+    catch {
+        return String(opts);
+    }
+}
+/** Take the LAST contributor for a singleton slot; warn when >1 competed; run
+ *  the runtime `.kind` guard so a mis-declared contribution still fails loudly. */
+function resolveSingleton(list, kind, logger) {
+    if (list.length === 0)
+        return undefined;
+    const warn = warnFrom(logger);
+    if (list.length > 1) {
+        const ids = list
+            .map((p) => p.id ?? '<?>')
+            .join(', ');
+        warn(`${kind}: ${list.length} addons contributed a ${kind} ([${ids}]); using the last (override wins)`);
+    }
+    const picked = list[list.length - 1];
+    const pickedKind = picked.kind;
+    if (pickedKind !== kind) {
+        throw new Error(`addon contributed a '${String(pickedKind)}' into the ${kind} slot`);
+    }
+    return picked;
+}
+/** Resolve discovered conductor contributions into the four engine slots. */
+export function resolveConductorSlots(contributions, logger) {
+    const remote = resolveSingleton(contributions.remotes, 'remote', logger);
+    const executor = resolveSingleton(contributions.executors, 'executor', logger);
+    const workspace = resolveSingleton(contributions.workspaces, 'workspace', logger);
+    return {
+        ...(remote ? { remote } : {}),
+        ...(executor ? { executor } : {}),
+        ...(workspace ? { workspace } : {}),
+        agents: contributions.agents,
+    };
+}

package/dist/src/plugins/preset.d.ts

@@ -0,0 +1,94 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+/**
+ * A lazy command pointer (moved here from the host, GAIA-201, + `describe`). The
+ * command surface accumulates DESCRIPTORS — never constructed command plugins —
+ * so the host runs every addon's `commands` at boot without importing their
+ * runtime (preserves the GAIA-201 lazy-mount + "gaia --help imports none").
+ */
+export interface CommandDescriptor {
+    /** The subcommand name mounted as `gaia <name> …`. */
+    name: string;
+    /** Module specifier that default- (or `export`-) exports the `GaiaCommandPlugin`. */
+    plugin: string;
+    /** Shown in `gaia --help` even when the plugin is NOT loaded (describe-only stub). */
+    describe: string;
+    /** Named export to pick instead of the module default. */
+    export?: string;
+}
+/** The three surfaces, each named for its config home (surface = file = plugins). */
+export type GaiaSurface = 'command' | 'conductor' | 'connection';
+/**
+ * One entry in an `addons[]` array — a bare package name, or a descriptor naming
+ * the package (`use`, or SB's `name`) plus its `with` options and, for agents, a
+ * static `priority` over the ticket. Never carries a `kind`/`export`: the surface
+ * is decided by which preset function the addon exports; the kind by the
+ * contribution's own `.kind`.
+ */
+export type AddonEntry = string | {
+    /** The addon package (GAIA term). */
+    use?: string;
+    /** Storybook's term for the same field; accepted as an alias. */
+    name?: string;
+    /** Options handed to the addon's accumulators as `opts`. */
+    with?: unknown;
+    /** Alias for `with`. */
+    options?: unknown;
+    /**
+     * Agent-surface only: the static per-ticket priority (see the conductor
+     * surface's `selectAgent`). The ticket type belongs to the conductor
+     * surface, so the kernel types the parameter as `never` — that makes ANY
+     * concretely-typed `(ticket: Ticket) => number` assignable here (a `never`
+     * parameter is contravariantly assignable to every parameter type) while
+     * keeping this module free of a conductor import.
+     */
+    priority?: (ticket: never) => number;
+};
+/**
+ * The accumulated contributions across an `addons[]` list, one array per
+ * extension point. `discoverAddons` populates only the arrays belonging to the
+ * requested surface (the others stay empty) — so a connection load never runs
+ * the conductor accumulators.
+ */
+export interface DiscoveredContributions {
+    commands: CommandDescriptor[];
+    /** Opaque: `RemotePlugin[]` on the conductor surface. */
+    remotes: unknown[];
+    /** Opaque: `ExecutorPlugin[]` on the conductor surface. */
+    executors: unknown[];
+    /** Opaque: `WorkspacePlugin[]` on the conductor surface. */
+    workspaces: unknown[];
+    /** Opaque: `AgentCandidate[]` on the conductor surface. */
+    agents: unknown[];
+    connectionPlugins: DropSHPlugin[];
+}
+/**
+ * An OPAQUE per-surface accumulator. The kernel threads it without knowing its
+ * element type; the surface owner declares the concrete signature (see
+ * `@gaia-ai/conductor`'s `Preset`). `never[]` on the input side is deliberate:
+ * it keeps a concretely-typed accumulator such as
+ * `(acc: RemotePlugin[], opts) => RemotePlugin[]` structurally assignable to
+ * this opaque form, so a conductor-surface `Preset` still satisfies `GaiaPreset`.
+ */
+export type OpaqueAccumulator<O> = (acc: never[], opts: O) => unknown[] | Promise<unknown[]>;
+/** The extension points each surface runs (the preset function names to call). */
+export declare const SURFACE_KEYS: Record<GaiaSurface, Array<keyof DiscoveredContributions>>;
+/**
+ * A preset: named per-surface accumulator functions + a meta-addon `addons`
+ * array. Every accumulator is `(acc, opts) => acc` (sync or async); returning a
+ * new array lets an addon append, replace, or even FILTER a prior contribution
+ * (override semantics — the user config participates as the final preset).
+ */
+export interface GaiaPreset<O = unknown> {
+    /** Meta-addon composition: children apply depth-first BEFORE this preset. */
+    addons?: AddonEntry[];
+    commands?: (acc: CommandDescriptor[], opts: O) => CommandDescriptor[] | Promise<CommandDescriptor[]>;
+    remotes?: OpaqueAccumulator<O>;
+    executors?: OpaqueAccumulator<O>;
+    workspaces?: OpaqueAccumulator<O>;
+    agents?: OpaqueAccumulator<O>;
+    connectionPlugins?: (acc: DropSHPlugin[], opts: O) => DropSHPlugin[] | Promise<DropSHPlugin[]>;
+}
+/** The preset function keys, for shape-detection during discovery. */
+export declare const PRESET_FUNCTION_KEYS: Array<keyof DiscoveredContributions>;
+/** An empty contributions accumulator. */
+export declare function emptyContributions(): DiscoveredContributions;

package/dist/src/plugins/preset.js

@@ -0,0 +1,52 @@
+// GAIA-215: the preset contract — the Storybook-style self-declaration every
+// GAIA addon exposes through its `./preset` export subpath. A preset declares an
+// addon's contributions through named, per-surface ACCUMULATOR functions
+// `(acc, opts) => acc` (Storybook's `managerEntries`/`previewAnnotations` model),
+// plus an `addons` array for meta-addon composition. Each extension point is
+// list-valued; the core discovers presets and threads these accumulators, so a
+// conforming addon needs no per-slot `export:`/kind wiring in config.
+//
+// The three GAIA surfaces (each named for its config home):
+//   - command    → the `@gaia-ai/gaia` host registry (CommandDescriptor[]).
+//   - conductor  → the run engine (remote / executor / workspace / agent).
+//   - connection → dropsh (auth + renderer plugins).
+//
+// Settings (machine_id / project / states / hooks / scheduler) are NEVER
+// preset-contributed — identity must not be composable — so this interface has
+// no such members and an unknown preset export is rejected loudly at discovery.
+//
+// GAIA-224 (Finding 6, decision 7): this module is surface-AGNOSTIC. It knows
+// the accumulator NAMES of every surface (`SURFACE_KEYS`) and the shape of the
+// pure-data command surface (`CommandDescriptor`), but the element types of the
+// CONDUCTOR surface (`RemotePlugin` / `ExecutorPlugin` / `WorkspacePlugin` /
+// `AgentCandidate`, and the `Ticket` an agent priority scores) live in
+// `@gaia-ai/conductor`. Importing them here would give the kernel an
+// `@gaia-ai/*` edge, which the acyclic guard forbids — so those four
+// accumulators are OPAQUE (see `OpaqueAccumulator`) and the concrete view is
+// declared by the surface owner (`@gaia-ai/conductor`'s `Preset`).
+/** The extension points each surface runs (the preset function names to call). */
+export const SURFACE_KEYS = {
+    command: ['commands'],
+    conductor: ['remotes', 'executors', 'workspaces', 'agents'],
+    connection: ['connectionPlugins'],
+};
+/** The preset function keys, for shape-detection during discovery. */
+export const PRESET_FUNCTION_KEYS = [
+    'commands',
+    'remotes',
+    'executors',
+    'workspaces',
+    'agents',
+    'connectionPlugins',
+];
+/** An empty contributions accumulator. */
+export function emptyContributions() {
+    return {
+        commands: [],
+        remotes: [],
+        executors: [],
+        workspaces: [],
+        agents: [],
+        connectionPlugins: [],
+    };
+}

package/dist/src/workflow/step-contract.d.ts

@@ -0,0 +1,119 @@
+/** The workflow states an agent works — the legal `step` values. */
+export declare const WORKFLOW_STEPS: readonly ["qualification", "spec", "diagnose", "coding", "review", "pre_deployment", "post_deployment", "verifying", "summary"];
+export type WorkflowStep = (typeof WORKFLOW_STEPS)[number];
+/** Typed defect raised on the first contract violation. */
+export declare class StepContractError extends Error {
+    constructor(message: string);
+}
+/**
+ * A normalized `when` clause value: a concrete list of allowed values, the
+ * wildcard `'*'` (matches anything), or `undefined` (key omitted — also any).
+ */
+export type WhenValue = string[] | '*' | undefined;
+/** A skill's `when` triple. Any of the three keys may be omitted (= any). */
+export interface SkillWhen {
+    work_type: WhenValue;
+    workflow: WhenValue;
+    step: WhenValue;
+}
+/** One declared input: a value key with a short description and an optional default. */
+export interface InputDecl {
+    /** The value key the skill reads (e.g. `test.command`). */
+    key: string;
+    /** A short human description of what the value is. */
+    description?: string;
+    /** The default used when `WORKFLOW.md` supplies no override for this key. */
+    default?: string;
+}
+/** The parsed contract of a single skill's frontmatter. */
+export interface SkillContract {
+    /** Skill name from frontmatter. */
+    name: string;
+    /**
+     * The `when` triple, or `undefined` when the skill declares no `when` — a
+     * helper/capability skill that owns no step and routes nothing.
+     */
+    when?: SkillWhen;
+    /** The inputs the skill declares (each: key + description + optional default). */
+    inputs: InputDecl[];
+    /**
+     * A **bundle** skill carries its own `## Loaded skills` section in its markdown
+     * **body** — the same list a `WORKFLOW.md` carries. `loads` holds those member
+     * names in declared order. Nothing in the frontmatter marks a bundle; the
+     * section is the marker. Present only on bundles.
+     */
+    loads?: string[];
+    /**
+     * A bundle's member values: the inline `key: value` overrides written under a
+     * member's bullet in the bundle body, keyed by member skill name. Present only
+     * on bundles.
+     */
+    values?: StepValues;
+}
+/**
+ * A concrete `(work_type, workflow, step)` the project can produce. `work_type`
+ * is `null` for a non-work-typed step (qualification, spec, deployment,
+ * verification), a `work:*` label (without the prefix) otherwise.
+ */
+export interface Triple {
+    work_type: string | null;
+    workflow: string;
+    step: WorkflowStep;
+}
+/** Per-skill values, keyed by skill `name` (the `@gaia/` prefix stripped). */
+export type StepValues = Record<string, Record<string, string>>;
+/**
+ * Read the per-skill value **overrides** from a `WORKFLOW.md`'s `## Loaded skills`
+ * section. A project overrides a skill default **inline under that skill's bullet**
+ * (indented `key: value` YAML, block scalars allowed), not in one global block.
+ * Returns a map keyed by skill `name` (the `@gaia/` prefix stripped); a skill with no
+ * overrides maps to `{}` (it runs on its declared defaults).
+ */
+export declare function parseStepValues(workflowMd: string): StepValues;
+/**
+ * Parse a skill's frontmatter into its `SkillContract` — the `when` triple (when
+ * present) and the declared `inputs`. Malformed frontmatter raises `StepContractError`.
+ */
+export declare function readSkillWhen(skillMd: string): SkillContract;
+/** What a load expands to: the flat leaf skills plus the values that reached them. */
+export interface ExpandedLoad {
+    /** The leaf skills (step-owners + helpers), deduplicated, in first-seen order. */
+    skills: SkillContract[];
+    /** The effective per-skill values, keyed by skill name. */
+    values: StepValues;
+}
+/**
+ * Read a `WORKFLOW.md` and expand what it loads into the flat, deduplicated list of
+ * **leaf** skills (step-owners + helpers) the project effectively runs, together with
+ * the values that reach each leaf. One call is the whole load step: parse, expand,
+ * resolve — hand the result straight to `validateLoad`.
+ *
+ * A **bundle** — a skill whose markdown body carries its own `## Loaded skills`
+ * section, so its contract carries `loads` — is recursed into, in its declared
+ * member order; a step-owner or helper is emitted as itself. Leaves are
+ * deduplicated **by name, first occurrence wins**, so the result is deterministic
+ * and idempotent — listing the same bundle twice, or a bundle plus one of its
+ * members as an explicit bullet, yields each leaf exactly once in first-seen order.
+ *
+ * **Value precedence**, narrowest wins: the project's own inline override in
+ * `WORKFLOW.md` beats a bundle's inline value for that member, which beats the
+ * skill's declared `default` (resolved later, in `validateLoad`). Between nested
+ * bundles the outermost wins, matching first-occurrence dedup.
+ *
+ * A root or member name absent from `byName`, or a cycle in the bundle graph,
+ * raises a typed `StepContractError`. Bundles may nest (cycle-safe); gaia ships one
+ * flat level. This never dispatches or routes.
+ */
+export declare function expandLoad(workflowMd: string, byName: Map<string, SkillContract>): ExpandedLoad;
+/**
+ * Validate a loaded set of skills against the project's triple set and per-skill values.
+ *
+ * For every `(work_type, workflow, step)` the project can produce, **exactly one**
+ * loaded skill's `when` must match — a triple with no match (gap) or two matches
+ * (collision) is a configuration error. Every `input` a matched skill declares must
+ * resolve to a value: the `values` map (as resolved by `expandLoad`) or the input's
+ * own declared `default`.
+ *
+ * Reports the first defect as a typed `StepContractError`. Never dispatches or routes.
+ */
+export declare function validateLoad(skills: SkillContract[], values: StepValues, projectTriples: Triple[]): void;