@gaia-ai/conductor 0.5.5 → 0.6.1

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

@@ -0,0 +1,203 @@
+export interface ConductorRegistration {
+    id: string;
+    project: string;
+    /** Empty = serve all claimable states in the project (GAIA-207). */
+    states: string[];
+    workspace: string;
+    label: string;
+    max_parallel: number;
+}
+export interface ClaimOptions {
+    leaseSeconds: number;
+    conductorId: string;
+}
+export interface ClaimedRun {
+    runUuid: string;
+    runId: number;
+    ticketUuid: string;
+    stateAtStart: string;
+    handler: string;
+}
+export interface Ticket {
+    uuid: string;
+    identifier: string;
+    title: string;
+    state: string;
+    branchName: string;
+    /** Branch the ticket's work is based on (computed server-side): parent branch, project default, or 'main'. */
+    baseBranch?: string;
+    /**
+     * Effective environment variables (GAIA-99), resolved server-side along the
+     * parent_id chain (child wins) as canonical `.env`-style `KEY=value` lines.
+     * The conductor parses this, strips reserved keys, overlays the core GAIA_*
+     * vars, and injects the result into the agent run env AND the workspace hooks.
+     * Omitted when the ticket (and its ancestors) set none. Values may be secret.
+     */
+    effectiveEnvVars?: string;
+    issueUrl?: string;
+    /** Ticket label term names (gaia_labels vocab), sideloaded for agent selection. Empty when none. */
+    labels: string[];
+    /** Ticket environments (gaia_environment refs), each as name + tier, sideloaded for agent selection. Empty when none. */
+    environments: {
+        name: string;
+        tier: string;
+    }[];
+}
+export interface ActiveRun {
+    runUuid: string;
+    ticketUuid: string;
+    ticketIdentifier: string;
+    branchName: string;
+    state: string;
+    stateAtStart: string;
+    /** Absolute path of the per-run git worktree, or '' when unset. */
+    worktreePath: string;
+}
+export interface ConductorStatus {
+    id: string;
+    project: string;
+    label: string;
+    status: string;
+    lastSeen: number;
+    load: number;
+}
+export interface FinalizableRun {
+    runUuid: string;
+    /** Numeric run id (the `#<runId>` tab-label token); scopes the run's tab-close at finalise (GAIA-183). */
+    runId: number;
+    /** Absolute path of the per-run git worktree, or '' when unset. */
+    worktreePath: string;
+    /** Id of the agent that ran (GAIA-144); routes footprint parsing at finalize. '' / undefined when unset. */
+    agent?: string;
+}
+/**
+ * Per-run effort footprint the conductor writes onto `gaia_run` at close
+ * (GAIA-132). Six integer metrics, all parsed from the agent transcript —
+ * including `duration_s`, the run's wall-clock length derived from the
+ * transcript's first→last timestamps (GAIA-151), not a re-read `started_at`.
+ */
+export interface RunMetrics {
+    tokens: number;
+    duration_s: number;
+    agent_turns: number;
+    tool_calls: number;
+    user_prompts: number;
+    user_prompt_words: number;
+}
+/**
+ * A finished ticket whose worktree has not yet been torn down — the
+ * conductor's teardown work list, driven by the durable `cleaned_up` flag
+ * (GAIA-89). "Finished" = reached `done` OR already `closed`; `cleaned_up=0`
+ * means the herdr worktree still needs reclaiming. The reconciliation is NOT
+ * scoped to a conductor's machine_id, so it also surfaces tickets whose
+ * conductor was down at `done` or whose `conductor_id` was reassigned.
+ */
+export interface UncleanTicket {
+    ticketUuid: string;
+    /** The ticket's git branch — the key herdr resolves the worktree by. */
+    branchName: string;
+    /**
+     * Absolute path of the ticket's worktree (from its latest run's
+     * `worktree_path`), or '' when unresolved. The cwd the teardown runs in.
+     */
+    worktreePath: string;
+    /** Workflow state (e.g. `coding`, `done`). */
+    state: string;
+    /** Whether the ticket's lifecycle has already been closed out. */
+    closed: boolean;
+}
+/** Extra conductor-writable gaia_run attributes (besides state/lease). */
+export interface RunWriteAttributes {
+    /** Absolute path of the per-run git worktree (set by the conductor). */
+    worktree_path?: string;
+    /** Id of the agent the conductor chose for this run (GAIA-144), for footprint routing. */
+    agent?: string;
+}
+export interface GaiaRemote {
+    /** Upserts by machine_id; sets status=online. Returns the Drupal entity uuid. */
+    registerConductor(reg: ConductorRegistration): Promise<string>;
+    /**
+     * Records a heartbeat server-side: upserts by machine_id (recreating a
+     * vanished registration), refreshes last_seen/lease/load, and brings the
+     * conductor online. Keyed on machine_id, so it never 404s — the self-heal
+     * lives on the server, not the client. Returns the resulting status
+     * (`online` | `offline`).
+     */
+    heartbeat(reg: ConductorRegistration, currentLoad: number, leaseSeconds?: number): Promise<string>;
+    getConductorStatus(conductorId: string): Promise<string | null>;
+    setConductorStatus(conductorId: string, status: 'offline' | 'online'): Promise<void>;
+    listConductors(owner?: 'me'): Promise<ConductorStatus[]>;
+    activeRunCount(conductorId: string): Promise<number>;
+    fetchActiveRuns(conductorId: string): Promise<ActiveRun[]>;
+    claimNext(claim: ClaimOptions): Promise<ClaimedRun | null>;
+    getTicket(ticketUuid: string): Promise<Ticket>;
+    /** Returns the run's worktree_path, or '' when unset. */
+    getRunWorktree(runUuid: string): Promise<string>;
+    /**
+     * Returns the identifier of the run's ticket, or '' when unresolved. Lets the
+     * release path derive the tab matching ref (the ticket identifier) from a run
+     * uuid alone.
+     */
+    getRunTicketIdentifier(runUuid: string): Promise<string>;
+    /**
+     * Returns the branch_name of the run's ticket, or '' when unresolved. Used
+     * by dispatch for the per-(branch,state) herdr tab model.
+     */
+    getRunTicketBranchName(runUuid: string): Promise<string>;
+    markRunning(runUuid: string, attrs?: RunWriteAttributes): Promise<void>;
+    /**
+     * Terminalise a run to the `failed` state on a dispatch/setup error (GAIA-149).
+     * PATCHes state=failed, records the failure detail in `error_log`, and closes
+     * the run (closed + closed_date). `failed` is a terminal sibling of `expired`
+     * (dispatch error vs lease lapse), so the run stops counting toward capacity
+     * and its ticket is no longer blocked by the single-active-run gate — instead
+     * of the old "leave it `claimed` to expire after ~300s" silent stall. The
+     * failure is visible immediately and its cause is recorded.
+     */
+    markFailed(runUuid: string, errorLog: string): Promise<void>;
+    /**
+     * Runs this conductor owns that are state=done but not yet closed — the
+     * conductor's one-shot finalisation work list.
+     */
+    fetchFinalizableRuns(conductorId: string): Promise<FinalizableRun[]>;
+    /**
+     * Finalise a run: set closed + closed_date, (when non-empty) log, and (when
+     * given) the per-run footprint metrics (GAIA-132). No state change — the run
+     * is already done.
+     */
+    finalizeRun(uuid: string, log: string, metrics?: RunMetrics): Promise<void>;
+    /**
+     * Finished tickets (state=done OR closed) whose worktree is not yet torn
+     * down (cleaned_up=0) — the conductor's teardown work list (GAIA-89). Driven
+     * by the durable `cleaned_up` flag AND scoped to the reaping conductor
+     * (GAIA-121): only tickets assigned to `conductorId` are loaded, so every
+     * ticket on the list is unambiguously this conductor's — a missing worktree
+     * means "already torn down on this host", not "belongs to another host". The
+     * same query backs the live tick and the standalone `gaia conductor reap`.
+     * Empty once every finished ticket this conductor owns is cleaned.
+     */
+    fetchUncleanedTickets(conductorId: string): Promise<UncleanTicket[]>;
+    /**
+     * Close a ticket: set closed=true + closed_date. Ticket-lifecycle only, and
+     * decoupled from teardown — a done ticket is closed even if its worktree
+     * teardown later fails. No state change (the ticket is already done).
+     */
+    closeTicket(uuid: string): Promise<void>;
+    /**
+     * Mark a ticket's worktree torn down: set cleaned_up=true so it drops off the
+     * {@link fetchUncleanedTickets} work list. Written ONLY after a verified
+     * teardown, so a teardown miss leaves cleaned_up=0 and the next reconciliation
+     * retries — one miss never orphans the workspace, and a re-run on an
+     * already-cleaned ticket is a no-op (it is no longer on the list).
+     */
+    markTicketCleanedUp(uuid: string): Promise<void>;
+    /**
+     * Resolve a ticket identifier (e.g. "GAIA-134") to its uuid+title within a
+     * project, or null when no such ticket exists. Used by the
+     * `gaia deployment tickets` helper to turn commit-message identifiers into tickets.
+     */
+    resolveTicketByIdentifier(project: string, identifier: string): Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
+}

