@gaia-ai/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/core
+
+GAIA global contract: plugin API, built-in remotes/workspaces/auth, shared primitives.
+
+Part of the GAIA conductor. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all plugins. Source: https://git.key-tec.de/keytec/gaia (conductor/).

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

@@ -0,0 +1 @@
+export declare function conductorId(absPath: string): string;

package/dist/src/core/conductor-id.js

@@ -0,0 +1,8 @@
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+export function conductorId(absPath) {
+    return createHash('sha256')
+        .update(`${hostname()}:${absPath}`)
+        .digest('hex')
+        .slice(0, 16);
+}

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

@@ -0,0 +1,41 @@
+import type { ConductorLogger } from './logger.js';
+export declare class ExecError extends Error {
+    readonly file: string;
+    readonly args: string[];
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    constructor(file: string, args: string[], exitCode: number | null, stderr: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface ExecOpts {
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * Rewrite the args used for *logging* (both the `exec ok` debug line and the
+     * `exec failed` error line). The real args are always executed unchanged.
+     * Use this when an arg embeds a secret — e.g. herdr's `pane run` command
+     * string `KEY='value' claude` (GAIA-99) — so a failed exec never writes the
+     * secret to the log.
+     */
+    redactArgs?: (args: string[]) => string[];
+}
+export declare class CommandRunner {
+    private readonly logger;
+    constructor(logger: ConductorLogger);
+    run(file: string, args: string[], opts?: ExecOpts): Promise<string>;
+}
+/**
+ * Replace the module-level singleton runner used by {@link exec}.
+ *
+ * Note: out-of-package plugins (e.g. `@gaia-ai/plugin-herdr`) import `exec` via
+ * the `@gaia-ai/gaia/plugin` barrel, which resolves to the built `dist/`
+ * copy of this module. This means `setDefaultCommandRunner` only shares the
+ * runner with those plugins when the conductor itself runs from `dist`
+ * (production / after `pnpm build`). Under `tsx`/dev, the entry point loads
+ * this module from source while the plugin loads it from dist — two separate
+ * module instances — so plugin exec calls fall back to the noop logger.
+ * This is functionally harmless; logging only.
+ */
+export declare function setDefaultCommandRunner(r: CommandRunner): void;
+export declare function exec(file: string, args: string[], opts?: ExecOpts): Promise<string>;

package/dist/src/core/exec.js

@@ -0,0 +1,75 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export class ExecError extends Error {
+    file;
+    args;
+    exitCode;
+    stderr;
+    constructor(file, args, exitCode, stderr, options) {
+        super(`exec failed: ${file}`, options);
+        this.file = file;
+        this.args = args;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = 'ExecError';
+    }
+}
+export class CommandRunner {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async run(file, args, opts = {}) {
+        // Args can themselves carry secrets (herdr embeds `KEY='value'` in the
+        // pane-run command string — GAIA-99). `redactArgs` rewrites the args used
+        // for logging only; the real args are still executed verbatim.
+        const logArgs = opts.redactArgs ? opts.redactArgs(args) : args;
+        try {
+            const { env, redactArgs: _redact, ...rest } = opts;
+            // Merge over process.env, never replace it: a caller-supplied env adds/
+            // overrides keys but the child still inherits PATH etc. Values may be
+            // sensitive (GAIA-99) — never log them; only cwd is logged below.
+            const childEnv = env ? { ...process.env, ...env } : undefined;
+            const { stdout } = await execFileAsync(file, args, {
+                encoding: 'utf8',
+                ...rest,
+                ...(childEnv ? { env: childEnv } : {}),
+            });
+            this.logger.debug({ file, args: logArgs, cwd: opts.cwd }, 'exec ok');
+            return stdout;
+        }
+        catch (err) {
+            const e = err;
+            const exitCode = typeof e.code === 'number' ? e.code : null;
+            const stderr = e.stderr ?? '';
+            this.logger.error({ file, args: logArgs, cwd: opts.cwd, exitCode, stderr }, 'exec failed');
+            throw new ExecError(file, args, exitCode, stderr, { cause: err });
+        }
+    }
+}
+const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+let defaultRunner = new CommandRunner(noopLogger);
+/**
+ * Replace the module-level singleton runner used by {@link exec}.
+ *
+ * Note: out-of-package plugins (e.g. `@gaia-ai/plugin-herdr`) import `exec` via
+ * the `@gaia-ai/gaia/plugin` barrel, which resolves to the built `dist/`
+ * copy of this module. This means `setDefaultCommandRunner` only shares the
+ * runner with those plugins when the conductor itself runs from `dist`
+ * (production / after `pnpm build`). Under `tsx`/dev, the entry point loads
+ * this module from source while the plugin loads it from dist — two separate
+ * module instances — so plugin exec calls fall back to the noop logger.
+ * This is functionally harmless; logging only.
+ */
+export function setDefaultCommandRunner(r) {
+    defaultRunner = r;
+}
+export function exec(file, args, opts = {}) {
+    return defaultRunner.run(file, args, opts);
+}

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

@@ -0,0 +1,31 @@
+export type LogSink = {
+    kind: 'stdout';
+} | {
+    kind: 'file';
+    path: string;
+};
+export interface ConductorLogger {
+    debug(obj: object, msg?: string): void;
+    info(obj: object, msg?: string): void;
+    warn(obj: object, msg?: string): void;
+    error(obj: object, msg?: string): void;
+}
+/**
+ * Pick the log sink. Precedence: explicit CLI override (`sink`) > the
+ * GAIA_CONDUCTOR_LOG env var > TTY default (stdout on a TTY, file otherwise).
+ */
+export declare function resolveSink(env: NodeJS.ProcessEnv, isTTY: boolean, checkoutRoot: string, override?: string): LogSink;
+/**
+ * Pick the log level. Precedence: explicit CLI override (`level`) >
+ * the GAIA_LOG_LEVEL env var > info.
+ */
+export declare function resolveLevel(env: NodeJS.ProcessEnv, override?: string): string;
+export declare function createLogger(opts: {
+    checkoutRoot: string;
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** CLI override for the level — beats env + default. */
+    level?: string;
+    /** CLI override for the sink — beats env + default. */
+    sink?: string;
+}): ConductorLogger;

package/dist/src/core/logger.js

@@ -0,0 +1,36 @@
+import { join } from 'node:path';
+import pino from 'pino';
+import pretty from 'pino-pretty';
+/**
+ * Pick the log sink. Precedence: explicit CLI override (`sink`) > the
+ * GAIA_CONDUCTOR_LOG env var > TTY default (stdout on a TTY, file otherwise).
+ */
+export function resolveSink(env, isTTY, checkoutRoot, override) {
+    const fileSink = {
+        kind: 'file',
+        path: join(checkoutRoot, 'log.txt'),
+    };
+    const choice = override ?? env.GAIA_CONDUCTOR_LOG;
+    if (choice === 'stdout')
+        return { kind: 'stdout' };
+    if (choice === 'file')
+        return fileSink;
+    return isTTY ? { kind: 'stdout' } : fileSink;
+}
+/**
+ * Pick the log level. Precedence: explicit CLI override (`level`) >
+ * the GAIA_LOG_LEVEL env var > info.
+ */
+export function resolveLevel(env, override) {
+    return override ?? env.GAIA_LOG_LEVEL ?? 'info';
+}
+export function createLogger(opts) {
+    const env = opts.env ?? process.env;
+    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
+    const level = resolveLevel(env, opts.level);
+    const sink = resolveSink(env, isTTY, opts.checkoutRoot, opts.sink);
+    if (sink.kind === 'stdout') {
+        return pino({ level }, pretty({ colorize: true, sync: true }));
+    }
+    return pino({ level }, pino.destination({ dest: sink.path, append: true, mkdir: true }));
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Quote a string for safe embedding as a single shell argument, guaranteeing
+ * the result contains NO literal control bytes — critical when the command is
+ * *typed* into an interactive pty (herdr `pane run`), where a literal newline
+ * (`0x0A`) acts as Enter and submits the line early, breaking the command into
+ * still-quoted fragments so the agent invocation is never run (GAIA-101).
+ *
+ * Newline-free values use plain POSIX single-quoting (`'...'`) — byte-identical
+ * to the old quoter, so simple commands are unchanged. Values with a newline or
+ * any other control char use ANSI-C quoting (`$'...'`), which encodes those
+ * bytes as escape sequences (`\n`, `\t`, `\xHH`, …) the shell decodes back — so
+ * the argument is one logical line yet the agent still receives the newlines.
+ *
+ * Caveat: a NUL byte (`0x00`) is the one control char the shell cannot
+ * reconstruct — `$'\x00'` decodes to the empty string because a C-string argv
+ * entry is NUL-terminated. We still emit `\x00` (so no literal NUL reaches the
+ * typed pty line), but the value silently truncates there. This is an inherent
+ * POSIX-shell limit, not a bug; it never affects real LLM prompt text, which
+ * contains no NUL bytes.
+ */
+export declare function shellQuote(value: string): string;

package/dist/src/core/shell.js

@@ -0,0 +1,46 @@
+/**
+ * Quote a string for safe embedding as a single shell argument, guaranteeing
+ * the result contains NO literal control bytes — critical when the command is
+ * *typed* into an interactive pty (herdr `pane run`), where a literal newline
+ * (`0x0A`) acts as Enter and submits the line early, breaking the command into
+ * still-quoted fragments so the agent invocation is never run (GAIA-101).
+ *
+ * Newline-free values use plain POSIX single-quoting (`'...'`) — byte-identical
+ * to the old quoter, so simple commands are unchanged. Values with a newline or
+ * any other control char use ANSI-C quoting (`$'...'`), which encodes those
+ * bytes as escape sequences (`\n`, `\t`, `\xHH`, …) the shell decodes back — so
+ * the argument is one logical line yet the agent still receives the newlines.
+ *
+ * Caveat: a NUL byte (`0x00`) is the one control char the shell cannot
+ * reconstruct — `$'\x00'` decodes to the empty string because a C-string argv
+ * entry is NUL-terminated. We still emit `\x00` (so no literal NUL reaches the
+ * typed pty line), but the value silently truncates there. This is an inherent
+ * POSIX-shell limit, not a bug; it never affects real LLM prompt text, which
+ * contains no NUL bytes.
+ */
+export function shellQuote(value) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: detecting control bytes is the point
+    if (!/[\x00-\x1f\x7f]/.test(value)) {
+        return `'${value.replaceAll("'", "'\\''")}'`;
+    }
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: escaping control bytes is the point
+    const escaped = value.replace(/[\\'\x00-\x1f\x7f]/g, (ch) => {
+        switch (ch) {
+            case '\\':
+                return '\\\\';
+            case "'":
+                return "\\'";
+            case '\n':
+                return '\\n';
+            case '\t':
+                return '\\t';
+            case '\r':
+                return '\\r';
+            default: {
+                const hex = ch.charCodeAt(0).toString(16).padStart(2, '0');
+                return `\\x${hex}`;
+            }
+        }
+    });
+    return `$'${escaped}'`;
+}

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

@@ -0,0 +1,9 @@
+/** Default cap for a title slug — keeps tab labels and branch names short. */
+export declare const DEFAULT_SLUG_MAX_LENGTH = 40;
+/**
+ * Turn free text (a ticket title) into a short, ref-safe slug:
+ * lowercase, non-alphanumeric runs collapsed to `-`, trimmed, and capped to
+ * `maxLength` characters without leaving a trailing separator. Returns `''`
+ * for input that has no usable characters.
+ */
+export declare function slugify(text: string, maxLength?: number): string;

package/dist/src/core/slug.js

@@ -0,0 +1,18 @@
+/** Default cap for a title slug — keeps tab labels and branch names short. */
+export const DEFAULT_SLUG_MAX_LENGTH = 40;
+/**
+ * Turn free text (a ticket title) into a short, ref-safe slug:
+ * lowercase, non-alphanumeric runs collapsed to `-`, trimmed, and capped to
+ * `maxLength` characters without leaving a trailing separator. Returns `''`
+ * for input that has no usable characters.
+ */
+export function slugify(text, maxLength = DEFAULT_SLUG_MAX_LENGTH) {
+    const slug = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (slug.length <= maxLength) {
+        return slug;
+    }
+    return slug.slice(0, maxLength).replace(/-+$/g, '');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+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 { AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, WorkspacePlugin, } 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';

package/dist/src/index.js

@@ -0,0 +1,7 @@
+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 { loadInstructions } from './plugins/workspace/instructions.js';

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

@@ -0,0 +1,52 @@
+/**
+ * Per-agent effort footprint parsed from that agent's run transcript
+ * (GAIA-132). The metrics are transcript-derived and therefore
+ * **agent-specific** (each agent's transcript has its own format), so parsing
+ * lives behind the agent abstraction (see {@link GaiaAgent.parseFootprint}) —
+ * the conductor stays agent-agnostic and only adds `duration_s` (wall-clock,
+ * agent-independent) before writing the run's footprint.
+ */
+export interface AgentFootprint {
+    /** Total tokens across every usage bucket of every assistant turn. */
+    tokens: number;
+    /** Number of assistant turns in the transcript. */
+    agent_turns: number;
+    /** Number of tool-use calls across all assistant turns. */
+    tool_calls: number;
+    /** Number of user-submitted prompts. */
+    user_prompts: number;
+    /** Total words across those user prompts. */
+    user_prompt_words: number;
+    /** Model of the last assistant turn, when present (informational). */
+    model?: string;
+}
+/** An all-zero footprint — the honest result for an empty/absent transcript. */
+export declare function emptyAgentFootprint(): AgentFootprint;
+/**
+ * A GAIA agent: the program the conductor runs to work a ticket (e.g. claude).
+ * It knows how it is launched (CLI + model + flags) and where its per-run
+ * transcript/log lives — so the conductor stays agent-agnostic and the CLI can
+ * attach the run log on release without agent-specific knowledge.
+ */
+export interface GaiaAgent {
+    /** Stable id, e.g. 'claude'. */
+    readonly id: string;
+    /**
+     * Build the full agent CLI invocation for a GAIA prompt. With an empty
+     * prompt, returns the bare launch command (no prompt argument).
+     */
+    launchCommand(prompt: string): string;
+    /**
+     * Locate and read this agent's run transcript for a run that executed in
+     * `worktreePath`. MUST return '' (never throw) when nothing is found.
+     */
+    getRunLog(worktreePath: string): Promise<string>;
+    /**
+     * Parse this agent's run transcript (as returned by {@link getRunLog}) into
+     * a footprint of effort metrics (GAIA-132). The transcript format is
+     * agent-specific, so each agent owns its own parser. MUST be tolerant of
+     * blank/partial/absent input (never throw) — an empty log yields
+     * {@link emptyAgentFootprint}.
+     */
+    parseFootprint(log: string): AgentFootprint;
+}

package/dist/src/plugins/agent/agent.js

@@ -0,0 +1,10 @@
+/** An all-zero footprint — the honest result for an empty/absent transcript. */
+export function emptyAgentFootprint() {
+    return {
+        tokens: 0,
+        agent_turns: 0,
+        tool_calls: 0,
+        user_prompts: 0,
+        user_prompt_words: 0,
+    };
+}

package/dist/src/plugins/auth/basic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Static HTTP Basic auth provider built from an inline base64 `user:pass` token
+ * (conductor.config.local.js `auth.basic`, or the GAIA_E2E_BASIC env for tests).
+ * Returns the `{ id, authProvider }` plugin shape that dropsh's resolveAuth reads
+ * from `config.plugins`. Replaces the per-file basicAuthProvider that used to be
+ * hand-written into each dropsh.config.js.
+ */
+export declare function basicAuthProvider(tokenBase64: string): {
+    id: string;
+    authProvider: unknown;
+};

package/dist/src/plugins/auth/basic.js

@@ -0,0 +1,35 @@
+/**
+ * Static HTTP Basic auth provider built from an inline base64 `user:pass` token
+ * (conductor.config.local.js `auth.basic`, or the GAIA_E2E_BASIC env for tests).
+ * Returns the `{ id, authProvider }` plugin shape that dropsh's resolveAuth reads
+ * from `config.plugins`. Replaces the per-file basicAuthProvider that used to be
+ * hand-written into each dropsh.config.js.
+ */
+export function basicAuthProvider(tokenBase64) {
+    const authProvider = {
+        id: 'basic_auth',
+        displayName: 'HTTP Basic (inline)',
+        capabilities: { login: false, logout: false, status: true },
+        async login() {
+            throw new Error('GAIA uses static inline HTTP Basic auth.');
+        },
+        async logout() { },
+        async status() {
+            return { loggedIn: true, provider: 'basic_auth' };
+        },
+        createAdapter() {
+            return {
+                async apply(req) {
+                    return {
+                        ...req,
+                        headers: {
+                            ...(req.headers ?? {}),
+                            Authorization: `Basic ${tokenBase64}`,
+                        },
+                    };
+                },
+            };
+        },
+    };
+    return { id: 'gaia-basic-auth', authProvider };
+}

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

@@ -0,0 +1,92 @@
+export interface SpawnedSession {
+    sessionRef: string;
+}
+export interface ExecutorCapabilities {
+    persistent: boolean;
+}
+export interface SpawnRunInput {
+    ticket: {
+        uuid: string;
+        identifier: string;
+        title: string;
+        branchName: string;
+        state: string;
+        url?: string;
+    };
+    run: {
+        uuid: string;
+        id: number;
+        handler: string;
+    };
+    workspacePath: string;
+    instructions: {
+        path: string;
+        sha256: string;
+        text: string;
+    } | null;
+    command?: string;
+    env?: Record<string, string>;
+}
+/** The four lifecycle-hook slots, keyed exactly like `config.hooks`. */
+export type HookName = 'after_create' | 'before_run' | 'after_run' | 'after_done';
+/** Context for a hook invocation — carries the ticket for observable logging. */
+export interface HookContext {
+    /** The ticket identifier/uuid the hook is running for (log context). */
+    ticket: string;
+}
+export interface GaiaExecutor {
+    id: string;
+    capabilities(): ExecutorCapabilities;
+    /**
+     * Run the lifecycle hook `name` (command from `config.hooks[name]`) in `cwd`,
+     * best-effort. This is the SINGLE catch point for all lifecycle hooks:
+     *
+     * - MUST NEVER throw. No configured command → silent no-op. A failing command
+     *   → `logger.error({hook,worktree,ticket,err}, 'lifecycle hook failed')` then
+     *   return. So a hook failure never aborts dispatch or wedges a run in
+     *   `claimed`.
+     * - The underlying shell command still fails honestly (a non-zero exit
+     *   rejects); only the executor catches + logs + continues.
+     *
+     * `env`, when given, is the run's resolved environment (per-ticket env_vars
+     * merged with the core GAIA_* vars, GAIA-99), merged over the hook process's
+     * inherited env. Values may be sensitive — implementations must never log
+     * them (log key names only).
+     */
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<void>;
+    startRun(input: SpawnRunInput): Promise<SpawnedSession>;
+    /** Send C-c to every open (non-`(done)`) tab in the branch workspace and
+     * append ` (done)` to its label. Best-effort, non-destructive: tabs stay open
+     * for the human to close. */
+    retire(branch: string): Promise<void>;
+    /**
+     * Ask the agent in each open (non-`(done)`) tab of the branch workspace to
+     * exit gracefully by typing `/exit` + Enter into its pane — a clean shutdown
+     * vs {@link retire}'s C-c SIGINT. Called by the conductor's run-finalise pass
+     * once a run is done. Best-effort and non-destructive (tabs stay open); a
+     * no-op for non-persistent executors (no hosted agent pane), so the conductor
+     * gates the call on `capabilities().persistent`.
+     */
+    stopAgent(branch: string): Promise<void>;
+    /**
+     * Tear down the branch's entire worktree (git worktree + hosted workspace),
+     * reclaiming its disk. Called by the conductor's ticket-cleanup pass once a
+     * ticket is done. A no-op for non-persistent executors (no hosted workspace);
+     * the conductor gates the call on `capabilities().persistent`.
+     *
+     * `worktreePath` is the stable, identifier-derived worktree path (from the
+     * ticket's latest run). Prefer it over `branch` to resolve the worktree: the
+     * checked-out branch is mutable (the coding agent may rename/switch it), the
+     * path is not.
+     *
+     * Returns whether the worktree was actually present on THIS host and torn
+     * down (or reclaimed on disk) — i.e. whether the teardown happened locally.
+     * `false` means nothing matched here: the worktree is either already gone or
+     * lives on another conductor's host. The reaper uses this to avoid marking a
+     * ticket `cleaned_up` for a worktree it did not actually tear down (a
+     * cross-host false-teardown), leaving it for the host that physically holds
+     * it. A genuine failure still throws (surfaced as a teardown miss); a `false`
+     * return is a clean "not here", not an error.
+     */
+    removeWorktree(branch: string, worktreePath?: string): Promise<boolean>;
+}

package/dist/src/plugins/executor/executor.js

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

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

@@ -0,0 +1,44 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { ConductorLogger } from '../core/logger.js';
+import type { ConductorFileConfig } from '../types.js';
+import type { GaiaAgent } from './agent/agent.js';
+import type { GaiaExecutor } from './executor/executor.js';
+import type { GaiaRemote } from './remote/remote.js';
+import type { GaiaWorkspace } from './workspace/workspace.js';
+/** Runtime dependencies handed to a plugin factory at selection time. */
+export interface ExecutorDeps {
+    /** The in-scope conductor logger — the executor logs hook failures through it. */
+    logger: ConductorLogger;
+}
+export interface RemotePlugin extends DropSHPlugin {
+    readonly kind: 'remote';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createRemote(config: ConductorFileConfig): Promise<GaiaRemote>;
+}
+export interface ExecutorPlugin extends DropSHPlugin {
+    readonly kind: 'executor';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createExecutor(config: ConductorFileConfig, deps: ExecutorDeps): Promise<GaiaExecutor>;
+}
+export interface WorkspacePlugin extends DropSHPlugin {
+    readonly kind: 'workspace';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createWorkspace(config: ConductorFileConfig): Promise<GaiaWorkspace>;
+}
+export interface AgentPlugin extends DropSHPlugin {
+    readonly kind: 'agent';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createAgent(config: ConductorFileConfig): Promise<GaiaAgent>;
+}
+/** Resolves the remote from its named config slot. */
+export declare function selectRemote(config: ConductorFileConfig): Promise<GaiaRemote>;
+/** Resolves the executor from its named config slot, injecting the logger. */
+export declare function selectExecutor(config: ConductorFileConfig, logger: ConductorLogger): Promise<GaiaExecutor>;
+/** Resolves the workspace from its named config slot. */
+export declare function selectWorkspace(config: ConductorFileConfig): Promise<GaiaWorkspace>;
+/** Resolves the agent from its named config slot. */
+export declare function selectAgent(config: ConductorFileConfig): Promise<GaiaAgent>;

package/dist/src/plugins/plugins.js

@@ -0,0 +1,16 @@
+/** Resolves the remote from its named config slot. */
+export async function selectRemote(config) {
+    return config.remote.createRemote(config);
+}
+/** Resolves the executor from its named config slot, injecting the logger. */
+export async function selectExecutor(config, logger) {
+    return config.executor.createExecutor(config, { logger });
+}
+/** Resolves the workspace from its named config slot. */
+export async function selectWorkspace(config) {
+    return config.workspace.createWorkspace(config);
+}
+/** Resolves the agent from its named config slot. */
+export async function selectAgent(config) {
+    return config.agent.createAgent(config);
+}

package/dist/src/plugins/registry-exports.d.ts

@@ -0,0 +1,6 @@
+export { basicAuthProvider } from './auth/basic.js';
+export { selectAgent, selectExecutor, selectRemote, selectWorkspace, } from './plugins.js';
+export { DrupalGaiaRemote, drupalRemote } from './remote/drupal.js';
+export { FakeGaiaRemote, type FakeRemoteSeed, fakeRemote, } from './remote/fake.js';
+export { FakeWorkspace, fakeWorkspace } from './workspace/fake.js';
+export { GitWorkspace, gitWorkspace } from './workspace/git.js';

package/dist/src/plugins/registry-exports.js

@@ -0,0 +1,6 @@
+export { basicAuthProvider } from './auth/basic.js';
+export { selectAgent, selectExecutor, selectRemote, selectWorkspace, } from './plugins.js';
+export { DrupalGaiaRemote, drupalRemote } from './remote/drupal.js';
+export { FakeGaiaRemote, fakeRemote, } from './remote/fake.js';
+export { FakeWorkspace, fakeWorkspace } from './workspace/fake.js';
+export { GitWorkspace, gitWorkspace } from './workspace/git.js';