@gaia-ai/conductor 0.0.1

package/dist/src/config.js

@@ -0,0 +1,277 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
+ * the agent must stop instead of running the whole flow in one session. The run
+ * is closed automatically when the ticket state changes on the next claim - the
+ * agent does not release it. Run mechanics live here (not in the repo's
+ * WORKFLOW.md). The prompt routes through the gaia skill (`ticket:run`) rather
+ * than pointing at WORKFLOW.md directly (GAIA-125): the intake splash + state
+ * engine are a skill mechanic, so a bare "follow WORKFLOW.md" pointer left the
+ * splash unrendered unless an external skill-forcing hook happened to fire. A
+ * conductor config may override via the `prompt` field.
+ *
+ * The ticket + its comments are NOT embedded (GAIA-112): embedding unbounded
+ * ticket content into a single typed pane line overran the PTY canonical line
+ * cap and truncated the dispatch command. Instead the prompt is a bounded,
+ * constant-size pointer and the agent reads the ticket + all comments at run
+ * start via `gaia dropsh read … --include comments`.
+ *
+ * HINT — the canonical cap is platform-specific: MAX_CANON is 4096 B on Linux
+ * but only 1024 B on macOS (a whole line >= 1024 B is silently DROPPED there).
+ * herdr types env-prefix + this prompt + flags as ONE line, so keep the total
+ * well under 1024 B — i.e. keep this prompt short (~a few hundred bytes). Do NOT
+ * grow it back toward the old ~1 KB, or macOS dispatch truncates silently again.
+ *
+ * The prompt is a SINGLE LINE — no newlines, no control chars (GAIA-128). herdr
+ * types it into the pane as one line, so a newline would submit early and any
+ * control char would force bash-only `$'…'` quoting that fish can't parse.
+ * Being single-line + bounded, plain `'…'` shell-quoting suffices (fish-safe)
+ * and the typed line stays well under the cap (1024 B on macOS, 4096 B on Linux)
+ * — so NO base64/`bash -c` wrapper and NO multiline handling are needed (that
+ * wrapper, GAIA-118, was the thing that re-inflated the line past the cap and
+ * truncated it mid-quote).
+ * Placeholders: `{identifier}`, `{state}`, `{runUuid}` ({state} falls back to
+ * `triage` for unclassified tickets).
+ */
+export const DEFAULT_AGENT_PROMPT = `You are a GAIA agent working ticket {identifier}, current state: {state}. ` +
+    `Invoke the gaia skill and run \`ticket:run {identifier} {state}\` — it first ` +
+    `reads the ticket + all comments ` +
+    `(gaia dropsh read gaia_ticket/gaia_ticket/$GAIA_ID --include comments), ` +
+    `renders the intake splash, runs the {state} engine, and applies ` +
+    `WORKFLOW.md's {state} policy. Do ONLY the {state} work — never start or ` +
+    `prepare a later state. When done, or if you are blocked, STOP and run /exit.`;
+function requirePlugin(value, kind) {
+    if (!isRecord(value) || value.kind !== kind) {
+        throw new Error(`conductor config requires a ${kind} plugin in the "${kind}" slot`);
+    }
+    return value;
+}
+/**
+ * A named-plugin descriptor `{ plugin, export?, with?/options? }` — the
+ * import-free form. `config.ts` resolves it into a constructed plugin, so a
+ * committed conductor.config.js need not `import` its plugin packages (which
+ * would resolve relative to the config file, not the CLI — the source of the
+ * "unknown command dropsh" breakage after the @gaia → @gaia-ai scope rename).
+ * Mirror of dropsh 0.4.1 `loadNamedPlugin` / `resolveSlot`.
+ */
+function isPluginDescriptor(entry) {
+    return isRecord(entry) && typeof entry.plugin === 'string';
+}
+/**
+ * Resolve + construct a descriptor. Resolution base order, ESLint-style:
+ * config dir → cwd → conductor install (`import.meta.url`) — the first
+ * `createRequire(base).resolve(name)` that succeeds wins. Then `import` the
+ * module, pick `export` (default 'default'), and call the factory with
+ * `with` (falling back to `options`).
+ */
+async function loadNamedPlugin(entry, configPath) {
+    const bases = [
+        pathToFileURL(configPath).href,
+        pathToFileURL(`${process.cwd()}/`).href,
+        import.meta.url,
+    ];
+    let resolved;
+    for (const base of bases) {
+        try {
+            resolved = createRequire(base).resolve(entry.plugin);
+            break;
+        }
+        catch {
+            // try the next base
+        }
+    }
+    if (resolved === undefined) {
+        throw new Error(`conductor config 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 a slot value: a descriptor is constructed via `loadNamedPlugin`, an
+ * already-constructed plugin passes straight through (backward-compat). Either
+ * way the kind-guard runs, so a wrong-target descriptor still errors.
+ */
+async function resolveSlot(value, kind, configPath) {
+    const resolved = isPluginDescriptor(value)
+        ? await loadNamedPlugin(value, configPath)
+        : value;
+    return requirePlugin(resolved, kind);
+}
+/**
+ * Resolve the `plugins[]` array: descriptor entries are constructed, already-
+ * constructed entries pass through. No kind-guard (plugins are not slotted).
+ *
+ * A factory may return one plugin OR an array of plugins — an aggregator built
+ * with dropsh's `composePlugins(a(), b())` returns the flat child list. dropsh's
+ * own `loadConfig` flattens such a nested entry one level; we mirror that here so
+ * `buildProgram({ plugins })` — which reads each entry's hooks/renderers per
+ * top-level element and does NOT recurse — sees every child.
+ */
+async function resolvePlugins(raw, configPath) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const resolved = await Promise.all(raw.map((entry) => isPluginDescriptor(entry) ? loadNamedPlugin(entry, configPath) : entry));
+    return resolved.flat();
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(value, key) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`conductor config requires non-empty ${key}`);
+    }
+    return value;
+}
+function optionalPositiveInteger(value, fallback, key) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`conductor config requires positive integer ${key}`);
+    }
+    return value;
+}
+/** A repo's config files live in this dir, one `<stem>.config.js` per conductor. */
+const GAIA_DIR = '.gaia';
+/** List the `*.config.js` stems in a `.gaia/` dir (e.g. `shop.config.js` → `shop`). */
+function configStems(gaiaDir) {
+    return readdirSync(gaiaDir)
+        .filter((f) => f.endsWith('.config.js'))
+        .map((f) => f.slice(0, -'.config.js'.length))
+        .sort();
+}
+/**
+ * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
+ * `.gaia/` dir holds at least one `*.config.js`; return that `.gaia/` dir, or
+ * `undefined` if none is found up to the filesystem root.
+ */
+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 conductor 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 `*.config.js`
+ *    — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves
+ *      `<gaiaDir>/<name>.config.js` (error listing the stems if absent).
+ *    - No selector: exactly one config → use it (back-compat: the lone
+ *      `conductor.config.js`); many → error naming the stems + the selector.
+ * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error
+ *    (never leak a raw "Cannot find module" from a later import()).
+ */
+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, `${name}.config.js`);
+        if (!existsSync(candidate)) {
+            throw new Error(`no conductor '${name}' in ${gaiaDir}; available: ${stems.join(', ')}`);
+        }
+        return candidate;
+    }
+    if (stems.length === 1) {
+        return join(gaiaDir, `${stems[0]}.config.js`);
+    }
+    throw new Error(`${stems.length} conductors in ${gaiaDir} (${stems.join(', ')}); ` +
+        'select one with --conductor <name> or $GAIA_CONDUCTOR');
+}
+export async function loadConductorConfig(configFile) {
+    const configPath = resolve(configFile);
+    const module = (await import(pathToFileURL(configPath).href));
+    const raw = module.default;
+    if (!isRecord(raw)) {
+        throw new Error('conductor config default export must be an object');
+    }
+    const config = raw;
+    const site = isRecord(config.site) ? config.site : {};
+    const baseUrl = requireNonEmptyString(site.base_url, 'site.base_url');
+    const project = requireNonEmptyString(config.project, 'project');
+    if (!Array.isArray(config.states) || config.states.length === 0) {
+        throw new Error('conductor config requires non-empty states');
+    }
+    const states = config.states.map((state) => requireNonEmptyString(state, 'states'));
+    // machine_id is required — the config MUST set it; there is no derived
+    // fallback. The id is defined in a single place (config.machine_id), which
+    // the CLI lifecycle commands and registration all read, never re-derive. The
+    // conductor label defaults to it (a conductor is identified by it). A repo's
+    // committed config composes it from the machine context
+    // (`${user_id}-${machine_id}-${project}`); with several named configs in one
+    // .gaia/ (GAIA-126) each composes its own from its own project, so co-located
+    // conductors get distinct identities with no filename-based fallback.
+    const machineId = requireNonEmptyString(config.machine_id, 'machine_id');
+    const label = typeof config.label === 'string' && config.label.trim() !== ''
+        ? config.label
+        : machineId;
+    return {
+        site: {
+            base_url: baseUrl,
+            jsonapi_prefix: typeof site.jsonapi_prefix === 'string' &&
+                site.jsonapi_prefix.trim() !== ''
+                ? site.jsonapi_prefix
+                : '/jsonapi',
+        },
+        ...(Array.isArray(config.plugins)
+            ? { plugins: await resolvePlugins(config.plugins, configPath) }
+            : {}),
+        remote: await resolveSlot(config.remote, 'remote', configPath),
+        executor: await resolveSlot(config.executor, 'executor', configPath),
+        agent: await resolveSlot(config.agent, 'agent', configPath),
+        workspace: await resolveSlot(config.workspace, 'workspace', configPath),
+        label,
+        machine_id: machineId,
+        project,
+        states,
+        prompt: typeof config.prompt === 'string' && config.prompt.trim() !== ''
+            ? config.prompt
+            : DEFAULT_AGENT_PROMPT,
+        max_parallel: optionalPositiveInteger(config.max_parallel, 1, 'max_parallel'),
+        poll_interval_ms: optionalPositiveInteger(config.poll_interval_ms, 5000, 'poll_interval_ms'),
+        lease_seconds: optionalPositiveInteger(config.lease_seconds, 300, 'lease_seconds'),
+        ...(config.hooks !== undefined ? { hooks: config.hooks } : {}),
+        config_path: configPath,
+    };
+}

package/dist/src/core/conductor.d.ts

@@ -0,0 +1,69 @@
+import { type ConductorFileConfig, type ConductorLogger, type GaiaAgent, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace } from '@gaia-ai/core';
+/**
+ * Resolve the environment a run executes in (GAIA-99): parse the ticket's
+ * effective env_vars, drop any reserved key (loud warn — key NAME only, never
+ * the value), then overlay the conductor's core vars so they always win.
+ *
+ * Values are potentially secret (e.g. a DB DSN): this function logs key names
+ * only, never a value. The returned map is injected into BOTH the agent run env
+ * and every workspace hook.
+ */
+export declare function resolveRunEnv(effectiveEnvVars: string | undefined, core: Record<string, string>, logger: ConductorLogger): Record<string, string>;
+export declare class Conductor {
+    private readonly config;
+    private readonly remote;
+    private readonly executor;
+    private readonly workspace;
+    private readonly agent;
+    private readonly logger;
+    private readonly checkoutRoot;
+    private uuid;
+    constructor(config: ConductorFileConfig, remote: GaiaRemote, executor: GaiaExecutor, workspace: GaiaWorkspace, agent: GaiaAgent, logger: ConductorLogger, checkoutRoot?: string);
+    get id(): string;
+    /** This conductor's registration payload, built from config. */
+    private registration;
+    start(): Promise<void>;
+    tick(): Promise<void>;
+    /**
+     * One-shot finalisation: for each of this conductor's runs that is
+     * state=done but not yet closed, read the agent transcript from its worktree
+     * and write it as the final log, then mark the run closed. Keyed off the
+     * durable `state=done AND closed=false` query — no in-memory state, so a
+     * restarted conductor still finalises any unclosed done run on its next tick.
+     */
+    private finalizeDoneRuns;
+    /**
+     * Reconcile finished tickets against their herdr worktrees and tear down any
+     * whose workspace still lingers (GAIA-89). Driven by the durable `cleaned_up`
+     * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket that is
+     * finished (state=done OR closed) but not yet cleaned. The SAME reconciliation
+     * runs on every tick AND standalone as `gaia conductor reap`, and the query is
+     * scoped to THIS conductor (GAIA-121) — so it catches the orphans a
+     * live-tick-only path structurally cannot (the conductor was down when the
+     * ticket hit `done`, or crashed mid-cleanup) for its OWN tickets. A foreign
+     * (non-gaia) worktree has no gaia ticket, so it is never on the work list; a
+     * ticket assigned to another conductor is filtered out at the query — both are
+     * left untouched with no host enumeration.
+     *
+     * Per ticket, close is DECOUPLED from teardown (no withholding): a done ticket
+     * is closed at once as a lifecycle step, independent of whether its worktree
+     * teardown then succeeds. Because the list is conductor-scoped, every ticket's
+     * worktree belongs on THIS host: `removeWorktree` returning `false` means the
+     * directory was already deleted out of band (nothing left to remove), which is
+     * itself a completed teardown → flag `cleaned_up`. There is no cross-host defer
+     * (GAIA-121) — the manufactured ambiguity that required it is gone once the
+     * query no longer loads foreign tickets. A teardown that THROWS logs loudly and
+     * leaves `cleaned_up=0`, so the next reconciliation retries; one miss never
+     * orphans the workspace (RC1). Re-running on an already-cleaned ticket is a
+     * no-op — it is off the list (idempotent). Each ticket is isolated in a
+     * try/catch so one failure never aborts the rest.
+     *
+     * The `after_done` hook runs through the executor (GAIA-84), which owns the
+     * best-effort policy — it logs+swallows a hook failure and never throws, so
+     * the core needs no per-call-site try/catch around it.
+     */
+    reap(): Promise<void>;
+    private dispatch;
+    serve(signal?: AbortSignal): Promise<void>;
+    private pollLoop;
+}