package/dist/src/plugins/remote.js

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

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

@@ -0,0 +1,35 @@
+export interface EnsuredWorkspace {
+    path: string;
+    instructions: {
+        path: string;
+        sha256: string;
+        text: string;
+    } | null;
+    /**
+     * Whether this call CREATED the worktree (true) or reused an existing one
+     * (false). The core runs the `after_create` lifecycle hook only on a fresh
+     * worktree, so it needs to know which happened. Lifecycle hooks themselves
+     * are no longer a workspace concern (GAIA-84): the executor owns and runs
+     * them best-effort.
+     */
+    created: boolean;
+}
+export interface GaiaWorkspace {
+    /**
+     * Ensure a per-ticket worktree exists. `branch`, when given, is the branch
+     * name the dispatcher computed for the ticket. The git plugin treats it as a
+     * readable title to slug into its branch template; the herdr plugin uses it
+     * verbatim as the worktree branch. The worktree directory key/path stays
+     * identifier- or branch-derived so reuse is stable across runs.
+     *
+     * `baseRef`, when given, overrides the base the new branch is created from
+     * (e.g. `origin/<base_branch>` so a sub-ticket stacks on its parent); if it
+     * does not resolve on the remote the implementation falls back to its default
+     * base — never a hard error.
+     *
+     * Reports `created` so the caller can run the `after_create` hook only on a
+     * fresh worktree. Lifecycle-hook invocation is NOT a workspace responsibility
+     * anymore — the executor owns all hooks (GAIA-84).
+     */
+    ensure(identifier: string, branch?: string, baseRef?: string): Promise<EnsuredWorkspace>;
+}

