@stigmer/runner 3.0.1

package/src/activities/execute-deep-agent/execution-state.ts

@@ -0,0 +1,87 @@
+/**
+ * Mutable execution state for the StatusBuilder.
+ *
+ * Holds the AgentExecutionStatus proto being progressively built and
+ * O(1) lookup indexes into its repeated fields. Mutations to indexed
+ * references (ToolCall, AgentMessage) propagate directly to the proto
+ * because they share the same object reference.
+ *
+ * Phase 3b-i scope: core indexes for main-agent streaming.
+ * Sub-agent routing maps and approval tracking are added in Phase 3c.
+ */
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+export class ExecutionState {
+  /** The protobuf projection being built. */
+  readonly proto: AgentExecutionStatus;
+
+  /**
+   * tool_call_id -> live ToolCall reference inside a message's repeated
+   * field. Mutations propagate directly to the proto.
+   */
+  readonly toolCalls: Map<string, ToolCall> = new Map();
+
+  /**
+   * LLM run_id -> the AgentMessage that run is streaming into.
+   * Prevents token interleaving when the model produces multiple runs.
+   */
+  readonly messagesByRun: Map<string, AgentMessage> = new Map();
+
+  /**
+   * Namespace -> most recently created AI message in that execution
+   * context. Tool calls are appended to this message's toolCalls field.
+   * Empty string key represents the main agent.
+   */
+  readonly currentAiMessage: Map<string, AgentMessage> = new Map();
+
+  /**
+   * Namespace -> latest LLM run_id for turn-boundary detection.
+   * When a new run_id appears in the same namespace, a new AgentMessage
+   * is created rather than appending to the existing one.
+   */
+  readonly lastLlmRunId: Map<string, string> = new Map();
+
+  /**
+   * Tool run_id -> monotonic start time (ms) for duration calculation.
+   * Set on on_tool_start, consumed and removed on on_tool_end.
+   */
+  readonly toolStartTimes: Map<string, number> = new Map();
+
+  constructor(proto: AgentExecutionStatus) {
+    this.proto = proto;
+  }
+
+  /**
+   * Reset all ephemeral indexes. The proto itself is not cleared —
+   * this is used when resuming from a persisted status where the proto
+   * already has messages and tool calls, but runtime tracking state
+   * (run_id maps, timing) must start fresh.
+   */
+  resetEphemeralState(): void {
+    this.messagesByRun.clear();
+    this.currentAiMessage.clear();
+    this.lastLlmRunId.clear();
+    this.toolStartTimes.clear();
+  }
+
+  /**
+   * Rebuild the toolCalls index from the proto's messages.
+   *
+   * Used on the resume path where the StatusBuilder is initialized
+   * with a persisted AgentExecutionStatus that already contains
+   * messages and tool calls. Only proto-derivable indexes are rebuilt;
+   * ephemeral runtime state starts fresh.
+   */
+  rebuildToolCallIndex(): void {
+    this.toolCalls.clear();
+    for (const message of this.proto.messages) {
+      for (const tc of message.toolCalls) {
+        if (tc.id) {
+          this.toolCalls.set(tc.id, tc);
+        }
+      }
+    }
+  }
+}

package/src/activities/execute-deep-agent/execution-status-writer.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared interface for proto mutation consumed by side-effect classes
+ * (InlinePublisher, WriteBackCoordinator) and streaming loops.
+ *
+ * Both v2 StatusBuilder and V3StatusBuilder implement this interface,
+ * decoupling side-effect classes from the specific builder version.
+ */
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+
+export interface ExecutionStatusWriter {
+  readonly currentStatus: AgentExecutionStatus;
+  readonly forceNextUpdate: boolean;
+  clearForceFlag(): void;
+  addArtifact(artifact: ExecutionArtifact): void;
+  addWriteBack(wb: WorkspaceWriteBack): void;
+}

package/src/activities/execute-deep-agent/hitl.ts

