@gaia-ai/core 0.4.0

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

@@ -0,0 +1,169 @@
+export interface ConductorRegistration {
+    id: string;
+    project: string;
+    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;
+}
+/** A ticket comment, as the conductor injects it into the dispatch prompt. */
+export interface TicketComment {
+    /** comment | spec | plan | debug_diagnose | summary | acceptance | test */
+    type: string;
+    /** Raw body (gaia_rich HTML). */
+    body: string;
+    /** ISO 8601 creation timestamp. */
+    created: 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;
+    /**
+     * Comments on the ticket, oldest first. The conductor renders these into the
+     * dispatch prompt so a review→coding bounce carries the review summary to the
+     * coder. Empty when the ticket has none — or when the session role lacks
+     * `view gaia_comment` (the include degrades to an empty set, never an error).
+     */
+    comments: TicketComment[];
+}
+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;
+    /** Absolute path of the per-run git worktree, or '' when unset. */
+    worktreePath: string;
+}
+/**
+ * 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;
+}
+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>;
+    /**
+     * 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 and (when non-empty) log. No state
+     * change — the run is already done.
+     */
+    finalizeRun(uuid: string, log: string): 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, NOT machine-scoped: the same query backs
+     * both the live tick and the standalone `gaia conductor reap`, so it catches
+     * orphans a conductor missed while down / after a restart / after a
+     * `conductor_id` reassignment. Empty once every finished ticket is cleaned.
+     */
+    fetchUncleanedTickets(): 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>;
+}

package/dist/src/plugins/remote/remote.js

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

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

@@ -0,0 +1,6 @@
+import type { WorkspacePlugin } from '../plugins.js';
+import type { EnsuredWorkspace, GaiaWorkspace } from './workspace.js';
+export declare class FakeWorkspace implements GaiaWorkspace {
+    ensure(identifier: string, _title?: string): Promise<EnsuredWorkspace>;
+}
+export declare function fakeWorkspace(): WorkspacePlugin;

package/dist/src/plugins/workspace/fake.js

@@ -0,0 +1,16 @@
+export class FakeWorkspace {
+    async ensure(identifier, _title) {
+        return { path: `/fake/${identifier}`, instructions: null, created: true };
+    }
+}
+export function fakeWorkspace() {
+    const workspace = new FakeWorkspace();
+    return {
+        kind: 'workspace',
+        id: 'fake',
+        requiredModules: [],
+        async createWorkspace(_config) {
+            return workspace;
+        },
+    };
+}

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

@@ -0,0 +1,37 @@
+import type { WorkspacePlugin } from '../plugins.js';
+import type { EnsuredWorkspace, GaiaWorkspace } from './workspace.js';
+/** Default branch template: `<prefix><key>-<title-slug>` (readable). */
+export declare const DEFAULT_BRANCH_TEMPLATE = "{branchPrefix}{key}-{titleSlug}";
+export type GitRunner = (args: string[], cwd: string) => Promise<void>;
+export interface GitWorkspaceOptions {
+    /** Main clone (a git repo): config source + worktree base. */
+    root: string;
+    /** Where per-ticket worktrees live. Default: `${root}-worktrees`. */
+    worktreesRoot?: string;
+    /** Branch name prefix per ticket. Default: 'gaia/'. */
+    branchPrefix?: string;
+    /**
+     * Branch name template. Vars: {branchPrefix}, {key} (sanitized identifier),
+     * {identifier}, {titleSlug}. Default: `{branchPrefix}{key}-{titleSlug}`.
+     */
+    branchTemplate?: string;
+    runGit?: GitRunner;
+}
+export declare class GitWorkspace implements GaiaWorkspace {
+    private readonly runGit;
+    private readonly root;
+    private readonly worktreesRoot;
+    private readonly branchPrefix;
+    private readonly branchTemplate;
+    constructor(options: GitWorkspaceOptions);
+    /** Render the branch name for a ticket from the configured template. */
+    branchFor(identifier: string, title?: string): string;
+    keyFor(identifier: string): string;
+    private pathFor;
+    ensure(identifier: string, title?: string, _baseRef?: string): Promise<EnsuredWorkspace>;
+    remove(identifier: string): Promise<void>;
+}
+export declare function gitWorkspace(opts?: {
+    branchPrefix?: string;
+    branchTemplate?: string;
+}): WorkspacePlugin;

package/dist/src/plugins/workspace/git.js

