@gaia-ai/gaia 0.1.5 → 0.2.0

package/README.md

@@ -54,8 +54,8 @@ tag. Requirements:
 To reproduce the published artifact locally:
 
 ```bash
-pnpm run prepare:publish   # bundle + stage conductor/publish/
-pnpm run verify:package    # pack the staged package, install it in a temp dir, smoke-test
+pnpm run prepare:publish   # stage conductor/publish/ + each plugins/*/publish/
+pnpm run verify:package    # pack the staged set, install it in a temp dir, smoke-test
 ```
 
 ## License

package/bin/gaia

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import('../dist/index.js').then((m) => m.main(process.argv));
+import('../dist/src/index.js').then((m) => m.main(process.argv));

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

@@ -0,0 +1,24 @@
+import { type ConductorLogger } from '../core/logger.js';
+import type { GaiaAgent } from '../plugins/agent/agent.js';
+import type { GaiaExecutor } from '../plugins/executor/executor.js';
+import type { GaiaRemote } from '../plugins/remote/remote.js';
+import type { GaiaWorkspace } from '../plugins/workspace/workspace.js';
+import type { ConductorFileConfig } from '../types.js';
+/** Test seam: inject any subset of dependencies. */
+export interface GaiaCliDeps {
+    remote?: GaiaRemote;
+    executor?: GaiaExecutor;
+    workspace?: GaiaWorkspace;
+    agent?: GaiaAgent;
+    config?: ConductorFileConfig;
+}
+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 runGaiaCli(argv: string[], deps?: GaiaCliDeps): Promise<void>;
+export declare function main(argv: string[]): Promise<void>;

package/dist/src/cli/gaia.js