package/dist/src/plugins/workspace.js

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

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { Preset } from './plugins/preset.js';
+export declare const commands: Preset['commands'];

package/dist/src/preset.js

@@ -0,0 +1,8 @@
+export const commands = (acc) => [
+    ...acc,
+    {
+        name: 'conductor',
+        plugin: '@gaia-ai/conductor/commands/conductor',
+        describe: 'node-agent lifecycle + local registry',
+    },
+];

package/dist/src/types.d.ts

@@ -0,0 +1,65 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { AgentCandidate, ExecutorPlugin, RemotePlugin, WorkspacePlugin } from './plugins/plugins.js';
+/** Normalized single conductor. */
+export interface ConductorSettings {
+    /** Default: `${project} @ ${checkoutRoot}`. */
+    label: string;
+    /**
+     * Stable node identity (gaia_conductor.machine_id) this process registers as.
+     * Defaults to a hash of hostname + checkout path. Set it to pin a conductor to
+     * a known identity — e.g. so a ticket can be pre-assigned to it (conductor
+     * assignment is the run-start trigger), which the e2e fixtures rely on.
+     */
+    machine_id?: string;
+    /** Project name (gaia_project.name); resolved at registration. */
+    project: string;
+    /**
+     * Workflow states this conductor serves. An empty list means it serves every
+     * claimable state in its project; a non-empty list narrows it to those
+     * states (GAIA-207).
+     */
+    states: string[];
+    /**
+     * Agent prompt template - the GAIA run contract, NOT project workflow. Bounds
+     * the agent to exactly one state and tells it to release + stop, keeping run
+     * mechanics out of the repo's WORKFLOW.md. Placeholders: `{identifier}`,
+     * `{state}`, `{runUuid}`. Defaults to `DEFAULT_AGENT_PROMPT`.
+     */
+    prompt: string;
+    /** Default: 1. */
+    max_parallel: number;
+    poll_interval_ms: number;
+    lease_seconds: number;
+    hooks?: {
+        after_create?: string;
+        before_run?: string;
+        after_run?: string;
+        after_done?: string;
+    };
+    /** Control-plane site settings used for dropsh and agent env. */
+    site: {
+        base_url: string;
+        jsonapi_prefix: string;
+    };
+    /** Absolute path of the loaded config. */
+    config_path: string;
+}
+/** Whole conductor.config.js (dropsh-superset): site + named plugin slots. */
+export interface ConductorFileConfig extends ConductorSettings {
+    remote: RemotePlugin;
+    executor: ExecutorPlugin;
+    /** The agent slot: a single candidate or an array of candidates (shape preserved as authored). Selection normalizes + picks one per dispatch. */
+    agent: AgentCandidate | AgentCandidate[];
+    workspace: WorkspacePlugin;
+    /** dropsh-layer plugins (auth etc.); separate from the GAIA slots. */
+    plugins?: DropSHPlugin[];
+}
+/**
+ * GAIA-201 split config model: the ENGINE half of a conductor config —
+ * everything a `conductor.config.js` carries EXCEPT the connection (`site`) and
+ * the auth `plugins`, which now live in a separate `gaia.config.js`
+ * (`GaiaConnectionConfig`). `loadConductorConfig` returns this; the conductor
+ * command composes it with the connection (`composeConductorConfig`) into the
+ * full `ConductorFileConfig` the engine consumes.
+ */
+export type ConductorEngineConfig = Omit<ConductorFileConfig, 'site' | 'plugins'>;

