@getforgeai/cli 0.1.0-beta.1

package/dist/orchestrator/connectors/claude-code-connector.d.ts

@@ -0,0 +1,3 @@
+import type { AgentConnector } from "./connector.js";
+export declare const claudeCodeConnector: AgentConnector;
+//# sourceMappingURL=claude-code-connector.d.ts.map

package/dist/orchestrator/connectors/claude-code-connector.js

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+import { stopAgentProcess } from "./connector.js";
+function buildDefaultPrompt(skillName) {
+    return `You are a ForgeAI agent. Read and follow the ${skillName} skill in .claude/skills/${skillName}/SKILL.md to implement your assigned task.`;
+}
+function getCleanEnv() {
+    const env = { ...process.env };
+    // Remove Claude Code session markers so spawned agents don't refuse to start
+    // with "cannot be launched inside another Claude Code session"
+    delete env.CLAUDECODE;
+    delete env.CLAUDE_CODE_ENTRYPOINT;
+    return env;
+}
+function spawnClaude(params, prompt) {
+    const args = [
+        "--mcp-config",
+        params.mcpConfigPath,
+        "-p",
+        prompt,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--include-partial-messages",
+    ];
+    // === DISPATCH DEBUG: log exact spawn args ===
+    console.log(`\x1b[35m[claude-spawn-debug] cwd="${params.worktreePath}"\n  prompt="${prompt.slice(0, 200)}${prompt.length > 200 ? "..." : ""}"\n  args=${JSON.stringify(args.filter((a) => a !== prompt))}\x1b[0m`);
+    const child = spawn("claude", args, {
+        cwd: params.worktreePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: false,
+        env: getCleanEnv(),
+    });
+    if (child.pid === undefined) {
+        throw new Error("Failed to spawn claude process — no PID assigned");
+    }
+    return { pid: child.pid, process: child };
+}
+export const claudeCodeConnector = {
+    name: "claude-code",
+    async start(params) {
+        return spawnClaude(params, params.prompt ?? buildDefaultPrompt(params.skillName));
+    },
+    stop: stopAgentProcess,
+    async resume(params, ctx) {
+        const basePrompt = params.prompt ?? buildDefaultPrompt(params.skillName);
+        const parts = [basePrompt];
+        if (ctx?.agentQuestion || ctx?.response) {
+            parts.push("\n\n## Human Interaction Resume\n");
+            if (ctx.agentQuestion) {
+                parts.push(`**Your previous question:**\n${ctx.agentQuestion}\n`);
+            }
+            if (ctx.response) {
+                parts.push(`**Human response:**\n${ctx.response}\n`);
+            }
+            parts.push("Continue your work using the human's response above. Do not re-ask the same question.");
+        }
+        return spawnClaude(params, parts.join("\n"));
+    },
+};
+//# sourceMappingURL=claude-code-connector.js.map

package/dist/orchestrator/connectors/connector.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Abstract process interface for agent execution.
+ * ChildProcess satisfies this interface natively.
+ * VmProcessProxy also satisfies it via vsock.
+ */
+export type AgentProcess = NodeJS.EventEmitter & {
+    readonly stdout: NodeJS.ReadableStream | null;
+    readonly stderr: NodeJS.ReadableStream | null;
+    readonly pid: number;
+    readonly exitCode: number | null;
+    readonly killed: boolean;
+    /** True when exit was caused by an authentication error */
+    readonly isAuthError?: boolean;
+    kill(signal?: string): boolean;
+};
+/**
+ * Parameters required to spawn an agent.
+ */
+export type SpawnParams = {
+    taskId: string;
+    projectId: string;
+    orgId: string;
+    workingDir: string;
+    mcpConfigPath: string;
+    skillName: string;
+    /** Custom prompt override — used for workflow step agents */
+    prompt?: string;
+};
+/**
+ * Extended spawn params for VM connector — includes repo/branch/skill context
+ * that the VM connector needs to set up the environment internally.
+ */
+export type VmSpawnParams = SpawnParams & {
+    repoUrl?: string;
+    taskBranch?: string;
+    workflowBaseBranch?: string;
+    skill?: {
+        name: string;
+        files: Array<{
+            path: string;
+            content: string;
+        }>;
+    };
+    taskContext?: Record<string, unknown>;
+    workflowContext?: {
+        workflowId: string;
+        stepId: string;
+    };
+    /** Base64-encoded session snapshot for --continue resume after timeout */
+    sessionSnapshotBase64?: string;
+};
+/**
+ * Result of spawning an agent subprocess.
+ */
+export type SpawnResult = {
+    pid: number;
+    process: AgentProcess;
+    vmId?: string;
+};
+/**
+ * Tracks a running agent subprocess in the registry.
+ */
+export type AgentEntry = {
+    taskId: string;
+    pid: number;
+    process: AgentProcess;
+    connectorName: string;
+    workingDir: string;
+    orgId: string;
+    startedAt: string;
+    status: "RUNNING" | "COMPLETED" | "ERROR" | "IDLE";
+    vmId?: string;
+};
+/**
+ * Uniform interface for spawning and stopping AI agent subprocesses.
+ * Connectors are stateless — they only know how to spawn/stop a specific agent type.
+ */
+export type ResumeContext = {
+    response?: string;
+    agentQuestion?: string;
+};
+export type AgentConnector = {
+    readonly name: string;
+    start(params: SpawnParams | VmSpawnParams): Promise<SpawnResult>;
+    stop(entry: AgentEntry): Promise<void>;
+    resume(params: SpawnParams | VmSpawnParams, ctx?: ResumeContext): Promise<SpawnResult>;
+    /** Resume a workflow step from a session snapshot (--continue in new container) */
+    resumeWithSnapshot?(params: VmSpawnParams): Promise<SpawnResult>;
+};
+/**
+ * Shared stop logic: SIGTERM → wait up to 10s → SIGKILL if still alive.
+ * Used by all connectors to avoid duplicating the stop sequence.
+ */
+export declare function stopAgentProcess(entry: AgentEntry): Promise<void>;
+//# sourceMappingURL=connector.d.ts.map

