@gaia-ai/conductor 0.0.1

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

@@ -0,0 +1,82 @@
+export interface InitInputs {
+    baseUrl: string;
+    project: string;
+    clientId: string;
+    /** The resolved OAuth client secret value (stored in the machine context). */
+    secret: string;
+    machineId?: string;
+    userId?: string;
+}
+export interface ScaffoldOptions {
+    configPath: string;
+    force: boolean;
+    machinePath?: string;
+    /** When true, scaffold the committed config only — never read/write the machine context. */
+    skipMachine?: boolean;
+    /** When true, scaffold the machine context only — never write the committed config. */
+    skipCommitted?: boolean;
+}
+export interface ScaffoldResult {
+    committedPath: string;
+    wroteCommitted: boolean;
+    machine: MachineContextResult;
+}
+/**
+ * The user-global machine context: a plain importable module carrying the
+ * developer's machine identity and connection (incl. the OAuth client secret).
+ * Committed configs import it to compose machine_id and read
+ * base_url / client_id / client_secret. Gitignored, user-only (chmod 0600).
+ */
+export interface MachineContext {
+    machine_id: string;
+    user_id: string;
+    base_url: string;
+    client_id: string;
+    client_secret: string;
+}
+export interface MachineContextOptions {
+    path: string;
+    userId: string;
+    baseUrl: string;
+    clientId: string;
+    secret: string;
+    machineId?: string;
+}
+export interface MachineContextResult {
+    path: string;
+    created: boolean;
+    filledKeys: string[];
+}
+/**
+ * The committed, structural conductor config. `project` is the only per-repo
+ * value and is baked in here; connection + identity (incl. the secret) come from
+ * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
+ * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
+ * optional, gitignored conductor.config.local.js beside this file may override
+ * any field — it is loaded if present but never created by `gaia conductor init`.
+ */
+export declare function renderCommittedConfig(inputs: Pick<InitInputs, 'project'>): string;
+/** The user-global machine context module: identity + connection (incl. secret). */
+export declare function renderMachineContext(ctx: MachineContext): string;
+/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
+export declare function machineContextPath(): string;
+/** Import an existing context module's default export, or {} if absent/broken. */
+export declare function readMachineContext(path: string): Promise<Partial<MachineContext>>;
+/**
+ * Create-if-missing / fill-only-missing the user-global machine context.
+ * Existing values always win; only absent/blank keys are filled. machine_id
+ * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
+ * The file is written user-only (chmod 0600) since it holds the client secret.
+ */
+export declare function scaffoldMachineContext(opts: MachineContextOptions): Promise<MachineContextResult>;
+/**
+ * Scaffold the two conductor config files: the committed conductor.config.js
+ * (created only if missing — never overwritten unless `force`) and the
+ * user-global machine context (create-if-missing / fill-only-missing). The
+ * optional per-project conductor.config.local.js is NOT generated.
+ *
+ * `skipMachine` writes the committed config only (project-only setup); its
+ * mirror `skipCommitted` writes the machine context only (machine-only
+ * onboarding, no repo). Setting both is a no-op.
+ */
+export declare function scaffold(inputs: InitInputs, opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/src/cli/init.js

@@ -0,0 +1,232 @@
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** JS single-quoted string literal for a trusted, simple value. */
+function q(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/**
+ * The committed, structural conductor config. `project` is the only per-repo
+ * value and is baked in here; connection + identity (incl. the secret) come from
+ * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
+ * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
+ * optional, gitignored conductor.config.local.js beside this file may override
+ * any field — it is loaded if present but never created by `gaia conductor init`.
+ */
+export function renderCommittedConfig(inputs) {
+    return `// Canonical GAIA conductor config — committed. Connection + identity come from
+// your user-global machine context (~/.config/conductor/conductor.config.machine.js:
+// { machine_id, user_id, base_url, client_id, client_secret }); machine_id is
+// composed here as \`\${user_id}-\${machine_id}-\${project}\`. \`project\` is the only
+// per-repo value and is baked in below. The client_secret is read from the
+// machine context (gitignored, user-only) — never committed here.
+//
+// IMPORT-FREE (GAIA-78): the plugin slots + plugins[] are \`{ plugin, with }\`
+// descriptors naming the REAL published package (\`@gaia-ai/plugin-*\`,
+// \`@dropsh/plugin-*\`), not \`import\`ed constructors. loadConductorConfig
+// resolves each name ESLint-style (config dir → cwd → conductor install), so
+// config load never depends on a \`node_modules/@gaia-ai\` symlink beside this
+// file. Each plugin package default-exports its factory, so the resolver's
+// auto-pick needs no \`export:\` here — only the \`@gaia-ai/gaia/plugins\` host
+// barrel (many exports) still names one via \`export: 'drupalRemote'\`.
+
+// The user-global machine context: identity + connection (incl. secret), shared
+// by every project on this machine. Never committed.
+async function loadMachine() {
+  try {
+    return (await import(\`\${process.env.HOME}/.config/conductor/conductor.config.machine.js\`)).default ?? {};
+  } catch {}
+  return {};
+}
+
+// OPTIONAL per-project override — create conductor.config.local.js beside this
+// file to override any field (machine_id, base_url, model, …). It is loaded only
+// if present and is NOT created by \`gaia conductor init\`.
+async function loadLocal() {
+  try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
+  return {};
+}
+
+const machine = await loadMachine();
+const local = await loadLocal();
+const project = local.project ?? ${q(inputs.project)};
+const baseUrl = local.base_url ?? machine.base_url;
+const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
+const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
+const composedMachineId =
+  machine.user_id && machine.machine_id
+    ? \`\${machine.user_id}-\${machine.machine_id}-\${project}\`
+    : undefined;
+
+export default {
+  site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
+  project,
+  machine_id: local.machine_id ?? composedMachineId,
+  states: ['spec', 'diagnose', 'coding', 'review'],
+  max_parallel: 5,
+  // Lifecycle hooks are executor-owned (GAIA-84): the executor invokes each
+  // best-effort (logs loudly + continues, never aborts a run), so they live at
+  // the config top level — NOT on a plugin descriptor's \`with.hooks\`.
+  hooks: { after_create: 'ddev init-worktree', after_done: 'ddev delete -Oy' },
+  remote: { plugin: '@gaia-ai/gaia/plugins', export: 'drupalRemote' },
+  // No hard-wired diff pane for review: the review diff surface is hunk
+  // (GAIA-55) — agent-driven + opt-in in the human's interactive pane, not an
+  // executor-forced git-diff pane. Clicking a changed file in that hunk pane
+  // opens it editable in a spiceedit overlay (see conductor/README.md).
+  executor: { plugin: '@gaia-ai/plugin-herdr' },
+  agent: {
+    plugin: '@gaia-ai/plugin-claude',
+    with: { model: local.model ?? 'claude-opus-4-8' },
+  },
+  workspace: {
+    plugin: '@gaia-ai/plugin-herdr-workspace',
+  },
+  // oauth2 is a real dep of the host (npm installs it alongside @gaia-ai/gaia).
+  // NOTE: plugins[] is consumed by DROPSH, which reloads this config with its OWN
+  // resolver (\`export ?? 'default'\`, no sole-function auto-pick) on every
+  // \`gaia dropsh …\` command. @dropsh/plugin-oauth2 has no default export, so
+  // these entries MUST name \`export: 'oauth2Plugin'\` — unlike the four conductor
+  // slots above, which the conductor resolves and auto-picks.
+  plugins: [
+    {
+      plugin: '@dropsh/plugin-oauth2',
+      export: 'oauth2Plugin',
+      with: {
+        id: 'session',
+        default: true,
+        type: 'oauth2_client_credentials',
+        client_id: clientId,
+        client_secret: clientSecret,
+        token_url: \`\${baseUrl}/oauth/token\`,
+        scope: 'gaia:session',
+      },
+    },
+    {
+      plugin: '@dropsh/plugin-oauth2',
+      export: 'oauth2Plugin',
+      with: {
+        id: 'pm',
+        type: 'oauth2_client_credentials',
+        client_id: clientId,
+        client_secret: clientSecret,
+        token_url: \`\${baseUrl}/oauth/token\`,
+        scope: 'gaia:project_manager',
+      },
+    },
+  ],
+};
+`;
+}
+/** The user-global machine context module: identity + connection (incl. secret). */
+export function renderMachineContext(ctx) {
+    return `// User-global conductor context — gitignored, user-only (chmod 0600), never
+// committed. A plain importable module holding your machine identity +
+// connection, incl. the OAuth client secret. Committed conductor.config.js files
+// import this to compose machine_id (\`\${user_id}-\${machine_id}-\${project}\`) and
+// read base_url / client_id / client_secret. Created and gap-filled by
+// \`gaia conductor init\`; existing values are never overwritten.
+export default {
+  machine_id: ${q(ctx.machine_id)},
+  user_id: ${q(ctx.user_id)},
+  base_url: ${q(ctx.base_url)},
+  client_id: ${q(ctx.client_id)},
+  client_secret: ${q(ctx.client_secret)},
+};
+`;
+}
+/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
+export function machineContextPath() {
+    return join(process.env.HOME ?? '', '.config', 'conductor', 'conductor.config.machine.js');
+}
+/** Import an existing context module's default export, or {} if absent/broken. */
+export async function readMachineContext(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        // Cache-bust so a re-render within one process re-reads fresh.
+        const mod = await import(`${pathToFileURL(path).href}?t=${Date.now()}`);
+        const raw = mod.default;
+        return raw && typeof raw === 'object'
+            ? raw
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Create-if-missing / fill-only-missing the user-global machine context.
+ * Existing values always win; only absent/blank keys are filled. machine_id
+ * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
+ * The file is written user-only (chmod 0600) since it holds the client secret.
+ */
+export async function scaffoldMachineContext(opts) {
+    const existing = await readMachineContext(opts.path);
+    const derived = {
+        machine_id: opts.machineId ?? hostname(),
+        user_id: opts.userId,
+        base_url: opts.baseUrl,
+        client_id: opts.clientId,
+        client_secret: opts.secret,
+    };
+    const filledKeys = [];
+    const merged = { ...derived, ...existing };
+    for (const key of [
+        'machine_id',
+        'user_id',
+        'base_url',
+        'client_id',
+        'client_secret',
+    ]) {
+        const cur = existing[key];
+        if (typeof cur !== 'string' || cur.trim() === '') {
+            merged[key] = derived[key];
+            filledKeys.push(key);
+        }
+    }
+    const created = !existsSync(opts.path);
+    if (filledKeys.length > 0 || created) {
+        mkdirSync(dirname(opts.path), { recursive: true });
+        writeFileSync(opts.path, renderMachineContext(merged), 'utf8');
+    }
+    // Always tighten perms — the file holds a secret.
+    if (existsSync(opts.path))
+        chmodSync(opts.path, 0o600);
+    return { path: opts.path, created, filledKeys };
+}
+/**
+ * Scaffold the two conductor config files: the committed conductor.config.js
+ * (created only if missing — never overwritten unless `force`) and the
+ * user-global machine context (create-if-missing / fill-only-missing). The
+ * optional per-project conductor.config.local.js is NOT generated.
+ *
+ * `skipMachine` writes the committed config only (project-only setup); its
+ * mirror `skipCommitted` writes the machine context only (machine-only
+ * onboarding, no repo). Setting both is a no-op.
+ */
+export async function scaffold(inputs, opts) {
+    const committedPath = opts.configPath;
+    let wroteCommitted = false;
+    if (!opts.skipCommitted) {
+        mkdirSync(dirname(committedPath), { recursive: true });
+        if (!existsSync(committedPath) || opts.force) {
+            writeFileSync(committedPath, renderCommittedConfig(inputs), 'utf8');
+            wroteCommitted = true;
+        }
+    }
+    const machinePath = opts.machinePath ?? machineContextPath();
+    const machine = opts.skipMachine
+        ? { path: machinePath, created: false, filledKeys: [] }
+        : await scaffoldMachineContext({
+            path: machinePath,
+            userId: inputs.userId ?? '',
+            baseUrl: inputs.baseUrl,
+            clientId: inputs.clientId,
+            secret: inputs.secret,
+            ...(inputs.machineId !== undefined
+                ? { machineId: inputs.machineId }
+                : {}),
+        });
+    return { committedPath, wroteCommitted, machine };
+}

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,56 @@
+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;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,51 @@
+import type { ConductorFileConfig } from '@gaia-ai/core';
+/**
+ * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
+ * the agent must stop instead of running the whole flow in one session. The run
+ * is closed automatically when the ticket state changes on the next claim - the
+ * agent does not release it. Run mechanics live here (not in the repo's
+ * WORKFLOW.md). The prompt routes through the gaia skill (`ticket:run`) rather
+ * than pointing at WORKFLOW.md directly (GAIA-125): the intake splash + state
+ * engine are a skill mechanic, so a bare "follow WORKFLOW.md" pointer left the
+ * splash unrendered unless an external skill-forcing hook happened to fire. A
+ * conductor config may override via the `prompt` field.
+ *
+ * The ticket + its comments are NOT embedded (GAIA-112): embedding unbounded
+ * ticket content into a single typed pane line overran the PTY canonical line
+ * cap and truncated the dispatch command. Instead the prompt is a bounded,
+ * constant-size pointer and the agent reads the ticket + all comments at run
+ * start via `gaia dropsh read … --include comments`.
+ *
+ * HINT — the canonical cap is platform-specific: MAX_CANON is 4096 B on Linux
+ * but only 1024 B on macOS (a whole line >= 1024 B is silently DROPPED there).
+ * herdr types env-prefix + this prompt + flags as ONE line, so keep the total
+ * well under 1024 B — i.e. keep this prompt short (~a few hundred bytes). Do NOT
+ * grow it back toward the old ~1 KB, or macOS dispatch truncates silently again.
+ *
+ * The prompt is a SINGLE LINE — no newlines, no control chars (GAIA-128). herdr
+ * types it into the pane as one line, so a newline would submit early and any
+ * control char would force bash-only `$'…'` quoting that fish can't parse.
+ * Being single-line + bounded, plain `'…'` shell-quoting suffices (fish-safe)
+ * and the typed line stays well under the cap (1024 B on macOS, 4096 B on Linux)
+ * — so NO base64/`bash -c` wrapper and NO multiline handling are needed (that
+ * wrapper, GAIA-118, was the thing that re-inflated the line past the cap and
+ * truncated it mid-quote).
+ * Placeholders: `{identifier}`, `{state}`, `{runUuid}` ({state} falls back to
+ * `triage` for unclassified tickets).
+ */
+export declare const DEFAULT_AGENT_PROMPT: string;
+/**
+ * Resolve the conductor config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$GAIA_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.gaia/` dir holding `*.config.js`
+ *    — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves
+ *      `<gaiaDir>/<name>.config.js` (error listing the stems if absent).
+ *    - No selector: exactly one config → use it (back-compat: the lone
+ *      `conductor.config.js`); many → error naming the stems + the selector.
+ * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error
+ *    (never leak a raw "Cannot find module" from a later import()).
+ */
+export declare function resolveConfigPath(override?: string, cwd?: string, conductorName?: string): string;
+export declare function loadConductorConfig(configFile: string): Promise<ConductorFileConfig>;