package/dist/src/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/conductor",
-  "version": "0.5.5",
+  "version": "0.6.1",
   "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -9,6 +9,9 @@
   },
   "exports": {
     ".": "./dist/src/index.js",
+    "./contract": "./dist/src/contract.js",
+    "./preset": "./dist/src/preset.js",
+    "./commands/conductor": "./dist/src/commands/conductor.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -22,14 +25,14 @@
   "repository": {
     "type": "git",
     "url": "git+https://git.key-tec.de/keytec/gaia.git",
-    "directory": "conductor/packages/conductor"
+    "directory": "gaia-cli/conductor"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.5.5",
+    "@gaia-ai/core": "^0.6.1",
     "@dropsh/plugin-oauth2": "^0.5.7",
-    "@dropsh/plugin-jsonapi-schema": "^0.5.7",
+    "@dropsh/plugin-jsonapi-schema": "^0.5.8",
     "commander": "^12.1.0",
-    "dropsh": "^0.5.7",
+    "dropsh": "^0.5.8",
     "semver": "^7.6.0"
   }
 }

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

@@ -1,23 +0,0 @@
-import { type ConductorFileConfig, type ConductorLogger, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace, type ResolvedAgent } from '@gaia-ai/core';
-import { Command } from 'commander';
-/** Test seam: inject any subset of dependencies. */
-export interface GaiaCliDeps {
-    remote?: GaiaRemote;
-    executor?: GaiaExecutor;
-    workspace?: GaiaWorkspace;
-    agents?: ResolvedAgent[];
-    config?: ConductorFileConfig;
-    /** Injectable registry fetch for the start-time version check (tests). */
-    fetch?: typeof fetch;
-}
-export declare function parseHerdrJson(output: string, command: string): unknown;
-/**
- * Start-time auth gate. Returns true if authenticated (session or session-less
- * provider); otherwise logs a single clear line and returns false. Must run
- * before remote resolution (resolveRemote), which calls resolveAuth and throws
- * when unauthenticated.
- */
-export declare function ensureAuthenticated(config: ConductorFileConfig, logger: ConductorLogger): Promise<boolean>;
-export declare function buildProgram(deps: GaiaCliDeps): Command;
-export declare function runGaiaCli(argv: string[], deps?: GaiaCliDeps): Promise<void>;
-export declare function main(argv: string[]): Promise<void>;

package/dist/src/cli/local-registry.d.ts

@@ -1,14 +0,0 @@
-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 registryPath(): string;
-export declare function register(entry: ConductorRegistryEntry): Promise<void>;
-export declare function remove(id: string): Promise<void>;
-export declare function list(): Promise<ConductorRegistryEntry[]>;
-export declare function get(id: string): Promise<ConductorRegistryEntry | null>;

package/dist/src/cli/local-registry.js

@@ -1,56 +0,0 @@
-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 registryPath() {
-    const home = process.env.GAIA_HOME ?? homedir();
-    return join(home, '.gaia', 'conductors.json');
-}
-async function read() {
-    let raw;
-    try {
-        raw = await readFile(registryPath(), '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 = registryPath();
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
-}
-export async function register(entry) {
-    const data = await read();
-    data[entry.id] = entry;
-    await write(data);
-}
-export async function remove(id) {
-    const data = await read();
-    if (data[id]) {
-        delete data[id];
-        await write(data);
-    }
-}
-export async function list() {
-    return Object.values(await read());
-}
-export async function get(id) {
-    const data = await read();
-    return data[id] ?? null;
-}