@@ -0,0 +1,89 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { exec } from '../../core/exec.js';
+import { slugify } from '../../core/slug.js';
+import { loadInstructions } from './instructions.js';
+/** Default branch template: `<prefix><key>-<title-slug>` (readable). */
+export const DEFAULT_BRANCH_TEMPLATE = '{branchPrefix}{key}-{titleSlug}';
+function renderBranchTemplate(template, vars) {
+    const rendered = template.replace(/\{(\w+)\}/g, (whole, key) => {
+        const value = vars[key];
+        return value === undefined ? whole : value;
+    });
+    // An empty title slug leaves a dangling separator (e.g. `gaia/GL-9-`) —
+    // trim trailing branch separators so the branch stays a valid, tidy ref.
+    return rendered.replace(/[-_./]+$/g, '');
+}
+const defaultGitRunner = async (args, cwd) => {
+    await exec('git', args, { cwd });
+};
+export class GitWorkspace {
+    runGit;
+    root;
+    worktreesRoot;
+    branchPrefix;
+    branchTemplate;
+    constructor(options) {
+        this.runGit = options.runGit ?? defaultGitRunner;
+        this.root = resolve(options.root);
+        this.worktreesRoot = options.worktreesRoot
+            ? resolve(options.worktreesRoot)
+            : `${this.root}-worktrees`;
+        this.branchPrefix = options.branchPrefix ?? 'gaia/';
+        this.branchTemplate = options.branchTemplate ?? DEFAULT_BRANCH_TEMPLATE;
+    }
+    /** Render the branch name for a ticket from the configured template. */
+    branchFor(identifier, title) {
+        return renderBranchTemplate(this.branchTemplate, {
+            branchPrefix: this.branchPrefix,
+            key: this.keyFor(identifier),
+            identifier,
+            titleSlug: slugify(title ?? ''),
+        });
+    }
+    keyFor(identifier) {
+        return identifier.replace(/[^A-Za-z0-9._-]/g, '_');
+    }
+    pathFor(key) {
+        return resolve(join(this.worktreesRoot, key));
+    }
+    async ensure(identifier, title, _baseRef) {
+        const key = this.keyFor(identifier);
+        // Reject empty and dot-leading keys: a dot-leading key would produce an
+        // invalid git ref (e.g. `gaia/.hidden`) and covers '.'/'..' too.
+        if (key === '' || key.startsWith('.')) {
+            throw new Error(`invalid workspace identifier: ${identifier}`);
+        }
+        const path = this.pathFor(key);
+        if (existsSync(path)) {
+            return { path, instructions: loadInstructions(path), created: false };
+        }
+        const branch = this.branchFor(identifier, title);
+        await this.runGit(['-C', this.root, 'worktree', 'add', '--force', '-B', branch, path], this.root);
+        // The `after_create` hook is run by the executor (GAIA-84), not here — the
+        // workspace only reports that it created a fresh worktree.
+        return { path, instructions: loadInstructions(path), created: true };
+    }
+    async remove(identifier) {
+        const key = this.keyFor(identifier);
+        const path = this.pathFor(key);
+        await this.runGit(['-C', this.root, 'worktree', 'remove', '--force', path], this.root);
+    }
+}
+export function gitWorkspace(opts = {}) {
+    return {
+        kind: 'workspace',
+        id: 'git',
+        requiredModules: [],
+        async createWorkspace(config) {
+            const root = config.config_path
+                ? dirname(config.config_path)
+                : process.cwd();
+            return new GitWorkspace({
+                root,
+                ...(opts.branchPrefix ? { branchPrefix: opts.branchPrefix } : {}),
+                ...(opts.branchTemplate ? { branchTemplate: opts.branchTemplate } : {}),
+            });
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+/** Loads ./WORKFLOW.md from the workspace, hashing its content. */
+export declare function loadInstructions(workspacePath: string): {
+    path: string;
+    sha256: string;
+    text: string;
+} | null;

package/dist/src/plugins/workspace/instructions.js

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** Loads ./WORKFLOW.md from the workspace, hashing its content. */
+export function loadInstructions(workspacePath) {
+    const path = resolve(workspacePath, 'WORKFLOW.md');
+    if (!existsSync(path)) {
+        return null;
+    }
+    const text = readFileSync(path, 'utf8');
+    return {
+        path,
+        sha256: createHash('sha256').update(text).digest('hex'),
+        text,
+    };
+}

package/dist/src/plugins/workspace/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/workspace.js

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

package/dist/src/plugins-index.d.ts

@@ -0,0 +1 @@
+export * from './plugins/registry-exports.js';

package/dist/src/plugins-index.js

@@ -0,0 +1 @@
+export * from './plugins/registry-exports.js';

package/dist/src/types.d.ts

@@ -0,0 +1,51 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { AgentPlugin, 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. */
+    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;
+    agent: AgentPlugin;
+    workspace: WorkspacePlugin;
+    /** dropsh-layer plugins (auth etc.); separate from the GAIA slots. */
+    plugins?: DropSHPlugin[];
+}

package/dist/src/types.js

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@gaia-ai/core",
+  "version": "0.4.0",
+  "description": "GAIA global contract: plugin API, built-in remotes/workspaces/auth, shared primitives.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./plugins": "./dist/src/plugins-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/core"
+  },
+  "dependencies": {
+    "dropsh": "^0.5.1",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0"
+  }
+}