package/dist/orchestrator/connectors/connector.js

@@ -0,0 +1,25 @@
+const STOP_TIMEOUT_MS = 10_000;
+/**
+ * Shared stop logic: SIGTERM → wait up to 10s → SIGKILL if still alive.
+ * Used by all connectors to avoid duplicating the stop sequence.
+ */
+export async function stopAgentProcess(entry) {
+    const { process: proc } = entry;
+    if (proc.exitCode !== null || proc.killed) {
+        return;
+    }
+    proc.kill("SIGTERM");
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (proc.exitCode === null && !proc.killed) {
+                proc.kill("SIGKILL");
+            }
+            resolve();
+        }, STOP_TIMEOUT_MS);
+        proc.once("exit", () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=connector.js.map

package/dist/orchestrator/connectors/docker-connector.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AgentConnector implementation that runs agents inside Docker containers.
+ *
+ * Each agent session gets its own container with a full git clone.
+ * Communication uses native Docker exec stdio streams.
+ * MCP bridge via TCP to host (forge-mcp-relay inside container).
+ *
+ * Container lifecycle is workflow-aware:
+ * - Board tasks: container destroyed immediately on agent exit
+ * - Workflow steps: container kept alive during idle window for --continue resume
+ */
+import type { AgentConnector } from "./connector.js";
+export declare const dockerConnector: AgentConnector;
+//# sourceMappingURL=docker-connector.d.ts.map

package/dist/orchestrator/connectors/docker-connector.js

@@ -0,0 +1,337 @@
+/**
+ * AgentConnector implementation that runs agents inside Docker containers.
+ *
+ * Each agent session gets its own container with a full git clone.
+ * Communication uses native Docker exec stdio streams.
+ * MCP bridge via TCP to host (forge-mcp-relay inside container).
+ *
+ * Container lifecycle is workflow-aware:
+ * - Board tasks: container destroyed immediately on agent exit
+ * - Workflow steps: container kept alive during idle window for --continue resume
+ */
+import { stopAgentProcess } from "./connector.js";
+import { getVmManager } from "../../vm/vm-manager-facade.js";
+import { startMcpBridge, stopMcpBridge } from "../../vm/mcp-bridge.js";
+import { getDockerBridgeGatewayIp } from "../../vm/docker-executor.js";
+import { activeConnections } from "../../lib/connection-manager.js";
+import { vmLog } from "../../vm/log.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the host address the in-container relay connects to.
+ * Must match the interface the MCP bridge binds to (see mcp-bridge.ts):
+ * the Docker bridge gateway on Linux, host.docker.internal elsewhere
+ * (Docker Desktop forwards it to the host loopback).
+ */
+async function resolveMcpRelayHost() {
+    if (process.platform === "linux") {
+        return getDockerBridgeGatewayIp();
+    }
+    return "host.docker.internal";
+}
+/**
+ * Build MCP config JSON for the Docker container.
+ * The relay connects to the host MCP server via host.docker.internal.
+ * Runs the relay staged in the session dir (always matches this CLI build)
+ * and authenticates to the bridge with the per-session secret.
+ */
+function buildMcpConfigJson(sessionIndex, mcpSecret, mcpHost) {
+    const mcpPort = 20000 + sessionIndex;
+    return JSON.stringify({
+        mcpServers: {
+            forgeai: {
+                command: "node",
+                args: ["/session/forge-mcp-relay.mjs"],
+                env: {
+                    FORGEAI_MCP_HOST: mcpHost,
+                    FORGEAI_MCP_PORT: String(mcpPort),
+                    FORGEAI_MCP_TOKEN: mcpSecret,
+                },
+            },
+        },
+    }, null, 2);
+}
+function buildDefaultPrompt(skillName) {
+    return `You are a ForgeAI agent. Read and follow the ${skillName} skill in .claude/skills/${skillName}/SKILL.md to implement your assigned task.`;
+}
+function buildResumePrompt(basePrompt, ctx) {
+    const parts = [basePrompt];
+    if (ctx?.agentQuestion ?? ctx?.response) {
+        parts.push("\n\n## Human Interaction Resume\n");
+        if (ctx?.agentQuestion) {
+            parts.push(`**Your previous question:**\n${ctx.agentQuestion}\n`);
+        }
+        if (ctx?.response) {
+            parts.push(`**Human response:**\n${ctx.response}\n`);
+        }
+        parts.push("Continue your work using the human's response above. Do not re-ask the same question.");
+    }
+    return parts.join("\n");
+}
+/** Standard Claude CLI args for agent execution */
+function buildAgentArgs(mcpConfigPath, prompt) {
+    return [
+        "--dangerously-skip-permissions",
+        "--mcp-config",
+        mcpConfigPath,
+        "-p",
+        prompt,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--include-partial-messages",
+    ];
+}
+/** Claude CLI args for --continue resume (requires -p for print/stream mode) */
+function buildContinueArgs(mcpConfigPath, prompt) {
+    return [
+        "--continue",
+        "--dangerously-skip-permissions",
+        "--mcp-config",
+        mcpConfigPath,
+        "-p",
+        prompt,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--include-partial-messages",
+    ];
+}
+/**
+ * Start the MCP bridge for a session.
+ * Returns the MCP port used, or null if no active connection available.
+ */
+async function startSessionMcpBridge(session, params) {
+    const mcpPort = 20000 + session.sessionIndex;
+    const orgConn = activeConnections.get(params.orgId);
+    if (orgConn) {
+        await startMcpBridge(session.id, mcpPort, {
+            taskId: params.taskId,
+            projectId: params.projectId,
+            orgId: params.orgId,
+            restClient: orgConn.restClient,
+            socketClient: orgConn.socketClient,
+            currentTask: null,
+            projectRoot: null,
+            workflowId: params.workflowContext?.workflowId,
+            stepId: params.workflowContext?.stepId,
+        }, session.mcpSecret);
+        return mcpPort;
+    }
+    vmLog.warn("docker-connector", `No active connection for org ${params.orgId} — MCP tools unavailable`, session.id);
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Connector
+// ---------------------------------------------------------------------------
+export const dockerConnector = {
+    name: "docker-claude-code",
+    async start(params) {
+        const sm = getVmManager();
+        // 1. Ensure Docker is ready + image available
+        await sm.ensureVmRunning();
+        // 2. Create session (container + host dirs)
+        const sessionId = await sm.createSession(params.taskId);
+        const session = sm.getSessionByTaskId(params.taskId);
+        // 3. Clone repo inside the container
+        await sm.cloneRepo(sessionId, params.repoUrl, params.taskBranch, params.workflowBaseBranch);
+        // 4. Prepare workspace files on the host (volume-mounted at /session)
+        const skillFiles = [];
+        if (params.skill) {
+            for (const file of params.skill.files) {
+                skillFiles.push({
+                    relativePath: `${params.skill.name}/${file.path}`,
+                    content: file.content,
+                });
+            }
+        }
+        sm.prepareWorkspace(sessionId, {
+            contextJson: JSON.stringify(params.taskContext ?? {}, null, 2),
+            mcpConfigJson: buildMcpConfigJson(session.sessionIndex, session.mcpSecret, await resolveMcpRelayHost()),
+            skillFiles,
+        });
+        // 5. Copy workspace files from volume mount into /workspace inside container
+        await sm.exec(params.taskId, "bash", [
+            "-c",
+            [
+                "mkdir -p /session/workspace/.forgeai /session/workspace/.claude",
+                "cp /session/context.json /session/workspace/.forgeai/context.json",
+                "cp /session/mcp_config.json /session/workspace/.claude/mcp_config.json",
+            ].join(" && "),
+        ]);
+        if (skillFiles.length > 0) {
+            await sm.exec(params.taskId, "bash", [
+                "-c",
+                [
+                    "mkdir -p /session/workspace/.claude/skills",
+                    "cp -r /session/skills/. /session/workspace/.claude/skills/",
+                ].join(" && "),
+            ]);
+        }
+        // 6. Start MCP bridge (TCP server on host for forge-mcp-relay in container)
+        await startSessionMcpBridge(session, params);
+        // 7. Spawn agent
+        const prompt = params.prompt ?? buildDefaultPrompt(params.skillName);
+        const agentArgs = buildAgentArgs("/session/workspace/.claude/mcp_config.json", prompt);
+        const env = {};
+        vmLog.magenta("docker-connector", `Spawning agent in container ${sessionId}`, sessionId);
+        const proxy = await sm.spawnAgent(params.taskId, "claude", agentArgs, env);
+        // 8. Container lifecycle on agent exit — depends on workflow context
+        if (!params.workflowContext) {
+            // Board task: destroy container + MCP bridge immediately on exit
+            proxy.once("exit", () => {
+                stopMcpBridge(sessionId).catch(() => { });
+                sm.destroySession(params.taskId).catch((err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    vmLog.warn("docker-connector", `Cleanup failed for ${sessionId}: ${message}`, sessionId);
+                });
+            });
+        }
+        else {
+            // Workflow step: keep container alive for idle window.
+            // Only stop MCP bridge — container stays for --continue resume.
+            // Destruction is handled by idle timeout / dismiss / error in agent-spawner.
+            proxy.once("exit", () => {
+                stopMcpBridge(sessionId).catch(() => { });
+                vmLog.dim("docker-connector", `Workflow agent exited — container ${sessionId} kept alive for idle window`, sessionId);
+            });
+        }
+        return {
+            pid: proxy.pid,
+            process: proxy,
+            vmId: sessionId,
+        };
+    },
+    async stop(entry) {
+        await stopAgentProcess(entry);
+        if (entry.vmId) {
+            const sm = getVmManager();
+            await sm.destroySession(entry.taskId);
+        }
+    },
+    async resume(params, ctx) {
+        const sm = getVmManager();
+        const session = sm.getSessionByTaskId(params.taskId);
+        if (session && session.status === "RUNNING") {
+            vmLog.cyan("docker-connector", `Resuming in existing container ${session.id}`, session.id);
+            // Restart MCP bridge (stopped on previous agent exit)
+            await startSessionMcpBridge(session, params);
+            // Use --continue for workflow resume in existing container (full context)
+            if (params.workflowContext) {
+                const continuePrompt = params.prompt ??
+                    "Continue your work from where you left off. Do not repeat completed work.";
+                const agentArgs = buildContinueArgs("/session/workspace/.claude/mcp_config.json", continuePrompt);
+                const proxy = await sm.spawnAgent(params.taskId, "claude", agentArgs);
+                // Keep container alive for next idle window cycle
+                proxy.once("exit", () => {
+                    stopMcpBridge(session.id).catch(() => { });
+                    vmLog.dim("docker-connector", `Resumed workflow agent exited — container ${session.id} kept alive`, session.id);
+                });
+                return {
+                    pid: proxy.pid,
+                    process: proxy,
+                    vmId: session.id,
+                };
+            }
+            // Board task resume: use --continue with user's answer (container alive from ask-human)
+            const resumePrompt = ctx?.response ?? "Continue your work.";
+            await startSessionMcpBridge(session, params);
+            const agentArgs = buildContinueArgs("/session/workspace/.claude/mcp_config.json", resumePrompt);
+            const proxy = await sm.spawnAgent(params.taskId, "claude", agentArgs);
+            return {
+                pid: proxy.pid,
+                process: proxy,
+                vmId: session.id,
+            };
+        }
+        // No existing session — check for snapshot restore
+        if (params.sessionSnapshotBase64 && this.resumeWithSnapshot) {
+            return this.resumeWithSnapshot(params);
+        }
+        // Fallback: full fresh start with context in prompt
+        const basePrompt = params.prompt ?? buildDefaultPrompt(params.skillName);
+        return this.start({
+            ...params,
+            prompt: buildResumePrompt(basePrompt, ctx),
+        });
+    },
+    /**
+     * Resume a workflow step using a restored session snapshot.
+     * The snapshot has already been restored into the container by the caller.
+     * Uses `claude --continue` for full context restoration.
+     */
+    async resumeWithSnapshot(params) {
+        const sm = getVmManager();
+        // 1. Ensure Docker is ready + image available
+        await sm.ensureVmRunning();
+        // 2. Create session (container + host dirs)
+        const sessionId = await sm.createSession(params.taskId);
+        const session = sm.getSessionByTaskId(params.taskId);
+        // 3. Clone repo (picks up auto-saved code from git push)
+        await sm.cloneRepo(sessionId, params.repoUrl, params.taskBranch, params.workflowBaseBranch);
+        // 4. Prepare workspace files
+        const skillFiles = [];
+        if (params.skill) {
+            for (const file of params.skill.files) {
+                skillFiles.push({
+                    relativePath: `${params.skill.name}/${file.path}`,
+                    content: file.content,
+                });
+            }
+        }
+        sm.prepareWorkspace(sessionId, {
+            contextJson: JSON.stringify(params.taskContext ?? {}, null, 2),
+            mcpConfigJson: buildMcpConfigJson(session.sessionIndex, session.mcpSecret, await resolveMcpRelayHost()),
+            skillFiles,
+        });
+        await sm.exec(params.taskId, "bash", [
+            "-c",
+            [
+                "mkdir -p /session/workspace/.forgeai /session/workspace/.claude",
+                "cp /session/context.json /session/workspace/.forgeai/context.json",
+                "cp /session/mcp_config.json /session/workspace/.claude/mcp_config.json",
+            ].join(" && "),
+        ]);
+        if (skillFiles.length > 0) {
+            await sm.exec(params.taskId, "bash", [
+                "-c",
+                [
+                    "mkdir -p /session/workspace/.claude/skills",
+                    "cp -r /session/skills/. /session/workspace/.claude/skills/",
+                ].join(" && "),
+            ]);
+        }
+        // 5. Restore the session snapshot (already written to sessionDir by caller)
+        const { restoreSessionSnapshot } = await import("../../vm/session-snapshot.js");
+        const snapshotRestored = await restoreSessionSnapshot(session, params.sessionSnapshotBase64);
+        // 6. Start MCP bridge
+        await startSessionMcpBridge(session, params);
+        // 7. Spawn with --continue if snapshot restored, otherwise -p prompt
+        let proxy;
+        if (snapshotRestored) {
+            vmLog.cyan("docker-connector", `Spawning with --continue (snapshot restored) in ${sessionId}`, sessionId);
+            const continuePrompt = params.prompt ??
+                "Continue your work from where you left off. Do not repeat completed work.";
+            const agentArgs = buildContinueArgs("/session/workspace/.claude/mcp_config.json", continuePrompt);
+            proxy = await sm.spawnAgent(params.taskId, "claude", agentArgs);
+        }
+        else {
+            vmLog.warn("docker-connector", `Snapshot restore failed — falling back to prompt in ${sessionId}`, sessionId);
+            const prompt = params.prompt ?? buildDefaultPrompt(params.skillName);
+            const agentArgs = buildAgentArgs("/session/workspace/.claude/mcp_config.json", prompt);
+            proxy = await sm.spawnAgent(params.taskId, "claude", agentArgs);
+        }
+        // Workflow: keep container alive for idle window
+        proxy.once("exit", () => {
+            stopMcpBridge(sessionId).catch(() => { });
+            vmLog.dim("docker-connector", `Snapshot-resumed workflow agent exited — container ${sessionId} kept alive`, sessionId);
+        });
+        return {
+            pid: proxy.pid,
+            process: proxy,
+            vmId: sessionId,
+        };
+    },
+};
+//# sourceMappingURL=docker-connector.js.map

package/dist/orchestrator/connectors/native-vm-connector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AgentConnector implementation that runs agents inside bubblewrap sandboxes
+ * within the shared native VM (Virtualization.framework via Swift N-API addon).
+ *
+ * Replaces the old vm-connector that used one VM per session with SSH streaming.
+ * This connector uses vsock for all communication and shares a single VM across
+ * all concurrent agent sessions.
+ */
+import type { AgentConnector } from "./connector.js";
+export declare const nativeVmConnector: AgentConnector;
+//# sourceMappingURL=native-vm-connector.d.ts.map