@gaia-ai/conductor 0.4.0

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

@@ -0,0 +1,71 @@
+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
+     * NOT machine-scoped — so it catches the orphans a live-tick-only path
+     * structurally cannot (RC2/RC3): the conductor was down when the ticket hit
+     * `done`, crashed mid-cleanup, or the ticket's `conductor_id` was reassigned.
+     * A foreign (non-gaia) worktree has no gaia ticket, so it is never on the work
+     * list and never touched — foreign-safety falls out of the DB-driven model
+     * 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. Teardown is best-effort + verified — `cleaned_up` is
+     * set only when the worktree was actually torn down ON THIS HOST. Since the
+     * query is not machine-scoped, a conductor may see a finished ticket whose
+     * worktree lives on ANOTHER host; `removeWorktree` returns `false` there (a
+     * clean "not here") and the reaper DEFERS — it does not flag the ticket
+     * cleaned, leaving the teardown to the host that physically holds the
+     * worktree. That gate is what keeps the not-machine-scoped query from
+     * cross-host-false-teardowning a still-live workspace. 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;
+}

package/dist/src/core/conductor.js

@@ -0,0 +1,410 @@
+import { conductorId, } from '@gaia-ai/core';
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Formats a ticket's comments into the `{comments}` prompt block, oldest first.
+ * The conductor injects this so a review→coding bounce reaches the coder with the
+ * review summary in hand, independent of whether the agent remembers to fetch it.
+ *
+ * The body is the raw gaia_rich markup — the agent reads HTML fine, so we don't
+ * strip it (a tag/entity stripper is a maintenance footgun that buys nothing for
+ * an LLM reader).
+ */
+function renderComments(comments) {
+    if (comments.length === 0) {
+        return '(no comments on this ticket yet)';
+    }
+    return comments
+        .map((c, i) => {
+        const when = c.created ? ` (${c.created})` : '';
+        return `[#${i + 1}] type=${c.type}${when}\n${c.body}`;
+    })
+        .join('\n\n---\n\n');
+}
+/**
+ * A run-env key is reserved when it names a conductor-provided core variable:
+ * any `GAIA_*`, `WORKSPACE_ROOT`, or `TICKET_URL`. User `env_vars` may not
+ * clobber these — the core vars always win (GAIA-99).
+ */
+function isReservedEnvKey(key) {
+    return (key.startsWith('GAIA_') || key === 'WORKSPACE_ROOT' || key === 'TICKET_URL');
+}
+/**
+ * Parse the server-canonicalised effective env_vars (`KEY=value` lines, one per
+ * line) into a map. The server already stripped comments/blank/malformed lines,
+ * so this is deliberately minimal: split on the first `=`, keep a valid key.
+ * Defensive against stray blank lines only — never throws.
+ */
+function parseEnvLines(text) {
+    const out = {};
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line === '') {
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq <= 0) {
+            continue;
+        }
+        const key = line.slice(0, eq);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            continue;
+        }
+        out[key] = line.slice(eq + 1);
+    }
+    return out;
+}
+/**
+ * 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 function resolveRunEnv(effectiveEnvVars, core, logger) {
+    const user = effectiveEnvVars ? parseEnvLines(effectiveEnvVars) : {};
+    const clobbered = [];
+    const safe = {};
+    for (const [key, value] of Object.entries(user)) {
+        if (isReservedEnvKey(key)) {
+            clobbered.push(key);
+            continue;
+        }
+        safe[key] = value;
+    }
+    if (clobbered.length > 0) {
+        logger.warn({ keys: clobbered }, 'ignored reserved keys in ticket env_vars (core vars win)');
+    }
+    // Core vars overlay last — they can never be overridden.
+    return { ...safe, ...core };
+}
+function renderPrompt(template, values) {
+    return template
+        .replaceAll('{identifier}', values.identifier)
+        .replaceAll('{state}', values.state)
+        .replaceAll('{runUuid}', values.runUuid)
+        .replaceAll('{comments}', renderComments(values.comments));
+}
+export class Conductor {
+    config;
+    remote;
+    executor;
+    workspace;
+    agent;
+    logger;
+    checkoutRoot;
+    uuid = null;
+    constructor(config, remote, executor, workspace, agent, logger, checkoutRoot = process.cwd()) {
+        this.config = config;
+        this.remote = remote;
+        this.executor = executor;
+        this.workspace = workspace;
+        this.agent = agent;
+        this.logger = logger;
+        this.checkoutRoot = checkoutRoot;
+    }
+    get id() {
+        return this.config.machine_id ?? conductorId(this.checkoutRoot);
+    }
+    /** This conductor's registration payload, built from config. */
+    registration() {
+        return {
+            id: this.id,
+            project: this.config.project,
+            states: this.config.states,
+            workspace: this.checkoutRoot,
+            label: this.config.label,
+            max_parallel: this.config.max_parallel,
+        };
+    }
+    async start() {
+        this.uuid = await this.remote.registerConductor(this.registration());
+        this.logger.info({ conductorId: this.id, uuid: this.uuid, project: this.config.project }, 'conductor started');
+    }
+    async tick() {
+        if (!this.uuid)
+            throw new Error('not started');
+        let count = await this.remote.activeRunCount(this.id);
+        // A heartbeat is the server-side self-heal: it upserts by machine_id (so it
+        // never 404s and recreates a vanished registration) and refreshes the lease
+        // — no client-side re-register, no separate status read.
+        await this.remote.heartbeat(this.registration(), count, this.config.lease_seconds);
+        this.logger.info({ conductorId: this.id, active: count }, 'conductor tick');
+        await this.finalizeDoneRuns();
+        await this.reap();
+        let claimed = 0;
+        while (count < this.config.max_parallel) {
+            const run = await this.remote.claimNext({
+                leaseSeconds: this.config.lease_seconds,
+                conductorId: this.id,
+            });
+            if (!run)
+                break;
+            this.logger.info({ conductorId: this.id, run: run.runUuid, ticket: run.ticketUuid }, 'claimed run');
+            try {
+                await this.dispatch(run);
+            }
+            catch (err) {
+                // A failed dispatch must NOT terminalise the run. The run lifecycle is
+                // server-owned; a client-side releaseRun('done') here fabricated a
+                // terminal state on failure, which reopened the ticket for claiming and
+                // re-dispatched it every tick — the GAIA-41 runaway. Leaving the run
+                // `claimed` lets the server's same-state claim conflict
+                // (TicketClaimService::retireSupersededRuns) block a re-claim of the
+                // same ticket, so we just log and move on. A run stuck `claimed` on a
+                // persistently-failing dispatch is freed by the lease-expiry reaper
+                // (separate follow-up), not here.
+                this.logger.error({ run: run.runUuid, err: String(err) }, 'dispatch failed');
+            }
+            count += 1;
+            claimed += 1;
+        }
+        if (claimed === 0) {
+            this.logger.info({
+                conductorId: this.id,
+                active: count,
+                capacity: this.config.max_parallel,
+            }, count >= this.config.max_parallel
+                ? 'at capacity, nothing claimed'
+                : 'idle, nothing to claim');
+        }
+    }
+    /**
+     * 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.
+     */
+    async finalizeDoneRuns() {
+        const runs = await this.remote.fetchFinalizableRuns(this.id);
+        for (const r of runs) {
+            try {
+                // Ask the agent to exit gracefully (/exit) before capturing its log.
+                // Best-effort and gated on the persistent capability (only hosted
+                // executors have a live agent pane) — mirrors removeWorktree's gate.
+                // A stop failure must never block finalisation.
+                if (this.executor.capabilities().persistent) {
+                    const branch = await this.remote.getRunTicketBranchName(r.runUuid);
+                    if (branch) {
+                        try {
+                            await this.executor.stopAgent(branch);
+                        }
+                        catch (err) {
+                            this.logger.warn({ run: r.runUuid, err: String(err) }, 'agent stop failed');
+                        }
+                    }
+                }
+                const log = r.worktreePath
+                    ? await this.agent.getRunLog(r.worktreePath)
+                    : '';
+                await this.remote.finalizeRun(r.runUuid, log);
+                this.logger.info({ run: r.runUuid }, 'run finalised');
+            }
+            catch (err) {
+                this.logger.warn({ run: r.runUuid, err: String(err) }, 'run finalise failed');
+            }
+        }
+    }
+    /**
+     * 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
+     * NOT machine-scoped — so it catches the orphans a live-tick-only path
+     * structurally cannot (RC2/RC3): the conductor was down when the ticket hit
+     * `done`, crashed mid-cleanup, or the ticket's `conductor_id` was reassigned.
+     * A foreign (non-gaia) worktree has no gaia ticket, so it is never on the work
+     * list and never touched — foreign-safety falls out of the DB-driven model
+     * 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. Teardown is best-effort + verified — `cleaned_up` is
+     * set only when the worktree was actually torn down ON THIS HOST. Since the
+     * query is not machine-scoped, a conductor may see a finished ticket whose
+     * worktree lives on ANOTHER host; `removeWorktree` returns `false` there (a
+     * clean "not here") and the reaper DEFERS — it does not flag the ticket
+     * cleaned, leaving the teardown to the host that physically holds the
+     * worktree. That gate is what keeps the not-machine-scoped query from
+     * cross-host-false-teardowning a still-live workspace. 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.
+     */
+    async reap() {
+        const tickets = await this.remote.fetchUncleanedTickets();
+        for (const t of tickets) {
+            try {
+                // Lifecycle: close a done+unclosed ticket at once, decoupled from the
+                // infra teardown below — a done ticket whose conductor was down was
+                // never closed, and withholding the close on a teardown hiccup would
+                // make a finished ticket look unfinished (the pre-GAIA-89 defect).
+                if (t.state === 'done' && !t.closed) {
+                    await this.remote.closeTicket(t.ticketUuid);
+                }
+                // Infra teardown. The `after_done` hook runs in the worktree regardless
+                // of executor kind (a non-persistent gitWorkspace still has an on-disk
+                // worktree); only the workspace removal is gated on the persistent
+                // capability (mirrors the executor-agnostic release path). Pass the
+                // stable worktreePath so the executor resolves the worktree by path,
+                // not by the mutable checked-out branch (the coding agent may rename
+                // it). Teardown is idempotent: a worktree herdr no longer tracks is a
+                // no-op / on-disk reclaim, not a failure.
+                if (t.worktreePath) {
+                    await this.executor.runHook('after_done', t.worktreePath, {
+                        ticket: t.ticketUuid,
+                    });
+                }
+                if (this.executor.capabilities().persistent) {
+                    let removed;
+                    try {
+                        removed = await this.executor.removeWorktree(t.branchName, t.worktreePath || undefined);
+                    }
+                    catch (err) {
+                        this.logger.warn({
+                            ticket: t.ticketUuid,
+                            branch: t.branchName,
+                            worktreePath: t.worktreePath,
+                            err: String(err),
+                        }, 'worktree teardown failed');
+                        continue; // leave cleaned_up=0 → the next reconciliation retries.
+                    }
+                    // A recorded worktree path that was NOT present on this host belongs
+                    // to another conductor's host (the query is not machine-scoped, so we
+                    // see every finished ticket). Do NOT flag it cleaned — that would be a
+                    // cross-host false-teardown, orphaning a still-live workspace. Defer:
+                    // the host that physically holds it reaps + flags it. A ticket with no
+                    // recorded path (nothing hosted to locate) falls through to cleaned.
+                    if (t.worktreePath && !removed) {
+                        this.logger.info({
+                            ticket: t.ticketUuid,
+                            branch: t.branchName,
+                            worktreePath: t.worktreePath,
+                        }, 'worktree not on this host — deferring teardown to its host');
+                        continue;
+                    }
+                }
+                // Teardown verified locally (or nothing hosted to tear down): flag it
+                // cleaned so it drops off the work list.
+                await this.remote.markTicketCleanedUp(t.ticketUuid);
+                this.logger.info({ ticket: t.ticketUuid }, 'ticket cleaned up');
+            }
+            catch (err) {
+                this.logger.warn({ ticket: t.ticketUuid, err: String(err) }, 'ticket cleanup failed');
+            }
+        }
+    }
+    async dispatch(run) {
+        const t = await this.remote.getTicket(run.ticketUuid);
+        const baseRef = t.baseBranch ? `origin/${t.baseBranch}` : undefined;
+        // Resolve the run env once (per-ticket env_vars + core GAIA_* vars) and
+        // inject it into BOTH the executor-owned lifecycle hooks AND the agent run
+        // env (GAIA-99). Reserved core keys always win; values may be sensitive so
+        // only key names are ever logged.
+        const core = {
+            GAIA_URL: this.config.site.base_url,
+            GAIA_ID: run.ticketUuid,
+            GAIA_RUN_UUID: run.runUuid,
+            WORKSPACE_ROOT: this.checkoutRoot,
+            ...(t.issueUrl ? { TICKET_URL: t.issueUrl } : {}),
+        };
+        const env = resolveRunEnv(t.effectiveEnvVars, core, this.logger);
+        const ws = await this.workspace.ensure(t.identifier, t.branchName, baseRef);
+        // A claimable state has no deterministic policy without a WORKFLOW.md
+        // (SKILL.md dispatch reads its `## State: <state>` sections). The human
+        // steered this to WARN-and-proceed (not a hard fail): the agent runs on
+        // engine defaults, and the gap is observable in the conductor log rather
+        // than wedging the run. `ws.instructions` IS the loaded WORKFLOW.md (null
+        // when absent), so no extra stat.
+        if (!ws.instructions) {
+            this.logger.warn({ ticket: t.identifier, workspace: ws.path }, 'WORKFLOW.md missing — dispatching on engine defaults');
+        }
+        // Lifecycle hooks are executor-owned + best-effort (GAIA-84): runHook never
+        // throws, so neither call can abort dispatch or wedge a run in `claimed`.
+        // after_create only on a freshly-created worktree; before_run always. Both
+        // get the resolved run env so a setup/pre hook sees the same vars (e.g. a DB
+        // DSN) the agent does (GAIA-99).
+        if (ws.created) {
+            await this.executor.runHook('after_create', ws.path, { ticket: t.identifier }, env);
+        }
+        await this.executor.runHook('before_run', ws.path, { ticket: t.identifier }, env);
+        await this.executor.retire(t.branchName);
+        const prompt = ws.instructions
+            ? renderPrompt(this.config.prompt, {
+                identifier: t.identifier,
+                state: t.state || 'triage',
+                runUuid: run.runUuid,
+                comments: t.comments,
+            })
+            : '';
+        await this.executor.startRun({
+            ticket: {
+                uuid: t.uuid,
+                identifier: t.identifier,
+                title: t.title,
+                branchName: t.branchName,
+                state: t.state,
+                ...(t.issueUrl ? { url: t.issueUrl } : {}),
+            },
+            run: { uuid: run.runUuid, id: run.runId, handler: run.handler },
+            workspacePath: ws.path,
+            instructions: ws.instructions,
+            command: this.agent.launchCommand(prompt),
+            env,
+        });
+        this.logger.info({
+            ticket: t.identifier,
+            run: run.runUuid,
+            state: t.state,
+            workspace: ws.path,
+            // Key names only — env values may be sensitive (GAIA-99).
+            envKeys: Object.keys(env),
+        }, 'dispatched run');
+        // The conductor — not the agent — knows the per-run git worktree path, so
+        // it persists `worktree_path` to gaia_run here alongside the running state.
+        await this.remote.markRunning(run.runUuid, { worktree_path: ws.path });
+    }
+    async serve(signal) {
+        await this.pollLoop(signal);
+    }
+    async pollLoop(signal) {
+        while (!signal?.aborted) {
+            try {
+                await this.tick();
+            }
+            catch (err) {
+                this.logger.error({ conductorId: this.id, err: String(err) }, 'tick failed');
+            }
+            await sleep(this.config.poll_interval_ms, signal);
+        }
+        // NB: the poll loop never writes status=offline itself. A graceful stop
+        // (`gaia conductor stop`) writes offline directly server-side; a crash or
+        // hard-kill leaves a stale lease that the Drupal cron reaper flips to
+        // offline (gaia_core cron → ConductorReaper). Liveness is thus always
+        // derived from status + last_seen/lease_expires_at, never from the loop.
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export type * from '@gaia-ai/core';
+export { conductorId } from '@gaia-ai/core';
+export { DrupalGaiaRemote, drupalRemote, FakeGaiaRemote, FakeWorkspace, fakeRemote, fakeWorkspace, GitWorkspace, gitWorkspace, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+export type { GaiaCliDeps } from './cli/gaia.js';
+export { main, runGaiaCli } from './cli/gaia.js';
+export type { ConductorRegistryEntry } from './cli/local-registry.js';
+export { DEFAULT_AGENT_PROMPT, loadConductorConfig } from './config.js';
+export { Conductor } from './core/conductor.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { conductorId } from '@gaia-ai/core';
+export { DrupalGaiaRemote, drupalRemote, FakeGaiaRemote, FakeWorkspace, fakeRemote, fakeWorkspace, GitWorkspace, gitWorkspace, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+export { main, runGaiaCli } from './cli/gaia.js';
+export { DEFAULT_AGENT_PROMPT, loadConductorConfig } from './config.js';
+export { Conductor } from './core/conductor.js';

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@gaia-ai/conductor",
+  "version": "0.4.0",
+  "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "conductor/packages/conductor"
+  },
+  "dependencies": {
+    "@gaia-ai/core": "^0.4.0",
+    "@dropsh/plugin-oauth2": "^0.4.1",
+    "@dropsh/plugin-jsonapi-schema": "^0.5.1",
+    "commander": "^12.1.0",
+    "dropsh": "^0.5.1"
+  }
+}