agent-tempo 1.0.1

package/dist/server.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto = __importStar(require("crypto"));
+const os = __importStar(require("os"));
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const client_1 = require("@temporalio/client");
+const config_1 = require("./config");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { version: PKG_VERSION } = require('../package.json');
+const connection_1 = require("./connection");
+const daemon_1 = require("./cli/daemon");
+const git_info_1 = require("./git-info");
+// #450 self-bootstrap path uses the typed default-part helper for the
+// player-type-aware fallback string. Lives here (not in server-tools) because
+// it's invoked at MCP-server boot time before the tool surface lands.
+const default_part_1 = require("./utils/default-part");
+// #131 Phase C — every tool registration now lives in `server-tools.ts` so
+// the claude-api adapter's in-process MCP server registers the same surface
+// without per-tool drift between the two callsites.
+const server_tools_1 = require("./server-tools");
+const adapters_1 = require("./adapters");
+const agent_types_1 = require("./ensemble/agent-types");
+const parent_death_watchdog_1 = require("./utils/parent-death-watchdog");
+const log = (...args) => console.error('[agent-tempo]', ...args);
+async function main() {
+    (0, parent_death_watchdog_1.installParentDeathWatchdog)();
+    // Only activate when explicitly opted in via AGENT_TEMPO_ENSEMBLE
+    if (!process.env[config_1.ENV.ENSEMBLE]) {
+        log(`${config_1.ENV.ENSEMBLE} not set — MCP server idle (no workflow started)`);
+        // Keep the process alive so Claude Code doesn't see a crash, but do nothing
+        const transport = new stdio_js_1.StdioServerTransport();
+        const idleServer = new mcp_js_1.McpServer({ name: 'agent-tempo', version: PKG_VERSION });
+        await idleServer.connect(transport);
+        return;
+    }
+    const config = (0, config_1.getConfig)();
+    const isConductor = process.env[config_1.ENV.CONDUCTOR] === 'true';
+    const requestedName = process.env[config_1.ENV.PLAYER_NAME] || '';
+    // Conductors use their requested name or fall back to 'conductor'.
+    // Non-conductors are prevented from using "conductor" as a name,
+    // which would collide with the conductor's deterministic workflow ID.
+    let playerId = isConductor
+        ? (requestedName || 'conductor')
+        : (requestedName && requestedName !== 'conductor' ? requestedName : '') || crypto.randomBytes(4).toString('hex');
+    const getPlayerId = () => playerId;
+    const setPlayerId = (id) => { playerId = id; };
+    const workDir = process.cwd();
+    const { gitRoot, gitBranch } = (0, git_info_1.getGitInfo)(workDir);
+    log(`Starting ${isConductor ? 'conductor' : `peer ${playerId}`} in ${workDir}`);
+    // Connect Temporal client — friendly error messages for common failures
+    let connection;
+    try {
+        connection = await (0, connection_1.createTemporalConnection)(config);
+    }
+    catch (err) {
+        const code = err?.code || '';
+        const msg = err?.message || String(err);
+        if (code === 'ECONNREFUSED' || msg.includes('ECONNREFUSED')) {
+            log(`Cannot connect to Temporal at ${config.temporalAddress} — is the server running?`);
+            log('  Start it with: temporal server start-dev');
+        }
+        else if (msg.includes('ENOENT') || msg.includes('no such file')) {
+            log(`TLS certificate/key file not found: ${msg}`);
+            log('  Check TEMPORAL_TLS_CERT_PATH and TEMPORAL_TLS_KEY_PATH');
+        }
+        else {
+            log(`Failed to connect to Temporal: ${msg}`);
+        }
+        process.exit(1);
+    }
+    const client = new client_1.Client({
+        connection,
+        namespace: config.temporalNamespace,
+    });
+    // Ensure the worker daemon is running (starts it if needed).
+    // Sessions no longer run in-process workers — the daemon handles all task processing.
+    if (!(0, daemon_1.isDaemonRunning)()) {
+        log('Worker daemon not running — starting it...');
+        try {
+            const daemonPid = await (0, daemon_1.startDaemon)(config);
+            log(`Worker daemon started (pid ${daemonPid})`);
+        }
+        catch (err) {
+            log(`Failed to start worker daemon: ${err?.message || err}`);
+            log('Start it manually with: agent-tempo daemon start');
+            process.exit(1);
+        }
+    }
+    else {
+        log('Worker daemon already running');
+    }
+    // Start the session workflow
+    const workflowId = isConductor
+        ? (0, config_1.conductorWorkflowId)(config.ensemble)
+        : `agent-session-${config.ensemble}-${playerId}`;
+    const isBridgeMode = process.env[config_1.ENV.BRIDGE_MODE] === '1';
+    // PR-B (v0.25 step 2/7): resolve the adapter descriptor through the registry.
+    // `isBridgeMode` is the legacy signal — set by the Copilot bridge when it spawns
+    // this MCP server as a child. PR-C will replace this with the attachment wire
+    // protocol. Until then, the registry lookup is purely informational on the
+    // server-side and the real dispatch is still driven by isBridgeMode.
+    const adapterId = isBridgeMode ? 'copilot' : 'claude-code';
+    const adapterDescriptor = adapters_1.registry.get(adapterId);
+    const sessionInput = {
+        metadata: {
+            playerId,
+            ensemble: config.ensemble,
+            hostname: os.hostname(),
+            workDir,
+            gitRoot,
+            gitBranch,
+            isConductor,
+            agentType: isBridgeMode ? 'copilot' : 'claude',
+            adapterId,
+        },
+        // Issue #450 — self-bootstrap path has no resolved player type, so
+        // this falls through to `'Conductor session'` for conductors and
+        // `'Session in <basename>'` otherwise. Routed through the helper so
+        // any future server-side player-type discovery picks up the typed
+        // default automatically.
+        autoSummary: (0, default_part_1.defaultPart)({ isConductor, workDir, adapterType: isBridgeMode ? 'copilot' : 'claude' }),
+        temporalConfig: {
+            temporalAddress: config.temporalAddress,
+            temporalNamespace: config.temporalNamespace,
+            taskQueue: config.taskQueue,
+        },
+    };
+    const startedHandle = await client.workflow.start('agentSessionWorkflow', {
+        workflowId,
+        taskQueue: config.taskQueue,
+        args: [sessionInput],
+        workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+        // No execution timeout — workflows live until terminated status or stale detection.
+        searchAttributes: {
+            ...(gitRoot ? { AgentTempoGitRoot: [gitRoot] } : {}),
+            AgentTempoHostname: [os.hostname()],
+            AgentTempoEnsemble: [config.ensemble],
+            AgentTempoPlayerId: [playerId],
+        },
+    });
+    log(`Workflow ${workflowId} started (or reconnected)`);
+    // #347 — every tool that calls `executeUpdate` / `signal` / `query` on
+    // the session's own workflow MUST use an UNPINNED handle (no
+    // `firstExecutionRunId` field). The handle returned by
+    // `client.workflow.start()` carries `firstExecutionRunId` set to the
+    // run that was current when start() resolved; once the workflow does
+    // any `continueAsNew`, that run is no longer the FIRST of the chain
+    // and Temporal rejects update RPCs with `WorkflowNotFoundError`. The
+    // architect's outbox went silent because every force-restart reset
+    // the handle to a fresh-but-soon-stale `firstExecutionRunId`. Using
+    // `client.workflow.getHandle(workflowId)` (no runId) omits chain
+    // validation entirely and routes every operation to the latest open
+    // run regardless of CAN history. See
+    // `test/session-can-handle-staleness.test.ts` for the structural
+    // proof + stale-firstExecutionRunId reproducer.
+    const handle = client.workflow.getHandle(workflowId);
+    // Watch for workflow completion — exit the process when the workflow ends
+    // (e.g., via stop tool setting status to 'terminated'). Use the
+    // started handle (`runIdForResult` = the started run's id) so
+    // `result()` follows the CAN chain via `followRuns: true` and resolves
+    // when the entire chain ends, not on a single CAN boundary.
+    // Note: daemon is NOT stopped here — it serves all sessions, not just this one.
+    startedHandle.result().then(() => {
+        log('Workflow completed — shutting down');
+        stopPoller();
+        process.exit(0);
+    }).catch((err) => {
+        // Only exit on workflow-level errors (cancelled, failed), not transient connection errors
+        const name = err?.name || '';
+        if (name.includes('WorkflowFailed') || name.includes('WorkflowCancelled') || name.includes('WorkflowNotFound')) {
+            log('Workflow ended unexpectedly — shutting down');
+            stopPoller();
+            process.exit(1);
+        }
+        else {
+            log('Transient error watching workflow result:', err?.message || err);
+        }
+    });
+    // Resolve player type identity from env (set by recruiter's spawnProcess)
+    const playerType = process.env[config_1.ENV.PLAYER_TYPE] || undefined;
+    let playerTypeDescription;
+    if (playerType) {
+        try {
+            const info = (0, agent_types_1.resolveAgentType)(playerType);
+            playerTypeDescription = info?.description;
+        }
+        catch {
+            // Resolution failure is non-fatal — type is still set
+        }
+    }
+    // If the workflow was pre-created by a recruiter, update it with real metadata
+    // now that it's connected. Attachment phase (not the removed `status` field)
+    // is driven by the V2 wire surface — see claimAttachment / adapterExited.
+    await handle.signal('updateMetadata', {
+        hostname: os.hostname(),
+        gitRoot,
+        gitBranch,
+        enableStaleDetection: true,
+        ...(playerType ? { playerType } : {}),
+        ...(playerTypeDescription ? { playerTypeDescription } : {}),
+    });
+    // If there's a conductor running, announce ourselves
+    if (!isConductor) {
+        try {
+            const conductorHandle = client.workflow.getHandle((0, config_1.conductorWorkflowId)(config.ensemble));
+            await conductorHandle.signal('receiveMessage', {
+                from: playerId,
+                text: `Player ${playerId} joined from ${workDir}`,
+                responseRequested: false,
+            });
+        }
+        catch {
+            // No conductor running — that's fine
+        }
+    }
+    // If ensemble is paused, inherit the paused state
+    try {
+        const maestroHandle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
+        const isPaused = await maestroHandle.query('maestroPaused');
+        if (isPaused) {
+            await handle.signal('setPaused', true);
+            log('Ensemble is paused — session started in paused state');
+        }
+    }
+    catch {
+        // Maestro may not be running — that's fine
+    }
+    // Create MCP server
+    const hasRequestedName = isConductor || Boolean(requestedName && requestedName !== 'conductor');
+    const ownAgentType = isBridgeMode ? 'copilot' : 'claude';
+    const serverInstructions = (0, server_tools_1.buildServerInstructions)({
+        ensemble: config.ensemble,
+        playerId,
+        playerType,
+        playerTypeDescription,
+        isConductor,
+        hasRequestedName,
+    });
+    const mcpServer = new mcp_js_1.McpServer({
+        name: 'agent-tempo',
+        version: PKG_VERSION,
+    }, {
+        capabilities: {
+            experimental: { 'claude/channel': {} },
+        },
+        instructions: serverInstructions,
+    });
+    // Register every tempo tool via the shared helper. The claude-api adapter
+    // (#131) builds the same surface against an in-process MCP server using
+    // the same call. Adding a new tool? Add it once in `server-tools.ts`.
+    (0, server_tools_1.registerAllTempoTools)(mcpServer, {
+        client, config, getPlayerId, setPlayerId, handle, workflowId,
+        ownAgentType, isConductor,
+    });
+    const MAESTRO_ACK = '\n\n[IMPORTANT: This message is from a human (Maestro). Immediately cue the sender back with a brief acknowledgment and your planned next step before doing the work.]';
+    // Start message poller — push messages into Claude Code via channel notifications.
+    // SDK-class adapters (e.g. Copilot bridge) run their own delivery loop in the
+    // bridge subprocess; this MCP server is just the tool surface for that bridge,
+    // and must NOT also poll (would race on markDelivered, and SDK adapters don't
+    // understand notifications/claude/channel).
+    //
+    // Dispatch by adapterClass from the registry (PR-B). Pass client + host so
+    // the adapter can claim the attachment — `InteractiveAttachment` runs the
+    // V2 attachment-lease lifecycle for the attachment's lifetime. PR-H (#132)
+    // removed the `AGENT_TEMPO_LIFECYCLE_V2=0` legacy-shim branch; V2 is the
+    // only path.
+    const stopPoller = adapterDescriptor.adapterClass === 'sdk'
+        ? () => { } // no-op — SDK adapters handle delivery in their own subprocess
+        : new adapters_1.InteractiveAttachment({ client, host: os.hostname() }).start(handle, async (messages) => {
+            for (const msg of messages) {
+                log(`Message from ${msg.from}: ${msg.text}`);
+                const content = msg.isMaestro ? msg.text + MAESTRO_ACK : msg.text;
+                try {
+                    await mcpServer.server.notification({
+                        method: 'notifications/claude/channel',
+                        params: {
+                            content,
+                            meta: {
+                                from_player: msg.from,
+                                sent_at: msg.timestamp,
+                            },
+                        },
+                    });
+                }
+                catch (err) {
+                    log('Channel notification error:', err);
+                }
+            }
+        });
+    // Connect MCP transport
+    const transport = new stdio_js_1.StdioServerTransport();
+    await mcpServer.connect(transport);
+    log('MCP server connected');
+    // Graceful shutdown (idempotent — safe to call multiple times)
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log('Shutting down...');
+        // Hard exit safety net in case graceful shutdown hangs
+        const hardExit = setTimeout(() => {
+            log('Shutdown timeout — forcing exit');
+            process.exit(1);
+        }, 20_000);
+        hardExit.unref();
+        // 1. Stop the message poller — V2 adapter fires `adapterExited` (graceful=true)
+        //    from inside `stopV2Lifecycle`, collapsing the workflow `draining → detached`
+        //    per §11.1. Closing our terminal should NOT destroy the workflow — the user
+        //    can re-attach later via `restart`. PR-C commit 4 retired the former
+        //    `updateMetadata({ status: 'terminated' })` signal here (it destroyed the
+        //    session on every SIGINT, defeating the phase split). Operator-initiated
+        //    destruction now goes through the `destroy` tool / CLI, which uses
+        //    `destroyUpdate` directly.
+        stopPoller();
+        // 2. Close Temporal connection (daemon is left running — it serves all sessions)
+        try {
+            connection.close();
+        }
+        catch {
+            // best effort
+        }
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/spawn.d.ts

@@ -0,0 +1,296 @@
+import type { MockMode } from './types';
+import type { ClaudeCodeHeadlessPermissionMode } from './adapters/claude-code-headless/types';
+/** Resolve the absolute path to the package's icon file (PNG for Windows Terminal). */
+export declare function resolveIconPath(): string;
+/**
+ * Ensure a "agent-tempo" profile exists in Windows Terminal settings.json
+ * with our icon. Returns true if the profile is ready for use.
+ *
+ * Windows Terminal settings path:
+ *   %LOCALAPPDATA%/Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json
+ */
+export declare function ensureWindowsTerminalProfile(): boolean;
+/** POSIX shell-safe single-quoting (works in bash, zsh, and fish) */
+export declare function shellQuote(s: string): string;
+/**
+ * Resolve the path to the `claude` binary.
+ *
+ * Resolution order:
+ *  1. `configBin` parameter (from Config.claudeBin — env var or config file)
+ *  2. `AGENT_TEMPO_CLAUDE_BIN` env var (checked directly for spawned processes that
+ *     may not have full config resolution, e.g., activities)
+ *  3. `which claude` / `where claude` lookup
+ *  4. Bare `claude` fallback
+ */
+export declare function resolveClaudePath(configBin?: string): string;
+/**
+ * Detect the macOS terminal the user is actually running in.
+ *
+ * Priority:
+ *  1. TERM_PROGRAM env var (most reliable when available — set by the terminal itself)
+ *  2. Check frontmost app via AppleScript (detects what the user is actively using)
+ *  3. Fall back to Terminal.app
+ */
+export declare function detectMacTerminal(): 'ghostty' | 'iterm2' | 'terminal';
+/** Find the first available terminal emulator on Linux */
+export declare function findLinuxTerminal(): string | null;
+/**
+ * Build a shell command string that sets env vars and runs claude.
+ * Uses inline `KEY=val` syntax which works in bash, zsh, AND fish.
+ */
+export declare function buildClaudeCommand(claudeBin: string, claudeArgs: string[], envVars: Record<string, string>): string;
+/**
+ * Spawn a Claude Code session in a visible terminal window.
+ *
+ * Strategy per terminal:
+ *  - Ghostty: `initial input` into a normal window (preserves full shell env)
+ *  - iTerm2: `write text` via AppleScript (same approach)
+ *  - Terminal.app: .command script with shell profile sourcing
+ *  - Windows: shell:true with env vars
+ *  - Linux: terminal emulator with -e flag
+ */
+export declare function spawnInTerminal(claudeArgs: string[], workDir: string, envVars: Record<string, string>, options?: {
+    claudeBin?: string;
+}): {
+    pid: number | undefined;
+};
+export interface CopilotBridgeOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log and PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /** Copilot SDK session ID for resumable sessions. */
+    sessionId?: string;
+    /**
+     * PR-D attachment-lease handoff. When present, the workflow has already
+     * called `claimAttachment`; the bridge adapter reads these from env and
+     * renews (rather than fresh-claims) the lease on boot. See design §8.2.
+     */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface CopilotBridgeResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * Spawn a copilot bridge as a detached headless subprocess.
+ * Sets up log file, PID file, and all required env vars.
+ */
+export declare function spawnCopilotBridge(opts: CopilotBridgeOpts): CopilotBridgeResult;
+/**
+ * Options for {@link spawnMockAdapter}. Mirrors {@link CopilotBridgeOpts} for
+ * the cross-machine fields (host queue, attachment handoff) and adds the two
+ * mock-specific env knobs (`mockMode`, `mockScenario`).
+ *
+ * The mock adapter has no notion of a Claude session ID, no auth token, and
+ * no MCP server child — it talks to Temporal directly and posts every action
+ * through the outbox like any other adapter would. So the option surface is
+ * deliberately narrow.
+ */
+export interface MockAdapterOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log + PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /** Mock mode (defaults to `echo` when omitted). */
+    mockMode?: MockMode;
+    /** Scenario reference — bare name, absolute path, or relative path. Required for `scripted` mode. */
+    mockScenario?: string;
+    /**
+     * PR-D attachment-lease handoff. When present, the workflow has already
+     * called `claimAttachment`; the mock adapter reads these from env and
+     * renews (rather than fresh-claims) the lease on boot.
+     */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface MockAdapterResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * Spawn a mock adapter subprocess. Headless — no terminal window, no
+ * "trust this folder" prompt — which is the whole point of the mock for
+ * autonomous validation harnesses (ADR 0014 §4.7).
+ */
+export declare function spawnMockAdapter(opts: MockAdapterOpts): MockAdapterResult;
+/**
+ * Options for {@link spawnClaudeApiAdapter}. Mirrors {@link CopilotBridgeOpts}
+ * for the cross-machine fields (host queue, attachment handoff) and adds the
+ * `model` knob (resolved from recruit-arg → env → constants-pinned default
+ * upstream; the spawn helper just forwards whatever is set).
+ *
+ * The claude-api adapter is headless — no terminal, no Claude binary, no
+ * MCP-server child process. It runs an in-process MCP server paired with a
+ * client via `InMemoryTransport` and talks to Anthropic via the optional
+ * `@anthropic-ai/sdk`. So the option surface is narrow: identity, Temporal
+ * connection settings, attachment handoff, and the optional model id.
+ */
+export interface ClaudeApiAdapterOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log + PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /** Model id (e.g. `claude-opus-4-7`). Forwarded via `AGENT_TEMPO_API_MODEL`. */
+    model?: string;
+    /**
+     * PR-D attachment-lease handoff. When present, the workflow has already
+     * called `claimAttachment`; the adapter reads these from env and renews
+     * (rather than fresh-claims) the lease on boot.
+     */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface ClaudeApiAdapterResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * Spawn the claude-api adapter as a detached headless subprocess.
+ *
+ * Mirrors {@link spawnCopilotBridge} — no TTY, log + PID files in
+ * `logs/<name>.log` and `logs/<name>.pid`, env vars carry identity +
+ * Temporal connection settings + optional attachment-handoff. The adapter
+ * resolves the LLM model from `AGENT_TEMPO_API_MODEL` (set here when
+ * `opts.model` is provided) or falls back to the constants-pinned default
+ * (`claude-opus-4-7`) inside the adapter's `run()`. `ANTHROPIC_API_KEY`
+ * is inherited from the parent's env (recruit pre-flight checks it).
+ */
+export declare function spawnClaudeApiAdapter(opts: ClaudeApiAdapterOpts): ClaudeApiAdapterResult;
+/**
+ * Options for {@link spawnOpenCodeAdapter}. Mirrors {@link ClaudeApiAdapterOpts}
+ * with one shape difference: the model id carries a `provider/...` prefix
+ * (`anthropic/claude-opus-4-7`, `openai/gpt-4o`, …) and is forwarded via
+ * `AGENT_TEMPO_OPENCODE_MODEL` so it doesn't collide with claude-api's
+ * `AGENT_TEMPO_API_MODEL` namespace.
+ *
+ * The adapter manages its own `opencode serve` subprocess internally — the
+ * spawn helper here only launches the headless adapter Node process; the
+ * adapter then probes a free port and spawns opencode itself.
+ */
+export interface OpenCodeAdapterOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log + PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /** Model id (e.g. `anthropic/claude-opus-4-7`). Forwarded via `AGENT_TEMPO_OPENCODE_MODEL`. */
+    model?: string;
+    /**
+     * PR-D attachment-lease handoff. When present, the workflow has already
+     * called `claimAttachment`; the adapter reads these from env and renews
+     * (rather than fresh-claims) the lease on boot.
+     */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface OpenCodeAdapterResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * Spawn the opencode adapter as a detached headless subprocess.
+ *
+ * Pattern matches {@link spawnClaudeApiAdapter} — no TTY, log + PID files
+ * in `logs/<name>.log` and `logs/<name>.pid`, env vars carry identity +
+ * Temporal connection settings + optional attachment-handoff. Provider
+ * env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) are inherited
+ * from the parent's env unchanged — OpenCode reads whichever ones the
+ * `model`'s prefix maps to (recruit pre-flight does NOT validate any
+ * specific provider key since the model is opaque pass-through).
+ */
+export declare function spawnOpenCodeAdapter(opts: OpenCodeAdapterOpts): OpenCodeAdapterResult;
+/**
+ * Options for {@link spawnClaudeCodeHeadlessAdapter}. Mirrors
+ * {@link ClaudeApiAdapterOpts} for identity + Temporal connection +
+ * attachment handoff; adds `permissionMode` / `dangerouslySkipPermissions`
+ * for the per-turn `claude -p --permission-mode <mode>` flag.
+ *
+ * The adapter spawns the host's `claude` CLI as a per-turn subprocess; this
+ * spawn helper only launches the headless adapter Node process.
+ */
+export interface ClaudeCodeHeadlessAdapterOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log + PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /**
+     * `--permission-mode` flag value forwarded to per-turn `claude -p`. Default
+     * `'acceptEdits'` (set inside the adapter on construction). Mutually
+     * exclusive with `dangerouslySkipPermissions`.
+     */
+    permissionMode?: ClaudeCodeHeadlessPermissionMode;
+    /** Pass `--dangerously-skip-permissions` to per-turn `claude -p`. Mutually exclusive with `permissionMode`. */
+    dangerouslySkipPermissions?: boolean;
+    /**
+     * PR-D attachment-lease handoff. When present, the workflow has already
+     * called `claimAttachment`; the adapter reads these from env and renews
+     * (rather than fresh-claims) the lease on boot.
+     */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface ClaudeCodeHeadlessAdapterResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * Spawn the claude-code-headless adapter as a detached headless subprocess.
+ *
+ * Pattern matches {@link spawnClaudeApiAdapter} — no TTY, log + PID files
+ * in `logs/<name>.log` and `logs/<name>.pid`, env vars carry identity +
+ * Temporal connection settings + optional attachment-handoff.
+ *
+ * **Env hygiene** (design §3.6): the per-turn `claude -p` child needs to
+ * use the host's OAuth keychain — NOT a `ANTHROPIC_API_KEY` env var.
+ * The adapter strips `ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN`
+ * from its child env at spawn time (in `adapter.ts`'s `invokeSdk`); this
+ * spawn helper passes the parent's full env through to the adapter
+ * itself (which needs other env vars like PATH).
+ */
+export declare function spawnClaudeCodeHeadlessAdapter(opts: ClaudeCodeHeadlessAdapterOpts): ClaudeCodeHeadlessAdapterResult;