@@ -0,0 +1,572 @@
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { Command } from 'commander';
+import { authStatus, buildProgram as buildDropshProgram } from 'dropsh';
+import { loadConductorConfig } from '../config.js';
+import { Conductor } from '../core/conductor.js';
+import { conductorId } from '../core/conductor-id.js';
+import { CommandRunner, exec, setDefaultCommandRunner } from '../core/exec.js';
+import { createLogger } from '../core/logger.js';
+import { selectAgent, selectExecutor, selectRemote, selectWorkspace, } from '../plugins/plugins.js';
+import { machineContextPath, readMachineContext, scaffold, } from './init.js';
+import * as registry from './local-registry.js';
+/** Default config path; honors $GAIA_CONDUCTOR_CONFIG, else ./.gaia/conductor.config.js. */
+function defaultConfigPath(override) {
+    return (override ??
+        process.env.GAIA_CONDUCTOR_CONFIG ??
+        './.gaia/conductor.config.js');
+}
+async function resolveConfig(deps, configPathOverride) {
+    if (deps.config) {
+        return deps.config;
+    }
+    return loadConductorConfig(defaultConfigPath(configPathOverride));
+}
+async function resolveRemote(deps, config) {
+    return deps.remote ?? (await selectRemote(config));
+}
+function checkoutRootOf(config) {
+    return dirname(config.config_path);
+}
+/**
+ * The conductor's stable identity (gaia_conductor.machine_id). The loader
+ * always resolves this (config override or hostname+path hash), so lifecycle
+ * commands read it here instead of re-deriving the hash — otherwise a pinned
+ * machine_id and the CLI's id would diverge.
+ */
+function conductorIdOf(config) {
+    return config.machine_id ?? conductorId(checkoutRootOf(config));
+}
+/** Read the `conductor`-level --log-level / --log-sink flags from a subcommand. */
+function logOptsOf(cmd) {
+    const opts = cmd.optsWithGlobals();
+    return {
+        ...(opts.logLevel !== undefined ? { level: opts.logLevel } : {}),
+        ...(opts.logSink !== undefined ? { sink: opts.logSink } : {}),
+    };
+}
+/** Create the conductor logger (with CLI log overrides) and route all exec logging through it. */
+function loggerFor(checkoutRoot, log = {}) {
+    const logger = createLogger({ checkoutRoot, ...log });
+    setDefaultCommandRunner(new CommandRunner(logger));
+    return logger;
+}
+// --- herdr host (untested: shells out to herdr) ---------------------------
+export function parseHerdrJson(output, command) {
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        throw new Error(`herdr ${command} returned invalid JSON`);
+    }
+}
+/** Spawn a detached herdr pane running the given command in cwd. */
+async function spawnViaHerdr(label, cwd, cmd) {
+    const created = await exec('herdr', [
+        'workspace',
+        'create',
+        '--cwd',
+        cwd,
+        '--label',
+        label,
+        '--no-focus',
+    ]);
+    const parsed = parseHerdrJson(created, 'workspace create');
+    const paneId = parsed.result?.root_pane?.pane_id;
+    if (!paneId) {
+        throw new Error('herdr workspace create returned no pane id');
+    }
+    await exec('herdr', ['pane', 'run', paneId, cmd]);
+}
+/** Hard-kill a herdr-hosted conductor by its pane label. */
+async function killViaHerdr(label) {
+    const listed = await exec('herdr', ['workspace', 'list']);
+    const parsed = parseHerdrJson(listed, 'workspace list');
+    const ws = (parsed.result?.workspaces ?? []).find((w) => w.label === label);
+    if (ws?.workspace_id) {
+        await exec('herdr', ['workspace', 'close', ws.workspace_id]);
+    }
+}
+// --- ls/status freshness ----------------------------------------------------
+const DEFAULT_FRESH_S = 120;
+function freshnessThresholdS(config) {
+    return config
+        ? Math.max(DEFAULT_FRESH_S, config.lease_seconds * 2)
+        : DEFAULT_FRESH_S;
+}
+function classify(hub, freshS) {
+    // No host probe here (host calls are untested) → can't tell host-missing
+    // from wedged. registry+no-hub = registry-only; stale-hub = wedged.
+    if (!hub) {
+        return 'registry-only';
+    }
+    if (hub.status === 'offline') {
+        return 'stopped';
+    }
+    const nowS = Math.floor(Date.now() / 1000);
+    const fresh = hub.lastSeen > 0 && nowS - hub.lastSeen <= freshS;
+    return fresh ? 'running' : 'wedged';
+}
+async function buildLsRows(remote, config, onlyId) {
+    const entries = await registry.list();
+    let hub = [];
+    try {
+        hub = await remote.listConductors('me');
+    }
+    catch {
+        hub = [];
+    }
+    const hubById = new Map(hub.map((c) => [c.id, c]));
+    const freshS = freshnessThresholdS(config);
+    const ids = new Set();
+    for (const e of entries) {
+        ids.add(e.id);
+    }
+    for (const c of hub) {
+        ids.add(c.id);
+    }
+    const rows = [];
+    for (const id of ids) {
+        if (onlyId && id !== onlyId) {
+            continue;
+        }
+        const entry = entries.find((e) => e.id === id);
+        const h = hubById.get(id);
+        rows.push({
+            id,
+            project: entry?.project ?? h?.project ?? '',
+            label: entry?.label ?? h?.label ?? '',
+            host: entry?.host ?? '-',
+            status: classify(h, freshS),
+        });
+    }
+    return rows;
+}
+function printRows(rows) {
+    if (rows.length === 0) {
+        console.log('no conductors registered');
+        return;
+    }
+    for (const r of rows) {
+        console.log(`${r.id}\t${r.status}\t${r.host}\t${r.project}\t${r.label}`);
+    }
+}
+// --- command handlers -------------------------------------------------------
+/**
+ * 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 async function ensureAuthenticated(config, logger) {
+    const st = await authStatus({
+        baseUrl: config.site.base_url,
+        plugins: config.plugins ?? [],
+    });
+    if (!st.loggedIn) {
+        logger.error({ baseUrl: config.site.base_url }, `not logged in against ${config.site.base_url} — run 'gaia dropsh auth login'`);
+        return false;
+    }
+    return true;
+}
+async function cmdPoll(deps, log = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config));
+    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const agent = deps.agent ?? (await selectAgent(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    await conductor.start();
+    await conductor.tick();
+}
+async function cmdStartForeground(deps, log = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config));
+    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const agent = deps.agent ?? (await selectAgent(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    await conductor.start();
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        await conductor.serve(controller.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+    }
+}
+async function cmdStart(deps, log = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const existing = await registry.get(id);
+    if (existing) {
+        const hubStatus = await remote.getConductorStatus(id);
+        if (hubStatus !== null && hubStatus !== 'offline') {
+            console.log(`conductor already running for ${config.project}`);
+            return;
+        }
+    }
+    const handle = `gaia-conductor:${id}`;
+    await registry.register({
+        id,
+        path: checkoutRoot,
+        project: config.project,
+        label: config.label,
+        host: 'herdr',
+        handle,
+    });
+    // The detached foreground process is a fresh CLI invocation — forward the
+    // log flags so the herdr-hosted loop logs at the requested level. Sink stays
+    // forced to file (herdr-hosted = no TTY) unless the caller overrode it.
+    const fgFlags = [
+        log.level ? `--log-level ${log.level}` : '',
+        log.sink ? `--log-sink ${log.sink}` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const fgCmd = `GAIA_CONDUCTOR_LOG=file gaia conductor ${fgFlags} start --foreground`.replace(/\s+/g, ' ');
+    try {
+        await spawnViaHerdr(handle, checkoutRoot, fgCmd);
+        logger.info({ id, handle }, 'started conductor via herdr');
+    }
+    catch (err) {
+        logger.error({ id, err: err.message }, 'could not start via herdr');
+        logger.warn({}, 'Hint: run `gaia conductor start --foreground` under a service manager (systemd-user / docker) on hosts without herdr.');
+    }
+}
+async function cmdStop(deps, now) {
+    const config = await resolveConfig(deps);
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    if (now) {
+        const entry = await registry.get(id);
+        if (entry && entry.host === 'herdr') {
+            await killViaHerdr(entry.handle);
+            console.log(`hard-stopped conductor ${id} (${entry.handle})`);
+        }
+        else {
+            console.log(`no herdr-hosted conductor to hard-stop for ${id}`);
+        }
+        // A hard kill just stops the heartbeat; it never deletes the entity. The
+        // Drupal cron reaper flips the now-stale registration to offline (single
+        // authority for the offline transition — see gaia_core cron).
+        return;
+    }
+    // Graceful stop: there is no drain phase — the conductor goes offline at once,
+    // just like a hard kill, but writes offline itself instead of waiting for the
+    // cron reaper. Stop the process first (else its next heartbeat would flip it
+    // back online), then mark it offline. In-flight runs are not awaited.
+    const entry = await registry.get(id);
+    if (entry && entry.host === 'herdr') {
+        await killViaHerdr(entry.handle);
+    }
+    await remote.setConductorStatus(id, 'offline');
+    console.log(`stopped conductor ${id} (offline)`);
+}
+async function cmdLs(deps) {
+    const config = deps.config ?? (await tryConfig(deps));
+    const remote = await resolveRemote(deps, config ?? (await resolveConfig(deps)));
+    const rows = await buildLsRows(remote, config);
+    printRows(rows);
+}
+async function cmdStatus(deps) {
+    const config = await resolveConfig(deps);
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const rows = await buildLsRows(remote, config, id);
+    printRows(rows);
+}
+async function cmdRm(deps) {
+    const config = await resolveConfig(deps);
+    const id = conductorIdOf(config);
+    await registry.remove(id);
+    console.log(`removed conductor ${id} from registry`);
+}
+/** ls may run without a config file; best-effort load. */
+async function tryConfig(deps) {
+    if (deps.config) {
+        return deps.config;
+    }
+    try {
+        return await loadConductorConfig(defaultConfigPath());
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Prompt for the developer Kürzel / user id on an interactive terminal. */
+async function promptUserId() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => rl.question('Your Kürzel / user id: ', resolve));
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Prompt for the OAuth client secret without echoing the typed characters. */
+async function promptSecret() {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: true,
+    });
+    // Mute character echo while the secret is typed.
+    rl._writeToOutput = (s) => {
+        if (!rl.muted || s.includes('\n'))
+            process.stdout.write(s);
+    };
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question('OAuth client secret: ', (a) => {
+                process.stdout.write('\n');
+                resolve(a);
+            });
+            rl.muted = true;
+        });
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+// --- program ----------------------------------------------------------------
+function buildProgram(deps) {
+    const program = new Command();
+    program.name('gaia').description('GAIA conductor + client CLI');
+    const conductor = program
+        .command('conductor')
+        .description('node-agent lifecycle + local registry')
+        .option('--log-level <level>', 'log verbosity: debug | info | warn | error (overrides GAIA_LOG_LEVEL)')
+        .option('--log-sink <sink>', 'log sink: stdout | file (overrides GAIA_CONDUCTOR_LOG)')
+        .addHelpText('after', `
+Logging (precedence: CLI flag > env var > default):
+  --log-level <level>  debug | info (default) | warn | error.
+                       Set debug to see per-poll ticks, claims, and idle cycles.
+  --log-sink <sink>    stdout | file (writes <checkoutRoot>/log.txt).
+                       Default: stdout on a TTY, file otherwise.
+  GAIA_LOG_LEVEL       env fallback for --log-level.
+  GAIA_CONDUCTOR_LOG   env fallback for --log-sink.
+
+Examples:
+  gaia conductor --log-level debug start --foreground
+  gaia conductor --log-level debug poll
+  GAIA_LOG_LEVEL=debug gaia conductor poll`);
+    conductor
+        .command('start')
+        .description('start the conductor loop (herdr-hosted by default)')
+        .option('--foreground', 'run the loop in this process', false)
+        .action(async function (opts) {
+        if (opts.foreground) {
+            await cmdStartForeground(deps, logOptsOf(this));
+        }
+        else {
+            await cmdStart(deps, logOptsOf(this));
+        }
+    });
+    conductor
+        .command('poll')
+        .description('run one conductor cycle then exit')
+        .action(async function () {
+        await cmdPoll(deps, logOptsOf(this));
+    });
+    conductor
+        .command('stop')
+        .description('stop the conductor: graceful offline (default) or hard kill (--now)')
+        .option('--now', 'hard-kill via host and let the cron reaper mark it offline', false)
+        .action(async (opts) => {
+        await cmdStop(deps, opts.now);
+    });
+    conductor
+        .command('ls')
+        .description('list conductors on this machine + status')
+        .action(async () => {
+        await cmdLs(deps);
+    });
+    conductor
+        .command('status')
+        .description('status of the conductor for this checkout')
+        .action(async () => {
+        await cmdStatus(deps);
+    });
+    conductor
+        .command('rm')
+        .description('deregister the conductor for this checkout')
+        .action(async () => {
+        await cmdRm(deps);
+    });
+    conductor
+        .command('init')
+        .description('scaffold the committed .gaia/conductor.config.js for this repo plus the user-global conductor.config.machine.js context (identity + connection incl. secret)')
+        .requiredOption('--base-url <url>', 'control-plane base URL (site.base_url)')
+        .requiredOption('--project <name>', 'GAIA project name')
+        .option('--secret-env <VAR>', 'env var name to read the oauth client secret from (else TTY prompt)')
+        .option('--client-id <id>', 'oauth consumer id', 'gaia-agent')
+        .option('--machine-id <id>', 'machine host token for the context (defaults to hostname())')
+        .option('--user-id <kuerzel>', 'developer Kürzel for the user-global context')
+        .option('--machine-path <path>', 'user-global machine context path (defaults to ~/.config/conductor/conductor.config.machine.js)')
+        .option('--config <path>', 'target committed config path', './.gaia/conductor.config.js')
+        .option('--force', 'overwrite an existing committed config', false)
+        .action(async (opts) => {
+        let userId = opts.userId;
+        if (userId === undefined || userId.trim() === '') {
+            if (process.stdin.isTTY) {
+                userId = await promptUserId();
+            }
+            if (userId === undefined || userId.trim() === '') {
+                throw new Error('--user-id is required (or run in a TTY to be prompted)');
+            }
+        }
+        // The secret lives in the machine context; resolve it only when that
+        // context does not already carry one (existing values are never
+        // overwritten). Source: --secret-env value, else a TTY prompt.
+        const machinePath = opts.machinePath ?? machineContextPath();
+        const existing = await readMachineContext(machinePath);
+        let secret = '';
+        if (typeof existing.client_secret !== 'string' ||
+            existing.client_secret.trim() === '') {
+            secret =
+                opts.secretEnv !== undefined
+                    ? (process.env[opts.secretEnv] ?? '')
+                    : '';
+            if (secret.trim() === '') {
+                if (process.stdin.isTTY) {
+                    secret = await promptSecret();
+                }
+                if (secret.trim() === '') {
+                    throw new Error('OAuth client secret required: pass --secret-env <VAR> (exported) or run in a TTY to be prompted');
+                }
+            }
+        }
+        const inputs = {
+            baseUrl: opts.baseUrl,
+            project: opts.project,
+            clientId: opts.clientId,
+            secret,
+            userId,
+            ...(opts.machineId !== undefined
+                ? { machineId: opts.machineId }
+                : {}),
+        };
+        const res = await scaffold(inputs, {
+            configPath: opts.config,
+            force: opts.force,
+            machinePath,
+        });
+        console.log(res.wroteCommitted
+            ? `wrote ${res.committedPath}`
+            : `kept ${res.committedPath} (exists — pass --force to replace)`);
+        const m = res.machine;
+        console.log(m.created
+            ? `wrote ${m.path} (user-global machine context)`
+            : m.filledKeys.length > 0
+                ? `updated ${m.path} (filled: ${m.filledKeys.join(', ')})`
+                : `kept ${m.path} (already complete)`);
+        console.log(`\nNext steps:\n` +
+            `  gaia dropsh auth login --provider session\n` +
+            `  gaia dropsh auth login --provider pm\n` +
+            `  gaia dropsh auth status   # both profiles present`);
+    });
+    return program;
+}
+/**
+ * Attach the inherited dropsh CLI as a `gaia dropsh ...` subcommand.
+ *
+ * When a config is loadable, mounts the dropsh program built with the
+ * conductor's plugins (auth providers, etc.). Best-effort: if no config is
+ * loadable, the passthrough is simply not mounted.
+ *
+ * dropsh's own commands (e.g. `auth login`) reload their config from
+ * `--config` / `$DROPSH_CONFIG` / the `dropsh.config.js` default — they do not
+ * see the conductor config we already loaded. Default `$DROPSH_CONFIG` to the
+ * conductor's own config path so `gaia dropsh auth login` uses the same site +
+ * plugins without an explicit `--config` flag. An existing `$DROPSH_CONFIG`
+ * (or a `--config` flag) still wins.
+ */
+/** Actionable hint shown when a `gaia dropsh` command runs with no loadable config. */
+function dropshConfigHint(resolvedPath) {
+    return (`gaia dropsh: no conductor config could be loaded (looked at ${resolvedPath}).\n` +
+        `Point at one with --config <path>, set $DROPSH_CONFIG, or run from a directory ` +
+        `containing .gaia/conductor.config.js.`);
+}
+async function attachDropsh(program, deps) {
+    const config = deps.config ?? (await tryConfig(deps));
+    if (config && !process.env.DROPSH_CONFIG) {
+        process.env.DROPSH_CONFIG = config.config_path;
+    }
+    const dropsh = buildDropshProgram({
+        plugins: config?.plugins ?? [],
+    });
+    if (!config) {
+        // Registration is unconditional; a config problem must surface WHEN a dropsh
+        // command runs, not make the command vanish. The hook fires only on a real
+        // subcommand dispatch — never for `--help` — so discoverability holds.
+        dropsh.hook('preSubcommand', async (thisCommand) => {
+            const override = thisCommand.opts().config ??
+                process.env.DROPSH_CONFIG;
+            const resolved = defaultConfigPath(override);
+            let ok = false;
+            try {
+                await loadConductorConfig(resolved);
+                ok = true;
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok) {
+                throw new Error(dropshConfigHint(resolved));
+            }
+            if (!process.env.DROPSH_CONFIG) {
+                process.env.DROPSH_CONFIG = resolved;
+            }
+        });
+    }
+    program.addCommand(dropsh);
+}
+export async function runGaiaCli(argv, deps = {}) {
+    const program = buildProgram(deps);
+    await attachDropsh(program, deps);
+    try {
+        await program.parseAsync(argv, { from: 'user' });
+    }
+    catch (err) {
+        // The mounted dropsh program calls exitOverride(), so commander surfaces
+        // help/errors as a thrown CommanderError instead of exiting the process.
+        // `--help`/`--version` are clean exits; commander-generated errors have
+        // already written their message to stderr, so only report our own thrown
+        // errors (e.g. the dropsh missing-config hint) here.
+        const e = err;
+        if (e.code === 'commander.helpDisplayed' ||
+            e.code === 'commander.version') {
+            return;
+        }
+        if (typeof e.code === 'string' && e.code.startsWith('commander.')) {
+            process.exitCode = process.exitCode ?? 1;
+            return;
+        }
+        process.stderr.write(`${e.message ?? String(err)}\n`);
+        process.exitCode = process.exitCode ?? 1;
+    }
+}
+export async function main(argv) {
+    // Drop node + script path; commander parses the rest as user args.
+    await runGaiaCli(argv.slice(2));
+}

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

@@ -0,0 +1,74 @@
+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;
+}
+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.
+ */
+export declare function scaffold(inputs: InitInputs, opts: ScaffoldOptions): Promise<ScaffoldResult>;