@@ -0,0 +1,221 @@
+/**
+ * HITL (human-in-the-loop) resume infrastructure for ExecuteDeepAgent.
+ *
+ * On reinvocation after an approval signal, this module:
+ * 1. Reads the persisted execution status from the database
+ * 2. Queries the LangGraph checkpoint for pending interrupts
+ * 3. Matches each interrupt's tool_call_id to the user's approval decision
+ * 4. Builds a `Command(resume={...})` payload for LangGraph
+ * 5. Reconciles tool call statuses in the StatusBuilder
+ *
+ * DB-driven resume: Approval decisions are read from the persisted
+ * execution status (via `client.getExecution()`), NOT passed as Temporal
+ * activity arguments. This matches the Go workflow contract.
+ */
+
+import { Command } from "@langchain/langgraph";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ApprovalAction,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+// APPROVE_ALL resumes the interrupted tool exactly like APPROVE. Its
+// "auto-approve the rest of the run" effect is realized in setup.ts (the
+// approval gate is disabled for the whole execution once any APPROVE_ALL
+// decision exists), not here — this map only resolves the currently
+// interrupted tool calls.
+const ACTION_MAP: ReadonlyMap<ApprovalAction, string> = new Map([
+  [ApprovalAction.APPROVE, "approve"],
+  [ApprovalAction.APPROVE_ALL, "approve"],
+  [ApprovalAction.SKIP, "skip"],
+  [ApprovalAction.REJECT, "reject"],
+]);
+
+export interface ResumeResult {
+  readonly graphInput: Command | Record<string, unknown>;
+  readonly isResumeFromApproval: boolean;
+  readonly hasRejection: boolean;
+  readonly rejectionReason: string;
+}
+
+export interface GraphStateSnapshot {
+  readonly values: Record<string, unknown>;
+  readonly tasks: readonly GraphInterrupt[];
+}
+
+export interface GraphInterrupt {
+  readonly id: string;
+  readonly interrupts?: readonly InterruptValue[];
+}
+
+export interface InterruptValue {
+  readonly value: Record<string, unknown>;
+  readonly resumeValue?: unknown;
+}
+
+/**
+ * Resolve the resume input for a reinvocation after approval.
+ *
+ * Returns a `Command(resume=...)` if there are pending interrupts with
+ * matching approval decisions, or a fresh user message input if this is
+ * not a resume scenario.
+ */
+export async function resolveResumeInput(
+  execution: AgentExecution,
+  agentGraph: { getState(config: Record<string, unknown>): Promise<GraphStateSnapshot> },
+  langgraphConfig: Record<string, unknown>,
+  userMessage: string,
+): Promise<ResumeResult> {
+  const graphState = await agentGraph.getState(langgraphConfig);
+
+  const pendingInterrupts = extractPendingInterrupts(graphState);
+  if (pendingInterrupts.length === 0) {
+    return {
+      graphInput: { messages: [{ role: "user", content: userMessage }] },
+      isResumeFromApproval: false,
+      hasRejection: false,
+      rejectionReason: "",
+    };
+  }
+
+  const decisions = extractApprovalDecisions(execution);
+  if (decisions.size === 0) {
+    return {
+      graphInput: { messages: [{ role: "user", content: userMessage }] },
+      isResumeFromApproval: false,
+      hasRejection: false,
+      rejectionReason: "",
+    };
+  }
+
+  const resumeDict: Record<string, { action: string; comment?: string }> = {};
+  let hasRejection = false;
+  let rejectionReason = "";
+
+  for (const intr of pendingInterrupts) {
+    const toolCallId = intr.toolCallId;
+    const decision = decisions.get(toolCallId);
+    if (!decision) continue;
+
+    const actionStr = ACTION_MAP.get(decision.action);
+    if (!actionStr) continue;
+
+    resumeDict[intr.interruptId] = {
+      action: actionStr,
+      ...(decision.comment ? { comment: decision.comment } : {}),
+    };
+
+    if (decision.action === ApprovalAction.REJECT) {
+      hasRejection = true;
+      rejectionReason = decision.comment || "Rejected by user";
+    }
+  }
+
+  if (Object.keys(resumeDict).length === 0) {
+    return {
+      graphInput: { messages: [{ role: "user", content: userMessage }] },
+      isResumeFromApproval: false,
+      hasRejection: false,
+      rejectionReason: "",
+    };
+  }
+
+  console.log(
+    `[hitl] Building resume for ${Object.keys(resumeDict).length} interrupt(s), ` +
+    `rejection=${hasRejection}`,
+  );
+
+  return {
+    graphInput: new Command({ resume: resumeDict }),
+    isResumeFromApproval: true,
+    hasRejection,
+    rejectionReason,
+  };
+}
+
+interface PendingInterrupt {
+  readonly interruptId: string;
+  readonly toolCallId: string;
+}
+
+function extractPendingInterrupts(state: GraphStateSnapshot): PendingInterrupt[] {
+  const result: PendingInterrupt[] = [];
+
+  for (const task of state.tasks) {
+    if (!task.interrupts) continue;
+    for (const intr of task.interrupts) {
+      if (intr.resumeValue !== undefined) continue;
+
+      const value = intr.value;
+      if (typeof value === "object" && value !== null) {
+        const toolCallId = (value as Record<string, unknown>).tool_call_id;
+        if (typeof toolCallId === "string" && toolCallId) {
+          result.push({ interruptId: task.id, toolCallId });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+interface ApprovalDecisionEntry {
+  readonly action: ApprovalAction;
+  readonly comment: string;
+}
+
+function extractApprovalDecisions(
+  execution: AgentExecution,
+): Map<string, ApprovalDecisionEntry> {
+  const decisions = new Map<string, ApprovalDecisionEntry>();
+  const status = execution.status;
+  if (!status) return decisions;
+
+  for (const message of status.messages) {
+    for (const tc of message.toolCalls) {
+      if (
+        tc.approvalAction !== ApprovalAction.UNSPECIFIED &&
+        tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL
+      ) {
+        decisions.set(tc.id, {
+          action: tc.approvalAction,
+          comment: "",
+        });
+      }
+    }
+  }
+
+  return decisions;
+}
+
+/**
+ * Reconcile tool call statuses after resume decisions are applied.
+ *
+ * Updates the StatusBuilder's tool call entries to reflect the approval
+ * outcomes: APPROVE → RUNNING, SKIP → SKIPPED, REJECT → FAILED.
+ */
+export function reconcileToolCallStatuses(
+  toolCalls: ReadonlyMap<string, ToolCall>,
+  decisions: ReadonlyMap<string, ApprovalDecisionEntry>,
+): void {
+  for (const [toolCallId, decision] of decisions) {
+    const tc = toolCalls.get(toolCallId);
+    if (!tc) continue;
+
+    switch (decision.action) {
+      case ApprovalAction.APPROVE:
+      case ApprovalAction.APPROVE_ALL:
+        tc.status = ToolCallStatus.TOOL_CALL_RUNNING;
+        break;
+      case ApprovalAction.SKIP:
+        tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+        break;
+      case ApprovalAction.REJECT:
+        tc.status = ToolCallStatus.TOOL_CALL_FAILED;
+        tc.error = `Rejected by user: ${decision.comment || "no reason given"}`;
+        break;
+    }
+  }
+}

package/src/activities/execute-deep-agent/index.ts

@@ -0,0 +1,342 @@
+/**
+ * ExecuteDeepAgent activity — runs a Stigmer deep agent via LangGraph.
+ *
+ * Signature matches ExecuteGraphton (Python): (executionId, threadId) → status.
+ * The slim-payload pattern is preserved: input is just IDs, output is a slim
+ * AgentExecutionStatus proto.
+ *
+ * Phase 3b-iii: full middleware stack + artifact storage, inline publishing,
+ * incremental git writeback, and post-stream safety net.
+ */
+
+import { Context, CancelledFailure } from "@temporalio/activity";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ExecutionPhase, InteractionMode, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { activityStarted, activityFinished } from "../../idle-watchdog.js";
+import { persistStatus, slimStatus, utcTimestamp } from "../../shared/status.js";
+import { publishPlanArtifact } from "../../shared/plan-artifact.js";
+import { classifyTool } from "../../shared/tool-kind.js";
+import type { Config } from "../../config.js";
+import { StigmerClient } from "../../client/stigmer-client.js";
+import { performSetup, type SetupResult } from "./setup.js";
+import { streamExecution, type StreamResult } from "./streaming.js";
+import { loadStreamingConfig } from "./streaming-scheduler.js";
+import { StatusBuilder } from "./status-builder.js";
+import { InlinePublisher } from "./inline-publisher.js";
+import { WriteBackCoordinator } from "./writeback-coordinator.js";
+import { processPostStream } from "./post-stream.js";
+import { resolveResumeInput } from "./hitl.js";
+
+export function createDeepAgentActivities(config: Config) {
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+  });
+
+  const streamingConfig = loadStreamingConfig();
+
+  return {
+    ExecuteDeepAgent: async (executionId: string, threadId: string): Promise<unknown> => {
+      activityStarted();
+      let setup: SetupResult | null = null;
+
+      try {
+        console.log(`[ExecuteDeepAgent] Started for execution ${executionId}`);
+
+        setup = await performSetup({ config, client, executionId, threadId });
+
+        const initialStatus = create(AgentExecutionStatusSchema, {});
+        const statusBuilder = new StatusBuilder(executionId, initialStatus);
+
+        statusBuilder.setApprovalProvider({
+          policies: setup.approvalPolicies,
+          toolServerMap: setup.toolServerMap,
+          autoApproveAll: setup.autoApproveAll,
+        });
+
+        const resume = await resolveResumeInput(
+          setup.execution,
+          setup.agentGraph,
+          setup.langgraphConfig,
+          setup.execution.spec!.message,
+        );
+
+        if (resume.hasRejection) {
+          const failedStatus = create(AgentExecutionStatusSchema, {
+            phase: ExecutionPhase.EXECUTION_FAILED,
+            error: `Execution rejected: ${resume.rejectionReason}`,
+            completedAt: utcTimestamp(),
+            messages: [
+              create(AgentMessageSchema, {
+                type: MessageType.MESSAGE_SYSTEM,
+                content: `Execution rejected by user: ${resume.rejectionReason}`,
+                timestamp: utcTimestamp(),
+              }),
+            ],
+          });
+          await persistStatus(client, executionId, failedStatus);
+          return slimStatus(failedStatus);
+        }
+
+        const effectiveInput = resume.isResumeFromApproval
+          ? resume.graphInput
+          : setup.langgraphInput;
+
+        const inlinePublisher = new InlinePublisher({
+          workspaceBackend: setup.workspaceBackend,
+          artifactStorage: setup.artifactStorage,
+          statusWriter: statusBuilder,
+          executionId,
+        });
+
+        const workspaceEntries = setup.session.spec?.workspaceEntries ?? [];
+        const writebackCoordinator = setup.provisionResults.length > 0
+          ? new WriteBackCoordinator({
+              statusWriter: statusBuilder,
+              executionId,
+              provisionResults: setup.provisionResults,
+              workspaceEntries: workspaceEntries as any,
+              workspaceBackend: setup.workspaceBackend,
+            })
+          : null;
+
+        const cancellationSignal = Context.current().cancellationSignal;
+
+        const result: StreamResult = await streamExecution({
+          agentGraph: setup.agentGraph,
+          langgraphInput: effectiveInput as Record<string, unknown>,
+          langgraphConfig: setup.langgraphConfig,
+          executionId,
+          client,
+          initialStatus,
+          streamingConfig,
+          gracefulStop: setup.gracefulStop,
+          inlinePublisher,
+          writebackCoordinator: writebackCoordinator ?? undefined,
+          heartbeatFn: (details) => Context.current().heartbeat(details),
+          isCancelledFn: () => cancellationSignal.aborted,
+          approvalProvider: {
+            policies: setup.approvalPolicies,
+            toolServerMap: setup.toolServerMap,
+            autoApproveAll: setup.autoApproveAll,
+          },
+          streamVersion: setup.streamVersion,
+        });
+
+        await processPostStream({
+          status: initialStatus,
+          inlinePublisher,
+          writebackCoordinator,
+          pendingPublishPromises: result.pendingPublishPromises,
+          pendingWritebackPromises: result.pendingWritebackPromises,
+          executionId,
+        });
+
+        if (result.terminalStatus) {
+          if (initialStatus.phase === ExecutionPhase.EXECUTION_PAUSED) {
+            await persistStatus(client, executionId, initialStatus);
+            console.log(`[ExecuteDeepAgent] Paused for execution ${executionId}: events=${result.eventsProcessed}`);
+            throw new CancelledFailure("Activity paused by orchestrator");
+          }
+          return result.terminalStatus;
+        }
+
+        if (!setup.autoApproveAll) {
+          const graphState = await setup.agentGraph.getState(setup.langgraphConfig);
+          const pendingInterrupts = graphState.tasks?.flatMap(
+            (task: { id: string; interrupts?: readonly { value: Record<string, unknown>; resumeValue?: unknown }[] }) =>
+              (task.interrupts ?? [])
+                .filter((intr) => intr.resumeValue === undefined)
+                .map((intr) => {
+                  const val = intr.value as Record<string, unknown>;
+                  return {
+                    toolCallId: (val?.tool_call_id as string) ?? "",
+                    toolName: (val?.tool_name as string) ?? "",
+                    mcpServerSlug: (val?.mcp_server_slug as string) ?? "",
+                    message: (val?.message as string) ?? "",
+                  };
+                }),
+          ) ?? [];
+
+          if (pendingInterrupts.length > 0) {
+            console.log(
+              `[ExecuteDeepAgent] Detected ${pendingInterrupts.length} pending interrupt(s) ` +
+              `for execution ${executionId} — setting WAITING_FOR_APPROVAL`,
+            );
+            initialStatus.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
+
+            const aiMsg = create(AgentMessageSchema, {
+              type: MessageType.MESSAGE_AI,
+              content: "",
+              timestamp: utcTimestamp(),
+              isStreaming: false,
+            });
+            for (const intr of pendingInterrupts) {
+              aiMsg.toolCalls.push(create(ToolCallSchema, {
+                id: intr.toolCallId,
+                name: intr.toolName,
+                status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+                requiresApproval: true,
+                approvalMessage: intr.message,
+                approvalRequestedAt: utcTimestamp(),
+                mcpServerSlug: intr.mcpServerSlug,
+                startedAt: utcTimestamp(),
+                toolKind: classifyTool(intr.toolName, intr.mcpServerSlug),
+              }));
+            }
+            initialStatus.messages.push(aiMsg);
+
+            await persistStatus(client, executionId, initialStatus);
+            return slimStatus(initialStatus);
+          }
+        }
+
+        initialStatus.phase = ExecutionPhase.EXECUTION_COMPLETED;
+        initialStatus.completedAt = utcTimestamp();
+
+        let structuredOutput: JsonObject | undefined;
+        let finalText: string | undefined;
+
+        const lastAiMsg = [...initialStatus.messages]
+          .reverse()
+          .find(m => m.type === MessageType.MESSAGE_AI);
+        if (lastAiMsg) {
+          finalText = lastAiMsg.content;
+        }
+
+        if (setup.hasStructuredOutput) {
+          // Primary source: deepagents' structuredResponse surfaced via the v3
+          // run.output. This is the reliable path when the graph populates it.
+          const sr = result.runOutput?.structuredResponse;
+          if (sr != null && typeof sr === "object" && !Array.isArray(sr)) {
+            structuredOutput = sr as JsonObject;
+          } else if (sr !== undefined) {
+            console.warn(
+              `[ExecuteDeepAgent] structuredResponse is not a plain object ` +
+              `for execution ${executionId}: type=${typeof sr}`,
+            );
+          }
+
+          // Fallback: extract JSON from the agent's final text message. The v3
+          // streaming path does not surface deepagents' structuredResponse
+          // (hasStructuredResponse=false), so we recover structured output by
+          // parsing the agent's final response (JSON / code-fence / last-brace).
+          if (structuredOutput === undefined && finalText) {
+            const { extractJsonFromText } = await import("../../shared/extract-json.js");
+            const extracted = extractJsonFromText(finalText);
+            if (extracted != null && typeof extracted === "object" && !Array.isArray(extracted)) {
+              structuredOutput = extracted as JsonObject;
+              console.log(
+                `[ExecuteDeepAgent] structured output extracted from final text ` +
+                `for execution ${executionId}: finalTextLength=${finalText.length}`,
+              );
+            }
+          }
+
+          if (structuredOutput !== undefined) {
+            initialStatus.structuredOutput = structuredOutput;
+          }
+        }
+
+        // Plan mode: the agent's final message is the plan. Publish it as a
+        // first-class plan.md artifact so the UI can render a reviewable Plan
+        // card and a follow-up Implement run can reference it. Read-only mode
+        // produces no file to auto-publish, so this is the only artifact path.
+        if (
+          setup.execution.spec?.executionConfig?.interactionMode === InteractionMode.PLAN &&
+          finalText
+        ) {
+          await publishPlanArtifact({
+            status: initialStatus,
+            executionId,
+            planText: finalText,
+            artifactStorage: setup.artifactStorage,
+          });
+        }
+
+        await persistStatus(client, executionId, initialStatus);
+
+        console.log(
+          `[ExecuteDeepAgent] Completed for execution ${executionId}: ` +
+          `events=${result.eventsProcessed}, ` +
+          `messages=${initialStatus.messages.length}, ` +
+          `artifacts=${initialStatus.artifacts.length}, ` +
+          `writebacks=${initialStatus.workspaceWriteBacks.length}, ` +
+          `hasStructuredOutput=${structuredOutput !== undefined}`,
+        );
+
+        const slim = slimStatus(initialStatus) as Record<string, unknown>;
+        if (finalText !== undefined) {
+          slim.final_text = finalText;
+        }
+        if (structuredOutput !== undefined) {
+          slim.structured = structuredOutput;
+        }
+        return slim;
+
+      } catch (err: unknown) {
+        if (err instanceof CancelledFailure) {
+          console.log(`[ExecuteDeepAgent] Cancelled (pause) for execution ${executionId}`);
+          const pausedStatus = create(AgentExecutionStatusSchema, {
+            phase: ExecutionPhase.EXECUTION_PAUSED,
+          });
+          await persistStatus(client, executionId, pausedStatus).catch(() => {});
+          throw err;
+        }
+
+        if (Context.current().cancellationSignal.aborted) {
+          console.log(`[ExecuteDeepAgent] Error during cancellation for ${executionId}, treating as pause: ${err}`);
+          const pausedStatus = create(AgentExecutionStatusSchema, {
+            phase: ExecutionPhase.EXECUTION_PAUSED,
+          });
+          await persistStatus(client, executionId, pausedStatus).catch(() => {});
+          throw new CancelledFailure("Activity paused by orchestrator (error during cancellation)");
+        }
+
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const errorType = err instanceof Error ? err.constructor.name : "UnknownError";
+
+        console.error(
+          `[ExecuteDeepAgent] Failed for execution ${executionId}: ` +
+          `[${errorType}] ${errorMessage}`,
+        );
+
+        const failedStatus = create(AgentExecutionStatusSchema, {
+          phase: ExecutionPhase.EXECUTION_FAILED,
+          error: `Execution failed: [${errorType}] ${errorMessage}`,
+          completedAt: utcTimestamp(),
+          messages: [
+            create(AgentMessageSchema, {
+              type: MessageType.MESSAGE_SYSTEM,
+              content: `Error: [${errorType}] ${errorMessage}`,
+              timestamp: utcTimestamp(),
+            }),
+          ],
+        });
+
+        await persistStatus(client, executionId, failedStatus);
+        return slimStatus(failedStatus);
+
+      } finally {
+        await cleanup(setup);
+        activityFinished();
+      }
+    },
+  };
+}
+
+async function cleanup(setup: SetupResult | null): Promise<void> {
+  if (!setup) return;
+
+  if (setup.mcpConnection) {
+    try {
+      await setup.mcpConnection.client.close();
+    } catch (err) {
+      console.warn("[ExecuteDeepAgent] MCP connection cleanup failed:", err);
+    }
+  }
+}
+