@getforgeai/cli 0.1.0-beta.1

package/dist/mcp/mcp-response.d.ts

@@ -0,0 +1,29 @@
+import type { McpSessionContext } from "./types.js";
+type McpToolResult = {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Wrap any data in a standard MCP success response. */
+export declare function mcpSuccess(data: unknown): McpToolResult;
+/** Wrap any data in a standard MCP error response. */
+export declare function mcpError(data: unknown): McpToolResult;
+/** Return a "socket not connected" error for a given action. */
+export declare function mcpNotConnectedError(action: string): McpToolResult;
+/** Return a network error from an unknown caught error. */
+export declare function mcpNetworkError(error: unknown, retryHint?: string): McpToolResult;
+/** Return a "task not found" error. */
+export declare function mcpTaskNotFoundError(taskId: string): McpToolResult;
+/**
+ * Execute a socket emit call with standard connection check and error handling.
+ * Covers the most common MCP tool pattern: check connection → emit → return response.
+ */
+export declare function executeSocketEmit(context: McpSessionContext, action: string, emitFn: () => Promise<unknown>): Promise<McpToolResult>;
+/**
+ * Handle a REST client error, returning task-not-found for 404 or network error otherwise.
+ */
+export declare function handleRestError(error: unknown, taskId: string): McpToolResult;
+export {};
+//# sourceMappingURL=mcp-response.d.ts.map

package/dist/mcp/mcp-response.js

@@ -0,0 +1,67 @@
+import { MCP_ERROR_CODE } from "./types.js";
+import { RestClientError } from "../lib/rest-client.js";
+/** Wrap any data in a standard MCP success response. */
+export function mcpSuccess(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+    };
+}
+/** Wrap any data in a standard MCP error response. */
+export function mcpError(data) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(data) }],
+    };
+}
+/** Return a "socket not connected" error for a given action. */
+export function mcpNotConnectedError(action) {
+    return mcpError({
+        error: MCP_ERROR_CODE.NETWORK_ERROR,
+        message: `Socket not connected. Cannot ${action}.`,
+        retryHint: "Cloud may be temporarily unavailable. Retry in a few seconds.",
+    });
+}
+/** Return a network error from an unknown caught error. */
+export function mcpNetworkError(error, retryHint = "Cloud may be temporarily unavailable. Retry in a few seconds.") {
+    return mcpError({
+        error: MCP_ERROR_CODE.NETWORK_ERROR,
+        message: error instanceof Error ? error.message : String(error),
+        retryHint,
+    });
+}
+/** Return a "task not found" error. */
+export function mcpTaskNotFoundError(taskId) {
+    return mcpError({
+        error: MCP_ERROR_CODE.TASK_NOT_FOUND,
+        message: `Task "${taskId}" not found`,
+    });
+}
+/**
+ * Execute a socket emit call with standard connection check and error handling.
+ * Covers the most common MCP tool pattern: check connection → emit → return response.
+ */
+export async function executeSocketEmit(context, action, emitFn) {
+    if (!context.socketClient.socket.connected) {
+        return mcpNotConnectedError(action);
+    }
+    try {
+        const response = (await emitFn());
+        if (response.error) {
+            return mcpError(response);
+        }
+        return mcpSuccess(response);
+    }
+    catch (error) {
+        return mcpNetworkError(error);
+    }
+}
+/**
+ * Handle a REST client error, returning task-not-found for 404 or network error otherwise.
+ */
+export function handleRestError(error, taskId) {
+    if (error instanceof RestClientError && error.status === 404) {
+        return mcpTaskNotFoundError(taskId);
+    }
+    return mcpNetworkError(error);
+}
+//# sourceMappingURL=mcp-response.js.map

package/dist/mcp/mcp-server.d.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { McpSessionContext } from "./types.js";
+/**
+ * Create and configure an MCP server instance for a single agent session.
+ * Registers all ForgeAI tools and resources.
+ */
+export declare function createMcpServer(context: McpSessionContext): McpServer;
+/**
+ * Create a stdio transport for the MCP server.
+ * Uses provided streams or defaults to process.stdin/stdout.
+ */
+export declare function createStdioTransport(stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream): StdioServerTransport;
+/**
+ * Start an MCP server with stdio transport.
+ * Convenience function for daemon integration.
+ */
+export declare function startMcpServer(context: McpSessionContext, stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream): Promise<McpServer>;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp/mcp-server.js

@@ -0,0 +1,76 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerForgeGetTask } from "./tools/forge-get-task.js";
+import { registerForgeUpdateStatus } from "./tools/forge-update-status.js";
+import { registerForgeAskHuman } from "./tools/forge-ask-human.js";
+import { registerForgeRequeue } from "./tools/forge-requeue.js";
+import { registerForgeColumnDone } from "./tools/forge-column-done.js";
+import { registerForgeCompleteStep } from "./tools/forge-complete-step.js";
+import { registerForgeCreateTaskGroup } from "./tools/forge-create-task-group.js";
+import { registerForgeAddGroupDependency } from "./tools/forge-add-group-dependency.js";
+import { registerForgeCreateTask } from "./tools/forge-create-task.js";
+import { registerForgeAddTaskDependency } from "./tools/forge-add-task-dependency.js";
+import { registerForgeUpdateTask } from "./tools/forge-update-task.js";
+import { registerForgeDeleteTask } from "./tools/forge-delete-task.js";
+import { registerForgeUpdateTaskGroup } from "./tools/forge-update-task-group.js";
+import { registerForgeDeleteTaskGroup } from "./tools/forge-delete-task-group.js";
+import { registerForgeRemoveTaskDependency } from "./tools/forge-remove-task-dependency.js";
+import { registerForgeRemoveGroupDependency } from "./tools/forge-remove-group-dependency.js";
+import { registerForgeMergeBack } from "./tools/forge-merge-back.js";
+import { registerForgeValidateMerge } from "./tools/forge-validate-merge.js";
+import { registerForgeReleaseMerge } from "./tools/forge-release-merge.js";
+import { registerForgeReleaseTag } from "./tools/forge-release-tag.js";
+import { registerForgeReleaseNotes } from "./tools/forge-release-notes.js";
+import { registerTaskCurrentResource } from "./resources/task-current.js";
+import { registerProjectConventionsResource } from "./resources/project-conventions.js";
+/**
+ * Create and configure an MCP server instance for a single agent session.
+ * Registers all ForgeAI tools and resources.
+ */
+export function createMcpServer(context) {
+    const server = new McpServer({ name: "forgeai", version: "1.0.0" }, { capabilities: { tools: {}, resources: {} } });
+    // Register tools
+    registerForgeGetTask(server, context);
+    registerForgeUpdateStatus(server, context);
+    registerForgeAskHuman(server, context);
+    registerForgeRequeue(server, context);
+    registerForgeColumnDone(server, context);
+    registerForgeCompleteStep(server, context);
+    registerForgeCreateTaskGroup(server, context);
+    registerForgeAddGroupDependency(server, context);
+    registerForgeCreateTask(server, context);
+    registerForgeAddTaskDependency(server, context);
+    registerForgeUpdateTask(server, context);
+    registerForgeDeleteTask(server, context);
+    registerForgeUpdateTaskGroup(server, context);
+    registerForgeDeleteTaskGroup(server, context);
+    registerForgeRemoveTaskDependency(server, context);
+    registerForgeRemoveGroupDependency(server, context);
+    registerForgeMergeBack(server, context);
+    registerForgeValidateMerge(server, context);
+    registerForgeReleaseMerge(server, context);
+    registerForgeReleaseTag(server, context);
+    registerForgeReleaseNotes(server, context);
+    // Register resources
+    registerTaskCurrentResource(server, context);
+    registerProjectConventionsResource(server, context);
+    return server;
+}
+/**
+ * Create a stdio transport for the MCP server.
+ * Uses provided streams or defaults to process.stdin/stdout.
+ */
+export function createStdioTransport(stdin, stdout) {
+    return new StdioServerTransport(stdin, stdout);
+}
+/**
+ * Start an MCP server with stdio transport.
+ * Convenience function for daemon integration.
+ */
+export async function startMcpServer(context, stdin, stdout) {
+    const server = createMcpServer(context);
+    const transport = createStdioTransport(stdin, stdout);
+    await server.connect(transport);
+    return server;
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp/resources/project-conventions.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerProjectConventionsResource(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=project-conventions.d.ts.map

package/dist/mcp/resources/project-conventions.js

@@ -0,0 +1,50 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export function registerProjectConventionsResource(server, context) {
+    server.registerResource("Project Conventions", "forge://project/conventions", { mimeType: "text/plain" }, async (uri) => {
+        if (!context.projectRoot) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "text/plain",
+                        text: "No project root configured. Cannot read conventions.",
+                    },
+                ],
+            };
+        }
+        const sections = [];
+        // Read CLAUDE.md
+        try {
+            const claudeMd = await readFile(join(context.projectRoot, "CLAUDE.md"), "utf-8");
+            sections.push("# CLAUDE.md\n\n" + claudeMd);
+        }
+        catch {
+            sections.push("# CLAUDE.md\n\nNo CLAUDE.md found in project root.");
+        }
+        // Read architecture docs if they exist
+        const archPaths = [
+            "docs/architecture.md",
+            "_bmad-output/planning-artifacts/architecture.md",
+        ];
+        for (const archPath of archPaths) {
+            try {
+                const content = await readFile(join(context.projectRoot, archPath), "utf-8");
+                sections.push(`\n\n# ${archPath}\n\n${content}`);
+            }
+            catch {
+                // File doesn't exist, skip
+            }
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "text/plain",
+                    text: sections.join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=project-conventions.js.map

package/dist/mcp/resources/task-current.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerTaskCurrentResource(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=task-current.d.ts.map

package/dist/mcp/resources/task-current.js

@@ -0,0 +1,51 @@
+export function registerTaskCurrentResource(server, context) {
+    let fetchPromise = null;
+    server.registerResource("Current Task", "forge://task/current", { mimeType: "application/json" }, async (uri) => {
+        if (!context.currentTask) {
+            // Deduplicate concurrent fetches — only one REST call at a time
+            fetchPromise ??= context.restClient
+                .getTask(context.taskId)
+                .then((task) => {
+                context.currentTask = {
+                    id: task.id,
+                    title: task.title,
+                    description: task.description ?? "",
+                    status: task.kanbanSubStatus ?? "UNKNOWN",
+                    kanbanColumn: task.kanbanColumn,
+                    assigneeId: task.assigneeId,
+                    cliDeviceId: task.cliDeviceId,
+                };
+            })
+                .catch((error) => {
+                console.warn(`[MCP] Failed to fetch current task ${context.taskId}:`, error);
+            })
+                .finally(() => {
+                fetchPromise = null;
+            });
+            await fetchPromise;
+        }
+        if (!context.currentTask) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify({
+                            error: "Failed to fetch current task",
+                        }),
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(context.currentTask),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=task-current.js.map

package/dist/mcp/tools/forge-add-group-dependency.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerForgeAddGroupDependency(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=forge-add-group-dependency.d.ts.map

package/dist/mcp/tools/forge-add-group-dependency.js

@@ -0,0 +1,20 @@
+import { ForgeAddGroupDependencyInputSchema } from "@getforgeai/protocol";
+import { executeSocketEmit } from "../mcp-response.js";
+const shape = ForgeAddGroupDependencyInputSchema.shape;
+export function registerForgeAddGroupDependency(server, context) {
+    server.registerTool("forge_add_group_dependency", {
+        description: "Add a dependency between two task groups. The blocked group cannot start until the blocking group is done. References groups by name within the current project.",
+        inputSchema: {
+            blockingGroupName: shape.blockingGroupName.describe("Name of the group that must complete first"),
+            blockedGroupName: shape.blockedGroupName.describe("Name of the group that is blocked"),
+        },
+    }, async (params) => {
+        return executeSocketEmit(context, "add group dependency", () => context.socketClient.emitTaskGroupAddDependency({
+            projectId: context.projectId,
+            workflowId: context.workflowId,
+            blockingGroupName: params.blockingGroupName,
+            blockedGroupName: params.blockedGroupName,
+        }));
+    });
+}
+//# sourceMappingURL=forge-add-group-dependency.js.map

package/dist/mcp/tools/forge-add-task-dependency.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerForgeAddTaskDependency(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=forge-add-task-dependency.d.ts.map

package/dist/mcp/tools/forge-add-task-dependency.js

@@ -0,0 +1,20 @@
+import { ForgeAddTaskDependencyInputSchema } from "@getforgeai/protocol";
+import { executeSocketEmit } from "../mcp-response.js";
+const shape = ForgeAddTaskDependencyInputSchema.shape;
+export function registerForgeAddTaskDependency(server, context) {
+    server.registerTool("forge_add_task_dependency", {
+        description: "Add a dependency between two tasks. The blocked task cannot start until the blocking task is done. References tasks by title within the current project (most recently created match).",
+        inputSchema: {
+            blockingTaskTitle: shape.blockingTaskTitle.describe("Title of the task that must complete first"),
+            blockedTaskTitle: shape.blockedTaskTitle.describe("Title of the task that is blocked"),
+        },
+    }, async (params) => {
+        return executeSocketEmit(context, "add task dependency", () => context.socketClient.emitTaskAddDependency({
+            projectId: context.projectId,
+            workflowId: context.workflowId,
+            blockingTaskTitle: params.blockingTaskTitle,
+            blockedTaskTitle: params.blockedTaskTitle,
+        }));
+    });
+}
+//# sourceMappingURL=forge-add-task-dependency.js.map

package/dist/mcp/tools/forge-ask-human.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerForgeAskHuman(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=forge-ask-human.d.ts.map

package/dist/mcp/tools/forge-ask-human.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { mcpSuccess, mcpError, mcpNetworkError, handleRestError, } from "../mcp-response.js";
+export function registerForgeAskHuman(server, context) {
+    server.registerTool("forge_ask_human", {
+        description: "Ask a human a question. Creates a blocking question on the task, sets kanbanSubStatus to AWAITING_HUMAN, and returns a waiting signal. The agent should checkpoint and stop after calling this.",
+        inputSchema: {
+            taskId: z.string().min(1).describe("Task ID to attach the question to"),
+            question: z.string().min(1).describe("Question text for the human"),
+            context: z
+                .string()
+                .optional()
+                .describe("Optional context to help the human answer"),
+        },
+    }, async ({ taskId, question, context: questionContext }) => {
+        // Check current task status
+        let currentTask;
+        try {
+            currentTask = await context.restClient.getTask(taskId);
+        }
+        catch (error) {
+            return handleRestError(error, taskId);
+        }
+        // Validate kanbanSubStatus allows transition to AWAITING_HUMAN
+        // Only ACTIVE tasks can ask a human (per state machine)
+        if (currentTask.kanbanSubStatus === "AWAITING_HUMAN") {
+            return mcpError({
+                error: "INVALID_STATUS",
+                message: "Task is already in AWAITING_HUMAN state. Wait for the human to respond before asking another question.",
+            });
+        }
+        if (currentTask.kanbanSubStatus !== "ACTIVE") {
+            return mcpError({
+                error: "INVALID_STATUS",
+                message: `Cannot ask human from kanbanSubStatus "${currentTask.kanbanSubStatus}". Task must be ACTIVE.`,
+            });
+        }
+        // 1. Persist AWAITING_HUMAN + question to DB via REST FIRST.
+        //    This MUST complete before returning so that the DB has the correct
+        //    status before the agent exits and the fallback release checks it.
+        //    The REST route also broadcasts socket events for real-time UI.
+        try {
+            await context.restClient.updateTaskSubStatus({
+                taskId,
+                kanbanSubStatus: "AWAITING_HUMAN",
+                agentQuestion: question,
+            });
+        }
+        catch (error) {
+            return mcpNetworkError(error, "Failed to persist AWAITING_HUMAN status. Retry in a few seconds.");
+        }
+        // Mark task for container preservation (--continue on resume)
+        const { markAskHuman } = await import("../../orchestrator/agent-spawner.js");
+        markAskHuman(taskId);
+        // 2. Emit socket events for real-time UI updates (fire-and-forget)
+        try {
+            if (context.socketClient.socket.connected) {
+                context.socketClient.emitTaskAskHuman({
+                    taskId,
+                    question,
+                    context: questionContext,
+                    projectId: context.projectId,
+                });
+                context.socketClient.emitTaskUpdate({
+                    taskId,
+                    kanbanSubStatus: "AWAITING_HUMAN",
+                    projectId: context.projectId,
+                });
+            }
+        }
+        catch {
+            // Socket.io broadcast failed — DB is already updated, UI will catch up
+        }
+        return mcpSuccess({
+            taskId,
+            status: "waiting",
+            message: "Question submitted. Task kanbanSubStatus changed to AWAITING_HUMAN. Checkpoint your work and stop — you will be resumed when the human responds.",
+        });
+    });
+}
+//# sourceMappingURL=forge-ask-human.js.map

package/dist/mcp/tools/forge-column-done.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerForgeColumnDone(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=forge-column-done.d.ts.map

package/dist/mcp/tools/forge-column-done.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { ensureChangesCommittedAndPushed } from "../../lib/branch-manager.js";
+import { mcpSuccess, mcpError, handleRestError } from "../mcp-response.js";
+export function registerForgeColumnDone(server, context) {
+    server.registerTool("forge_column_done", {
+        description: "Signal that you have completed your work for the current column. " +
+            "The task advances to the next column in the pipeline and will be " +
+            "re-dispatched to an available agent. If the task is in the final " +
+            "column, it is marked as done without advancing.",
+        inputSchema: {
+            taskId: z.string().min(1).describe("Task ID to advance"),
+        },
+    }, async ({ taskId }) => {
+        try {
+            // Auto-commit/push guard: ensure all changes are saved before advancing.
+            // Only runs when projectRoot is set (local worktree mode).
+            // In VM mode (projectRoot is null), the agent manages its own git commits.
+            let guardStatus = "";
+            if (context.projectRoot) {
+                const guardResult = await ensureChangesCommittedAndPushed(context.projectRoot, "chore: auto-commit before column advance");
+                if (guardResult.error) {
+                    return mcpError({
+                        error: "GUARD_FAILED",
+                        message: `Cannot advance column: failed to commit/push changes. ${guardResult.error}`,
+                        retryHint: "Fix the git issue (commit and push your changes manually) then retry forge_column_done.",
+                    });
+                }
+                guardStatus = [
+                    guardResult.committed ? "Changes were auto-committed." : "",
+                    guardResult.pushed ? "Changes were auto-pushed." : "",
+                ]
+                    .filter(Boolean)
+                    .join(" ");
+            }
+            const result = await context.restClient.advanceTask(taskId);
+            return mcpSuccess({
+                ...result,
+                ...(guardStatus ? { guardStatus } : {}),
+            });
+        }
+        catch (error) {
+            return handleRestError(error, taskId);
+        }
+    });
+}
+//# sourceMappingURL=forge-column-done.js.map

package/dist/mcp/tools/forge-complete-step.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerForgeCompleteStep(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=forge-complete-step.d.ts.map

package/dist/mcp/tools/forge-complete-step.js

@@ -0,0 +1,139 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { ForgeCompleteStepDeliverableSchema } from "@getforgeai/protocol";
+import { MCP_ERROR_CODE } from "../types.js";
+import { ensureChangesCommittedAndPushed } from "../../lib/branch-manager.js";
+const MAX_FILE_CONTENT_BYTES = 100 * 1024; // 100 KB
+export function registerForgeCompleteStep(server, context) {
+    server.registerTool("forge_complete_step", {
+        description: "Signal that you have completed the current workflow step and provide the list of deliverables (files produced). Each deliverable has a filePath (relative to repo root) and a label (human-readable description). The user will review the deliverables before advancing to the next step.",
+        inputSchema: {
+            deliverables: z
+                .array(ForgeCompleteStepDeliverableSchema)
+                .min(1)
+                .describe("List of deliverables produced for this step"),
+        },
+    }, async ({ deliverables }) => {
+        const { workflowId, stepId } = context;
+        if (!workflowId || !stepId) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: MCP_ERROR_CODE.VALIDATION_ERROR,
+                            message: "No workflow context available. This tool can only be used during a workflow step execution.",
+                        }),
+                    },
+                ],
+            };
+        }
+        try {
+            // Read file contents for each deliverable (best-effort)
+            const enrichedDeliverables = await Promise.all(deliverables.map(async (d) => {
+                try {
+                    let raw;
+                    if (context.projectRoot) {
+                        // Local mode — read directly from filesystem
+                        const absPath = resolve(context.projectRoot, d.filePath);
+                        raw = await readFile(absPath, "utf-8");
+                    }
+                    else {
+                        // Docker mode — read via docker exec in the container
+                        const { getVmManager } = await import("../../vm/vm-manager-facade.js");
+                        const sm = getVmManager();
+                        const session = sm.getSessionByTaskId(context.taskId);
+                        if (!session)
+                            return d;
+                        const { execInContainer } = await import("../../vm/docker-executor.js");
+                        const result = await execInContainer(session.containerId, ["cat", `/session/workspace/${d.filePath}`], { timeout: 10_000 });
+                        if (result.exitCode !== 0)
+                            return d;
+                        raw = result.stdout;
+                    }
+                    const content = raw.length > MAX_FILE_CONTENT_BYTES
+                        ? raw.slice(0, MAX_FILE_CONTENT_BYTES) +
+                            "\n\n--- truncated ---"
+                        : raw;
+                    return { ...d, content };
+                }
+                catch {
+                    return d; // File unreadable — send without content
+                }
+            }));
+            // Auto-commit/push guard: only in local mode (projectRoot set).
+            // In VM mode, the agent manages its own git commits.
+            if (context.projectRoot) {
+                const guardResult = await ensureChangesCommittedAndPushed(context.projectRoot, `step: ${deliverables.map((d) => d.label).join(", ")}`);
+                if (guardResult.error) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: MCP_ERROR_CODE.NETWORK_ERROR,
+                                    message: `Cannot signal step completion: failed to commit/push changes. ${guardResult.error}`,
+                                    retryHint: "Fix the git issue (commit and push your changes manually) then retry forge_complete_step.",
+                                }),
+                            },
+                        ],
+                    };
+                }
+            }
+            if (!context.socketClient.socket.connected) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: MCP_ERROR_CODE.NETWORK_ERROR,
+                                message: "Socket not connected. Cannot signal step completion.",
+                                retryHint: "Cloud may be temporarily unavailable. Retry in a few seconds.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            context.socketClient.emitStepComplete({
+                workflowId,
+                stepId,
+                projectId: context.projectId,
+                deliverables: enrichedDeliverables,
+            });
+            const guardStatus = "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            workflowId,
+                            stepId,
+                            deliverableCount: deliverables.length,
+                            message: `Step completion signaled with ${deliverables.length} deliverable(s). The user will review them before advancing to the next step.${guardStatus ? " " + guardStatus : ""}`,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: MCP_ERROR_CODE.NETWORK_ERROR,
+                            message: error instanceof Error ? error.message : String(error),
+                            retryHint: "Retry in a few seconds.",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}
+//# sourceMappingURL=forge-complete-step.js.map

package/dist/mcp/tools/forge-create-task-group.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpSessionContext } from "../types.js";
+export declare function registerForgeCreateTaskGroup(server: McpServer, context: McpSessionContext): void;
+//# sourceMappingURL=forge-create-task-group.d.ts.map