@n8n/instance-ai 1.3.5 → 1.5.0

package/dist/tools/orchestration/build-workflow-agent.tool.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildWorkflowAgentInputSchema = void 0;
+exports.buildWarmBuilderFollowUp = buildWarmBuilderFollowUp;
 exports.recordSuccessfulWorkflowBuilds = recordSuccessfulWorkflowBuilds;
+exports.mergeLatestVerificationIntoOutcome = mergeLatestVerificationIntoOutcome;
+exports.withTerminalLoopState = withTerminalLoopState;
+exports.finalizeBuildResult = finalizeBuildResult;
 exports.resultFromPostStreamError = resultFromPostStreamError;
+exports.resultFromLaterFailedMainSubmit = resultFromLaterFailedMainSubmit;
+exports.attemptFromAutoResubmit = attemptFromAutoResubmit;
+exports.shouldRecoverSavedWorkflowAfterFailedSubmit = shouldRecoverSavedWorkflowAfterFailedSubmit;
 exports.startBuildWorkflowAgentTask = startBuildWorkflowAgentTask;
 exports.createBuildWorkflowAgentTool = createBuildWorkflowAgentTool;
 const agent_1 = require("@mastra/core/agent");
@@ -12,29 +19,63 @@ const nanoid_1 = require("nanoid");
 const node_crypto_1 = require("node:crypto");
 const zod_1 = require("zod");
 const build_workflow_agent_prompt_1 = require("./build-workflow-agent.prompt");
+const builder_memory_compaction_1 = require("./builder-memory-compaction");
 const display_utils_1 = require("./display-utils");
 const tracing_utils_1 = require("./tracing-utils");
 const verify_built_workflow_tool_1 = require("./verify-built-workflow.tool");
 const register_with_mastra_1 = require("../../agent/register-with-mastra");
 const sub_agent_briefing_1 = require("../../agent/sub-agent-briefing");
 const max_steps_1 = require("../../constants/max-steps");
+const model_settings_1 = require("../../constants/model-settings");
 const resumable_stream_executor_1 = require("../../runtime/resumable-stream-executor");
 const consume_with_hitl_1 = require("../../stream/consume-with-hitl");
 const langsmith_tracing_1 = require("../../tracing/langsmith-tracing");
 const extract_code_1 = require("../../workflow-builder/extract-code");
+const workflow_loop_1 = require("../../workflow-loop");
 const sandbox_fs_1 = require("../../workspace/sandbox-fs");
 const sandbox_setup_1 = require("../../workspace/sandbox-setup");
 const resolve_credentials_1 = require("../workflows/resolve-credentials");
-const submit_workflow_tool_1 = require("../workflows/submit-workflow.tool");
-const UNTESTABLE_TRIGGERS = new Set([
-    'n8n-nodes-base.webhook',
-    'n8n-nodes-base.formTrigger',
-    '@n8n/n8n-nodes-langchain.mcpTrigger',
-    '@n8n/n8n-nodes-langchain.chatTrigger',
-]);
-function triggerLabel(nodeType) {
-    const short = nodeType.split('.').pop() ?? nodeType;
-    return short.replace(/Trigger$/i, '').toLowerCase() || short.toLowerCase();
+const submit_workflow_identity_1 = require("../workflows/submit-workflow-identity");
+function createBuilderResourceId(userId) {
+    return `${userId}:workflow-builder`;
+}
+function buildWarmBuilderFollowUp(input) {
+    const parts = [
+        '<builder-follow-up type="fix">',
+        `Work item ID: ${input.workItemId}`,
+        `Workflow ID: ${input.workflowId}`,
+        'Continue from the existing sandbox files and your prior builder messages/tool calls. Apply the requested change, then submit the main workflow file.',
+        '',
+        DETACHED_BUILDER_REQUIREMENTS,
+    ];
+    if (input.conversationContext) {
+        parts.push('', '<conversation-context>', input.conversationContext, '</conversation-context>');
+    }
+    parts.push('', '<requested-change>', input.task, '</requested-change>', '</builder-follow-up>');
+    return parts.join('\n');
+}
+async function ensureBuilderMemoryThread(context, binding) {
+    if (!context.memory)
+        return false;
+    try {
+        const existingThread = await context.memory.getThreadById({ threadId: binding.thread });
+        if (existingThread)
+            return true;
+        const now = new Date();
+        await context.memory.saveThread({
+            thread: {
+                id: binding.thread,
+                resourceId: binding.resource,
+                title: 'Workflow Builder',
+                createdAt: now,
+                updatedAt: now,
+            },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 async function promoteMainWorkflow(context, logger, workflowId) {
     if (!workflowId || !context)
@@ -64,41 +105,95 @@ function recordSuccessfulWorkflowBuilds(tool, onWorkflowId) {
         return result;
     };
 }
-const UNTESTABLE_TRIGGER_LABELS = [...UNTESTABLE_TRIGGERS].map(triggerLabel).join(', ');
-function detectTriggerType(attempt) {
-    if (!attempt?.triggerNodeTypes || attempt.triggerNodeTypes.length === 0) {
-        return 'manual_or_testable';
-    }
-    const allUntestable = attempt.triggerNodeTypes.every((t) => UNTESTABLE_TRIGGERS.has(t));
-    return allUntestable ? 'trigger_only' : 'manual_or_testable';
+function detectTriggerType(_attempt) {
+    return 'manual_or_testable';
 }
-function buildOutcome(workItemId, taskId, attempt, finalText) {
+function buildOutcome(workItemId, runId, taskId, attempt, finalText) {
     if (!attempt?.success) {
         return {
             workItemId,
+            runId,
             taskId,
             submitted: false,
             triggerType: 'manual_or_testable',
             needsUserInput: false,
             failureSignature: attempt?.errors?.join('; '),
+            remediation: attempt?.remediation,
             summary: finalText,
         };
     }
+    const placeholderRemediation = attempt.hasUnresolvedPlaceholders
+        ? (0, workflow_loop_1.createRemediation)({
+            category: 'needs_setup',
+            shouldEdit: false,
+            reason: 'mocked_credentials_or_placeholders',
+            guidance: 'Workflow submitted successfully, but unresolved setup values remain. Stop code edits and route to workflows(action="setup").',
+        })
+        : undefined;
     return {
         workItemId,
+        runId,
         taskId,
         workflowId: attempt.workflowId,
         submitted: true,
-        triggerType: attempt.hasUnresolvedPlaceholders ? 'trigger_only' : detectTriggerType(attempt),
-        needsUserInput: false,
+        triggerType: detectTriggerType(attempt),
+        needsUserInput: Boolean(placeholderRemediation),
+        blockingReason: placeholderRemediation?.guidance,
         mockedNodeNames: attempt.mockedNodeNames,
         mockedCredentialTypes: attempt.mockedCredentialTypes,
         mockedCredentialsByNode: attempt.mockedCredentialsByNode,
+        triggerNodes: attempt.triggerNodes,
         verificationPinData: attempt.verificationPinData,
         hasUnresolvedPlaceholders: attempt.hasUnresolvedPlaceholders,
+        remediation: placeholderRemediation ?? attempt.remediation,
         summary: finalText,
     };
 }
+function mergeLatestVerificationIntoOutcome(outcome, latestOutcome) {
+    if (!latestOutcome?.verification)
+        return outcome;
+    if (latestOutcome.workItemId !== outcome.workItemId)
+        return outcome;
+    if (latestOutcome.taskId !== outcome.taskId)
+        return outcome;
+    if (outcome.workflowId &&
+        latestOutcome.workflowId &&
+        latestOutcome.workflowId !== outcome.workflowId) {
+        return outcome;
+    }
+    return {
+        ...outcome,
+        verification: latestOutcome.verification,
+    };
+}
+function withTerminalLoopState(outcome, state) {
+    const remediation = state?.lastRemediation;
+    if (!outcome.submitted || !remediation || remediation.shouldEdit) {
+        return outcome;
+    }
+    return {
+        ...outcome,
+        workflowId: outcome.workflowId ?? state.workflowId,
+        needsUserInput: remediation.category === 'needs_setup',
+        blockingReason: remediation.guidance,
+        remediation,
+    };
+}
+async function finalBuildOutcome(context, workItemId, outcome) {
+    const latestOutcome = await getLatestBuildOutcome(context, workItemId);
+    const loopState = await context.workflowTaskService?.getWorkflowLoopState(workItemId);
+    return withTerminalLoopState(mergeLatestVerificationIntoOutcome(outcome, latestOutcome), loopState);
+}
+async function finalizeBuildResult(context, workItemId, result) {
+    return {
+        text: result.text,
+        outcome: await finalBuildOutcome(context, workItemId, result.outcome),
+    };
+}
+async function buildOutcomeWithLatestVerification(context, workItemId, taskId, attempt, finalText) {
+    const outcome = buildOutcome(workItemId, context.runId, taskId, attempt, finalText);
+    return await finalBuildOutcome(context, workItemId, outcome);
+}
 const DETACHED_BUILDER_REQUIREMENTS = `## Detached Task Contract
 
 You are running as a detached background task. Do not stop after a successful submit — verify the workflow works.
@@ -107,56 +202,200 @@ You are running as a detached background task. Do not stop after a successful su
 
 Your job is done when ONE of these is true:
 - the workflow is verified (ran successfully)
-- the workflow uses only event triggers (${UNTESTABLE_TRIGGER_LABELS}) and cannot be runtime-tested — stop after a successful submit. Do NOT publish it; the orchestrator will handle setup and publishing.
 - you are blocked after one repair attempt per unique failure
 
+Do NOT stop after a successful submit without verifying. Every trigger type is testable:
+manual / schedule via \`executions(action="run")\`; event-based triggers (form, webhook,
+chat, mcp, linear, github, slack, etc.) via \`verify-built-workflow\` with an \`inputData\`
+payload. The pin-data adapter injects it as the trigger node's output.
+
 ### Submit discipline
 
 **Every file edit MUST be followed by submit-workflow before you do anything else.**
-The system tracks file hashes. If you edit the code and then call run-workflow or finish without re-submitting, your work is discarded. The sequence is always: edit → submit → then verify/run.
+The system tracks file hashes. If you edit the code and then call \`executions(action="run")\` or finish without re-submitting, your work is discarded. The sequence is always: edit → submit → then verify/run.
 
 ### Verification
 
-- If submit-workflow returned mocked credentials, call verify-built-workflow with the workItemId
-- Otherwise call run-workflow to test (skip for trigger-only workflows). For event-based triggers (Linear, GitHub, Slack, etc.), pass \`inputData\` with sample data matching the trigger's expected output shape — the system injects it as the trigger node's output.
-- If verification fails, call debug-execution, fix the code, re-submit, and retry once
-- If the same failure signature repeats, stop and explain the block
+- If submit-workflow returned mocked credentials, call \`verify-built-workflow\` with the workItemId.
+- Otherwise pick based on trigger type:
+  - **Manual / Schedule** — \`executions(action="run")\`.
+  - **Form Trigger** — \`verify-built-workflow\` with \`inputData\` as a flat field map, e.g. \`{name: "Alice", email: "a@b.c"}\`. Do NOT wrap in \`formFields\` — production Form Trigger emits fields directly on \`$json\`, and the adapter rejects wrapped payloads.
+  - **Webhook** — \`verify-built-workflow\` with \`inputData\` as the body payload, e.g. \`{event: "signup", userId: "..."}\`. Adapter wraps it under \`body\`; downstream expressions use \`$json.body.<field>\`.
+  - **Chat Trigger** — \`verify-built-workflow\` with \`{chatInput: "user message"}\`.
+  - **Other event triggers (Linear, GitHub, Slack, MCP, etc.)** — \`verify-built-workflow\` with \`inputData\` matching the trigger's expected payload shape.
+- If verify-built-workflow returns remediation with \`shouldEdit: false\`, stop editing and follow its guidance.
+- If verification fails with \`shouldEdit: true\`, make one batched code repair and re-submit. Never exceed the remaining repair budget in the remediation metadata.
+- If verification fails otherwise, call \`executions(action="debug")\`, fix the code, re-submit, and retry once.
+- If the same failure signature repeats, stop and explain the block.
 
 ### Resource discovery
 
 Before writing code that uses external services, **resolve real resource IDs**:
-- Call explore-node-resources for any parameter with searchListMethod (calendars, spreadsheets, channels, models, etc.)
+- Call \`nodes(action="explore-resources")\` for any parameter with searchListMethod (calendars, spreadsheets, channels, models, etc.)
 - Do NOT use "primary", "default", or any assumed identifier — look up the actual value
-- Call get-suggested-nodes early if the workflow fits a known category (web_app, form_input, data_persistence, etc.) — the pattern hints prevent common mistakes
+- Call \`nodes(action="suggested")\` early if the workflow fits a known category (web_app, form_input, data_persistence, etc.) — the pattern hints prevent common mistakes
 - Check @builderHint annotations in node type definitions for critical configuration guidance
 
 ### Publishing
 
-Do NOT call \`publish-workflow\` for the main workflow. Publishing is the user's decision after testing. Your job ends at a successful submit. The only exception is sub-workflows in the compositional pattern — those must be published so the parent workflow can reference them.
+Do NOT call \`workflows(action="publish")\` for the main workflow. Publishing is the user's decision after testing. Your job ends at a successful submit. The only exception is sub-workflows in the compositional pattern — those must be published so the parent workflow can reference them.
 `;
 function hashContent(content) {
     return (0, node_crypto_1.createHash)('sha256')
         .update(content ?? '', 'utf8')
         .digest('hex');
 }
-function resultFromPostStreamError(input) {
-    let attempt;
-    for (let i = input.submitAttempts.length - 1; i >= 0; i--) {
-        const a = input.submitAttempts[i];
-        if (a.filePath === input.mainWorkflowPath && a.success) {
-            attempt = a;
-            break;
+function deterministicSuffix(seed, label, length) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(label)
+        .update('\0')
+        .update(seed)
+        .digest('hex')
+        .slice(0, length);
+}
+function shouldUseDeterministicBuilderIds(context) {
+    return process.env.E2E_TESTS === 'true' && context.tracing?.replayMode !== 'off';
+}
+function createDeterministicBuilderIds(input) {
+    const seed = JSON.stringify({
+        task: input.task,
+        workflowId: input.workflowId ?? '',
+        plannedTaskId: input.plannedTaskId ?? '',
+        conversationContext: input.conversationContext ?? '',
+    });
+    return {
+        subAgentId: `agent-builder-${deterministicSuffix(seed, 'agent', 6)}`,
+        taskId: `build-${deterministicSuffix(seed, 'task', 8)}`,
+        workItemId: `wi_${deterministicSuffix(seed, 'work-item', 8)}`,
+    };
+}
+function latestSuccessfulMainSubmit(submitAttempts, mainWorkflowPath) {
+    for (let i = submitAttempts.length - 1; i >= 0; i--) {
+        const attempt = submitAttempts[i];
+        if (attempt.filePath === mainWorkflowPath && attempt.success && attempt.workflowId) {
+            return attempt;
         }
     }
+    return undefined;
+}
+function latestMainSubmit(submitAttempts, mainWorkflowPath) {
+    for (let i = submitAttempts.length - 1; i >= 0; i--) {
+        const attempt = submitAttempts[i];
+        if (attempt.filePath === mainWorkflowPath) {
+            return attempt;
+        }
+    }
+    return undefined;
+}
+function resultFromPostStreamError(input) {
+    const latestAttempt = latestMainSubmit(input.submitAttempts, input.mainWorkflowPath);
+    if (!latestAttempt)
+        return undefined;
+    const attempt = latestAttempt.success
+        ? latestAttempt
+        : shouldRecoverSavedWorkflowAfterFailedSubmit(latestAttempt)
+            ? latestSuccessfulMainSubmit(input.submitAttempts, input.mainWorkflowPath)
+            : undefined;
     if (!attempt)
         return undefined;
     const errorText = input.error instanceof Error ? input.error.message : String(input.error);
     const text = `Workflow ${attempt.workflowId} submitted successfully. A later step failed: ${errorText}`;
     return {
         text,
-        outcome: buildOutcome(input.workItemId, input.taskId, attempt, text),
+        outcome: buildOutcome(input.workItemId, input.runId, input.taskId, attempt, text),
+    };
+}
+async function getWorkflowNodeSummaries(context, workflowId) {
+    if (!context || !workflowId)
+        return undefined;
+    try {
+        const json = await context.workflowService.getAsWorkflowJSON(workflowId);
+        const summaries = [];
+        for (const node of json.nodes ?? []) {
+            if (!node.name || !node.type)
+                continue;
+            summaries.push({ name: node.name, type: node.type });
+        }
+        return summaries;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function getLatestBuildOutcome(context, workItemId) {
+    try {
+        return await context.workflowTaskService?.getBuildOutcome(workItemId);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function compactSuccessfulBuilderMemory(input) {
+    if (!input.shouldUseBuilderMemory)
+        return;
+    try {
+        const [nodeSummaries, latestOutcome] = await Promise.all([
+            getWorkflowNodeSummaries(input.domainContext, input.workflowId),
+            getLatestBuildOutcome(input.context, input.workItemId),
+        ]);
+        await (0, builder_memory_compaction_1.compactBuilderMemoryThread)({
+            context: input.context,
+            binding: input.binding,
+            sessionId: input.activeBuilderSession?.sessionId,
+            workflowId: input.workflowId,
+            workItemId: input.workItemId,
+            sourceFilePath: input.mainWorkflowPath,
+            nodeSummaries,
+            triggerNodes: input.mainWorkflowAttempt.triggerNodes,
+            mockedNodeNames: input.mainWorkflowAttempt.mockedNodeNames,
+            mockedCredentialTypes: input.mainWorkflowAttempt.mockedCredentialTypes,
+            mockedCredentialsByNode: input.mainWorkflowAttempt.mockedCredentialsByNode,
+            verification: latestOutcome?.verification,
+            lastRequestedChange: input.lastRequestedChange,
+            finalBuilderResult: input.finalText,
+        });
+    }
+    catch {
+    }
+}
+function resultFromLaterFailedMainSubmit(input) {
+    if (!shouldRecoverSavedWorkflowAfterFailedSubmit(input.failedAttempt))
+        return undefined;
+    const preservedAttempt = latestSuccessfulMainSubmit(input.submitAttempts, input.mainWorkflowPath);
+    if (!preservedAttempt)
+        return undefined;
+    const errorText = input.failedAttempt.errors?.join(' ') ?? 'Unknown submit-workflow failure.';
+    const text = `Workflow ${preservedAttempt.workflowId} was already submitted successfully. ` +
+        `A later submit failed: ${errorText}`;
+    return {
+        text,
+        outcome: buildOutcome(input.workItemId, input.runId, input.taskId, preservedAttempt, text),
     };
 }
+function isFreshAttemptForHash(attempt, sourceHash) {
+    return attempt?.sourceHash === sourceHash;
+}
+function attemptFromAutoResubmit(input) {
+    if (isFreshAttemptForHash(input.latestAttempt, input.sourceHash)) {
+        return input.latestAttempt;
+    }
+    if (input.resubmit.success)
+        return undefined;
+    return {
+        filePath: input.filePath,
+        sourceHash: input.sourceHash,
+        success: false,
+        errors: input.resubmit.errors,
+        remediation: input.resubmit.remediation,
+    };
+}
+function shouldRecoverSavedWorkflowAfterFailedSubmit(attempt) {
+    return attempt.remediation?.shouldEdit === false;
+}
+function formatSubmitWorkflowErrors(output, fallback) {
+    const errors = output.errors?.join(' ') ?? '';
+    return errors.length > 0 ? errors : fallback;
+}
 async function startBuildWorkflowAgentTask(context, input) {
     if (!context.spawnBackgroundTask) {
         return {
@@ -165,6 +404,7 @@ async function startBuildWorkflowAgentTask(context, input) {
             agentId: '',
         };
     }
+    const spawnBackgroundTask = context.spawnBackgroundTask;
     const factory = context.builderSandboxFactory;
     const domainContext = context.domainContext;
     const useSandbox = !!factory && !!domainContext;
@@ -210,30 +450,30 @@ async function startBuildWorkflowAgentTask(context, input) {
             return { result: 'Error: build-workflow tool not available.', taskId: '', agentId: '' };
         }
     }
-    const subAgentId = input.agentId ?? `agent-builder-${(0, nanoid_1.nanoid)(6)}`;
-    const taskId = input.taskId ?? `build-${(0, nanoid_1.nanoid)(8)}`;
-    const workItemId = `wi_${(0, nanoid_1.nanoid)(8)}`;
-    context.eventBus.publish(context.threadId, {
-        type: 'agent-spawned',
-        runId: context.runId,
-        agentId: subAgentId,
-        payload: {
-            parentId: context.orchestratorAgentId,
-            role: 'workflow-builder',
-            tools: Object.keys(builderTools),
-            taskId,
-            kind: 'builder',
-            title: 'Building workflow',
-            subtitle: (0, display_utils_1.truncateLabel)(input.task),
-            goal: input.task,
-            targetResource: input.workflowId
-                ? { type: 'workflow', id: input.workflowId }
-                : { type: 'workflow' },
-        },
-    });
+    const deterministicIds = shouldUseDeterministicBuilderIds(context)
+        ? createDeterministicBuilderIds(input)
+        : undefined;
+    const subAgentId = input.agentId ?? deterministicIds?.subAgentId ?? `agent-builder-${(0, nanoid_1.nanoid)(6)}`;
+    const taskId = input.taskId ?? deterministicIds?.taskId ?? `build-${(0, nanoid_1.nanoid)(8)}`;
+    const baseWorkItemId = input.workItemId ??
+        deterministicIds?.workItemId ??
+        (input.workflowId ? `${context.runId}:default` : `wi_${(0, nanoid_1.nanoid)(8)}`);
     const { workflowId } = input;
+    const reusedBuilderSession = useSandbox && workflowId
+        ? context.builderSandboxSessionRegistry?.acquireByWorkflowId(context.threadId, workflowId)
+        : undefined;
+    const workItemId = reusedBuilderSession?.workItemId ?? baseWorkItemId;
+    const builderThreadId = reusedBuilderSession?.builderThreadId ?? (0, node_crypto_1.randomUUID)();
+    const builderResourceId = reusedBuilderSession?.builderResourceId ?? createBuilderResourceId(context.userId);
+    const builderMemoryBinding = {
+        resource: builderResourceId,
+        thread: builderThreadId,
+    };
     let additionalContext = '';
-    if (useSandbox && workflowId) {
+    if (reusedBuilderSession && workflowId) {
+        additionalContext = '';
+    }
+    else if (useSandbox && workflowId) {
         additionalContext = `[CONTEXT: Modifying existing workflow ${workflowId}. The current code is pre-loaded in ~/workspace/src/workflow.ts — read it first, then edit. Use workflowId "${workflowId}" when calling submit-workflow.]\n\n[WORK ITEM ID: ${workItemId}]`;
     }
     else if (useSandbox) {
@@ -242,76 +482,347 @@ async function startBuildWorkflowAgentTask(context, input) {
     else if (workflowId) {
         additionalContext = `[CONTEXT: Modifying existing workflow ${workflowId}. Use workflowId "${workflowId}" when calling build-workflow.]`;
     }
-    const briefing = await (0, sub_agent_briefing_1.buildSubAgentBriefing)({
-        task: input.task,
-        conversationContext: input.conversationContext,
-        additionalContext: additionalContext || undefined,
-        requirements: useSandbox ? DETACHED_BUILDER_REQUIREMENTS : undefined,
-        iteration: context.iterationLog
-            ? {
-                log: context.iterationLog,
-                threadId: context.threadId,
-                taskKey: `build:${workflowId ?? 'new'}`,
-            }
-            : undefined,
-        runningTasks: context.getRunningTaskSummaries?.(),
-    });
-    const traceContext = await (0, tracing_utils_1.createDetachedSubAgentTracing)(context, {
-        agentId: subAgentId,
-        role: 'workflow-builder',
-        kind: 'builder',
-        taskId,
-        plannedTaskId: input.plannedTaskId,
-        workItemId,
-        inputs: {
+    const runningTaskSummaries = context.getRunningTaskSummaries?.();
+    const briefing = reusedBuilderSession && workflowId
+        ? buildWarmBuilderFollowUp({
             task: input.task,
-            workflowId: input.workflowId,
             conversationContext: input.conversationContext,
-        },
-    });
-    context.spawnBackgroundTask({
-        taskId,
-        threadId: context.threadId,
-        agentId: subAgentId,
-        role: 'workflow-builder',
-        traceContext,
-        plannedTaskId: input.plannedTaskId,
-        workItemId,
-        run: async (signal, drainCorrections, waitForCorrection) => await (0, tracing_utils_1.withTraceContextActor)(traceContext, async () => {
-            let builderWs;
-            const submitAttempts = new Map();
-            const submitAttemptHistory = [];
-            try {
-                if (useSandbox) {
-                    builderWs = await factory.create(subAgentId, domainContext);
-                    const workspace = builderWs.workspace;
-                    const root = await (0, sandbox_setup_1.getWorkspaceRoot)(workspace);
-                    prompt = (0, build_workflow_agent_prompt_1.createSandboxBuilderAgentPrompt)(root);
-                    if (workflowId && domainContext) {
+            workflowId,
+            workItemId,
+        })
+        : await (0, sub_agent_briefing_1.buildSubAgentBriefing)({
+            task: input.task,
+            conversationContext: input.conversationContext,
+            additionalContext: additionalContext || undefined,
+            requirements: useSandbox ? DETACHED_BUILDER_REQUIREMENTS : undefined,
+            iteration: context.iterationLog
+                ? {
+                    log: context.iterationLog,
+                    threadId: context.threadId,
+                    taskKey: `build:${workflowId ?? 'new'}`,
+                }
+                : undefined,
+            runningTasks: runningTaskSummaries,
+        });
+    let traceContext;
+    try {
+        traceContext = await (0, tracing_utils_1.createDetachedSubAgentTracing)(context, {
+            agentId: subAgentId,
+            role: 'workflow-builder',
+            kind: 'builder',
+            taskId,
+            plannedTaskId: input.plannedTaskId,
+            workItemId,
+            inputs: {
+                task: input.task,
+                workflowId: input.workflowId,
+                conversationContext: input.conversationContext,
+            },
+        });
+    }
+    catch (error) {
+        if (reusedBuilderSession) {
+            void context.builderSandboxSessionRegistry?.release(reusedBuilderSession.sessionId, {
+                keep: true,
+                reason: 'trace_setup_failed',
+            });
+        }
+        throw error;
+    }
+    let spawnOutcome;
+    try {
+        spawnOutcome = spawnBackgroundTask({
+            taskId,
+            threadId: context.threadId,
+            agentId: subAgentId,
+            role: 'workflow-builder',
+            traceContext,
+            plannedTaskId: input.plannedTaskId,
+            workItemId,
+            dedupeKey: {
+                role: 'workflow-builder',
+                plannedTaskId: input.plannedTaskId,
+                workflowId: input.workflowId,
+            },
+            parentCheckpointId: context.isCheckpointFollowUp === true ? context.checkpointTaskId : undefined,
+            run: async (signal, drainCorrections, waitForCorrection) => await (0, tracing_utils_1.withTraceContextActor)(traceContext, async () => {
+                let builderWs;
+                let activeBuilderSession = reusedBuilderSession;
+                const submitAttempts = new Map();
+                const submitAttemptHistory = [];
+                try {
+                    if (useSandbox) {
+                        let workspace;
+                        let root;
+                        if (activeBuilderSession) {
+                            workspace = activeBuilderSession.workspace;
+                            root = activeBuilderSession.root;
+                        }
+                        else {
+                            builderWs = await factory.create(subAgentId, domainContext);
+                            workspace = builderWs.workspace;
+                            root = await (0, sandbox_setup_1.getWorkspaceRoot)(workspace);
+                        }
+                        prompt = (0, build_workflow_agent_prompt_1.createSandboxBuilderAgentPrompt)(root);
+                        if (!activeBuilderSession && builderWs) {
+                            activeBuilderSession = context.builderSandboxSessionRegistry?.create({
+                                threadId: context.threadId,
+                                workflowId,
+                                workItemId,
+                                builderThreadId,
+                                builderResourceId,
+                                builderWorkspace: builderWs,
+                                root,
+                            });
+                        }
+                        if (!reusedBuilderSession && workflowId && domainContext) {
+                            try {
+                                const json = await domainContext.workflowService.getAsWorkflowJSON(workflowId);
+                                let rawCode = (0, workflow_sdk_1.generateWorkflowCode)(json);
+                                rawCode = rawCode.replace(/newCredential\('([^']*)',\s*'([^']*)'\)/g, "{ id: '$2', name: '$1' }");
+                                const code = `${extract_code_1.SDK_IMPORT_STATEMENT}\n\n${rawCode}`;
+                                if (workspace.filesystem) {
+                                    await workspace.filesystem.writeFile(`${root}/src/workflow.ts`, code, {
+                                        recursive: true,
+                                    });
+                                }
+                            }
+                            catch {
+                            }
+                        }
+                        const mainWorkflowPath = `${root}/src/workflow.ts`;
+                        builderTools['submit-workflow'] = (0, submit_workflow_identity_1.createIdentityEnforcedSubmitWorkflowTool)({
+                            context: domainContext,
+                            workspace,
+                            credentialMap: credMap,
+                            root,
+                            currentRunId: context.runId,
+                            getWorkflowLoopState: async () => await context.workflowTaskService?.getWorkflowLoopState(workItemId),
+                            onGuardFired: (event) => {
+                                context.trackTelemetry?.('Builder remediation guard fired', {
+                                    thread_id: context.threadId,
+                                    run_id: context.runId,
+                                    work_item_id: workItemId,
+                                    workflow_id: event.workflowId,
+                                    category: event.category,
+                                    attempt_count: event.attemptCount,
+                                    reason: event.reason,
+                                });
+                            },
+                            onAttempt: async (attempt) => {
+                                submitAttempts.set(attempt.filePath, attempt);
+                                submitAttemptHistory.push(attempt);
+                                if (attempt.filePath !== mainWorkflowPath) {
+                                    return;
+                                }
+                                if (attempt.success && attempt.workflowId && activeBuilderSession) {
+                                    context.builderSandboxSessionRegistry?.aliasWorkflowId(activeBuilderSession.sessionId, attempt.workflowId);
+                                }
+                                if (!context.workflowTaskService) {
+                                    return;
+                                }
+                                await context.workflowTaskService.reportBuildOutcome(buildOutcome(workItemId, context.runId, taskId, attempt, attempt.success
+                                    ? 'Workflow submitted and ready for verification.'
+                                    : (attempt.errors?.join(' ') ?? 'Workflow submission failed.')));
+                            },
+                        });
+                        const tracedBuilderTools = (0, tracing_utils_1.traceSubAgentTools)(context, builderTools, 'workflow-builder');
+                        const shouldUseBuilderMemory = activeBuilderSession
+                            ? await ensureBuilderMemoryThread(context, builderMemoryBinding)
+                            : false;
+                        const subAgent = new agent_1.Agent({
+                            id: subAgentId,
+                            name: 'Workflow Builder Agent',
+                            instructions: {
+                                role: 'system',
+                                content: prompt,
+                                providerOptions: {
+                                    anthropic: { cacheControl: { type: 'ephemeral' } },
+                                },
+                            },
+                            model: context.modelId,
+                            tools: tracedBuilderTools,
+                            workspace,
+                            memory: shouldUseBuilderMemory ? context.memory : undefined,
+                        });
+                        (0, langsmith_tracing_1.mergeTraceRunInputs)(traceContext?.actorRun, (0, langsmith_tracing_1.buildAgentTraceInputs)({
+                            systemPrompt: prompt,
+                            tools: tracedBuilderTools,
+                            modelId: context.modelId,
+                        }));
+                        (0, register_with_mastra_1.registerWithMastra)(subAgentId, subAgent, context.storage);
+                        const traceParent = (0, langsmith_tracing_1.getTraceParentRun)();
+                        let finalText;
                         try {
-                            const json = await domainContext.workflowService.getAsWorkflowJSON(workflowId);
-                            let rawCode = (0, workflow_sdk_1.generateWorkflowCode)(json);
-                            rawCode = rawCode.replace(/newCredential\('([^']*)',\s*'[^']*'\)/g, "newCredential('$1')");
-                            const code = `${extract_code_1.SDK_IMPORT_STATEMENT}\n\n${rawCode}`;
-                            if (workspace.filesystem) {
-                                await workspace.filesystem.writeFile(`${root}/src/workflow.ts`, code, {
-                                    recursive: true,
+                            const hitlResult = await (0, langsmith_tracing_1.withTraceParentContext)(traceParent, async () => {
+                                const llmStepTraceHooks = (0, resumable_stream_executor_1.createLlmStepTraceHooks)(traceParent);
+                                const resumeOptions = {
+                                    modelSettings: { temperature: model_settings_1.TEMPERATURE.BUILDER },
+                                    providerOptions: {
+                                        anthropic: { cacheControl: { type: 'ephemeral' } },
+                                    },
+                                    ...(shouldUseBuilderMemory
+                                        ? { memory: builderMemoryBinding, savePerStep: true }
+                                        : {}),
+                                };
+                                const stream = await subAgent.stream(briefing, {
+                                    maxSteps: max_steps_1.MAX_STEPS.BUILDER,
+                                    abortSignal: signal,
+                                    modelSettings: { temperature: model_settings_1.TEMPERATURE.BUILDER },
+                                    providerOptions: {
+                                        anthropic: { cacheControl: { type: 'ephemeral' } },
+                                    },
+                                    ...(shouldUseBuilderMemory
+                                        ? { memory: builderMemoryBinding, savePerStep: true }
+                                        : {}),
+                                    ...(llmStepTraceHooks?.executionOptions ?? {}),
+                                });
+                                return await (0, consume_with_hitl_1.consumeStreamWithHitl)({
+                                    agent: subAgent,
+                                    stream: stream,
+                                    runId: context.runId,
+                                    agentId: subAgentId,
+                                    eventBus: context.eventBus,
+                                    logger: context.logger,
+                                    threadId: context.threadId,
+                                    abortSignal: signal,
+                                    waitForConfirmation: context.waitForConfirmation,
+                                    drainCorrections,
+                                    waitForCorrection,
+                                    llmStepTraceHooks,
+                                    maxSteps: max_steps_1.MAX_STEPS.BUILDER,
+                                    resumeOptions,
                                 });
+                            });
+                            finalText = await hitlResult.text;
+                        }
+                        catch (error) {
+                            const recovered = resultFromPostStreamError({
+                                error,
+                                submitAttempts: submitAttemptHistory,
+                                mainWorkflowPath,
+                                workItemId,
+                                runId: context.runId,
+                                taskId,
+                            });
+                            if (recovered) {
+                                await promoteMainWorkflow(domainContext, context.logger, recovered.outcome.workflowId);
+                                return await finalizeBuildResult(context, workItemId, recovered);
                             }
+                            throw error;
                         }
-                        catch {
+                        const mainWorkflowAttempt = submitAttempts.get(mainWorkflowPath);
+                        const currentMainWorkflow = await (0, sandbox_fs_1.readFileViaSandbox)(workspace, mainWorkflowPath);
+                        const currentMainWorkflowHash = hashContent(currentMainWorkflow);
+                        if (!mainWorkflowAttempt) {
+                            const text = 'Error: workflow builder finished without submitting /src/workflow.ts.';
+                            return {
+                                text,
+                                outcome: buildOutcome(workItemId, context.runId, taskId, undefined, text),
+                            };
                         }
-                    }
-                    const mainWorkflowPath = `${root}/src/workflow.ts`;
-                    builderTools['submit-workflow'] = (0, submit_workflow_tool_1.createSubmitWorkflowTool)(domainContext, workspace, credMap, async (attempt) => {
-                        submitAttempts.set(attempt.filePath, attempt);
-                        submitAttemptHistory.push(attempt);
-                        if (attempt.filePath !== mainWorkflowPath || !context.workflowTaskService) {
-                            return;
+                        if (!mainWorkflowAttempt.success) {
+                            const recovered = resultFromLaterFailedMainSubmit({
+                                failedAttempt: mainWorkflowAttempt,
+                                submitAttempts: submitAttemptHistory,
+                                mainWorkflowPath,
+                                workItemId,
+                                runId: context.runId,
+                                taskId,
+                            });
+                            if (recovered) {
+                                await promoteMainWorkflow(domainContext, context.logger, recovered.outcome.workflowId);
+                                return await finalizeBuildResult(context, workItemId, recovered);
+                            }
+                            const errorText = mainWorkflowAttempt.errors?.join(' ') ?? 'Unknown submit-workflow failure.';
+                            const text = `Error: workflow builder stopped after a failed submit-workflow for /src/workflow.ts. ${errorText}`;
+                            return {
+                                text,
+                                outcome: buildOutcome(workItemId, context.runId, taskId, mainWorkflowAttempt, text),
+                            };
+                        }
+                        if (mainWorkflowAttempt.sourceHash !== currentMainWorkflowHash) {
+                            const submitTool = tracedBuilderTools['submit-workflow'];
+                            if (submitTool && 'execute' in submitTool) {
+                                const resubmit = await submitTool.execute({
+                                    filePath: mainWorkflowPath,
+                                    workflowId: mainWorkflowAttempt.workflowId,
+                                });
+                                const refreshedAttempt = attemptFromAutoResubmit({
+                                    latestAttempt: submitAttempts.get(mainWorkflowPath),
+                                    resubmit,
+                                    filePath: mainWorkflowPath,
+                                    sourceHash: currentMainWorkflowHash,
+                                });
+                                if (resubmit.success && refreshedAttempt?.success) {
+                                    await promoteMainWorkflow(domainContext, context.logger, refreshedAttempt.workflowId);
+                                    await compactSuccessfulBuilderMemory({
+                                        context,
+                                        binding: builderMemoryBinding,
+                                        activeBuilderSession,
+                                        domainContext,
+                                        workflowId: refreshedAttempt.workflowId,
+                                        workItemId,
+                                        mainWorkflowPath,
+                                        mainWorkflowAttempt: refreshedAttempt,
+                                        lastRequestedChange: input.task,
+                                        finalText,
+                                        shouldUseBuilderMemory,
+                                    });
+                                    const outcome = await buildOutcomeWithLatestVerification(context, workItemId, taskId, refreshedAttempt, finalText);
+                                    return {
+                                        text: finalText,
+                                        outcome,
+                                    };
+                                }
+                                const resubmitErrors = refreshedAttempt?.errors?.join(' ') ??
+                                    formatSubmitWorkflowErrors(resubmit, 'Auto-re-submit failed.');
+                                if (refreshedAttempt &&
+                                    !refreshedAttempt.success &&
+                                    shouldRecoverSavedWorkflowAfterFailedSubmit(refreshedAttempt)) {
+                                    const recovered = resultFromLaterFailedMainSubmit({
+                                        failedAttempt: refreshedAttempt,
+                                        submitAttempts: submitAttemptHistory,
+                                        mainWorkflowPath,
+                                        workItemId,
+                                        runId: context.runId,
+                                        taskId,
+                                    });
+                                    if (recovered) {
+                                        await promoteMainWorkflow(domainContext, context.logger, recovered.outcome.workflowId);
+                                        return await finalizeBuildResult(context, workItemId, recovered);
+                                    }
+                                }
+                                const text = `Error: auto-re-submit of edited /src/workflow.ts failed. ${resubmitErrors}`;
+                                return {
+                                    text,
+                                    outcome: buildOutcome(workItemId, context.runId, taskId, refreshedAttempt ?? undefined, text),
+                                };
+                            }
                         }
-                        await context.workflowTaskService.reportBuildOutcome(buildOutcome(workItemId, taskId, attempt, attempt.success
-                            ? 'Workflow submitted and ready for verification.'
-                            : (attempt.errors?.join(' ') ?? 'Workflow submission failed.')));
+                        await promoteMainWorkflow(domainContext, context.logger, mainWorkflowAttempt.workflowId);
+                        await compactSuccessfulBuilderMemory({
+                            context,
+                            binding: builderMemoryBinding,
+                            activeBuilderSession,
+                            domainContext,
+                            workflowId: mainWorkflowAttempt.workflowId,
+                            workItemId,
+                            mainWorkflowPath,
+                            mainWorkflowAttempt,
+                            lastRequestedChange: input.task,
+                            finalText,
+                            shouldUseBuilderMemory,
+                        });
+                        const outcome = await buildOutcomeWithLatestVerification(context, workItemId, taskId, mainWorkflowAttempt, finalText);
+                        return {
+                            text: finalText,
+                            outcome,
+                        };
+                    }
+                    let fallbackMainWorkflowId;
+                    recordSuccessfulWorkflowBuilds(builderTools['build-workflow'], (workflowId) => {
+                        fallbackMainWorkflowId = workflowId;
                     });
                     const tracedBuilderTools = (0, tracing_utils_1.traceSubAgentTools)(context, builderTools, 'workflow-builder');
                     const subAgent = new agent_1.Agent({
@@ -326,7 +837,6 @@ async function startBuildWorkflowAgentTask(context, input) {
                         },
                         model: context.modelId,
                         tools: tracedBuilderTools,
-                        workspace,
                     });
                     (0, langsmith_tracing_1.mergeTraceRunInputs)(traceContext?.actorRun, (0, langsmith_tracing_1.buildAgentTraceInputs)({
                         systemPrompt: prompt,
@@ -335,155 +845,110 @@ async function startBuildWorkflowAgentTask(context, input) {
                     }));
                     (0, register_with_mastra_1.registerWithMastra)(subAgentId, subAgent, context.storage);
                     const traceParent = (0, langsmith_tracing_1.getTraceParentRun)();
-                    let finalText;
-                    try {
-                        const hitlResult = await (0, langsmith_tracing_1.withTraceParentContext)(traceParent, async () => {
-                            const llmStepTraceHooks = (0, resumable_stream_executor_1.createLlmStepTraceHooks)(traceParent);
-                            const stream = await subAgent.stream(briefing, {
-                                maxSteps: max_steps_1.MAX_STEPS.BUILDER,
-                                abortSignal: signal,
-                                providerOptions: {
-                                    anthropic: { cacheControl: { type: 'ephemeral' } },
-                                },
-                                ...(llmStepTraceHooks?.executionOptions ?? {}),
-                            });
-                            return await (0, consume_with_hitl_1.consumeStreamWithHitl)({
-                                agent: subAgent,
-                                stream: stream,
-                                runId: context.runId,
-                                agentId: subAgentId,
-                                eventBus: context.eventBus,
-                                logger: context.logger,
-                                threadId: context.threadId,
-                                abortSignal: signal,
-                                waitForConfirmation: context.waitForConfirmation,
-                                drainCorrections,
-                                waitForCorrection,
-                                llmStepTraceHooks,
-                            });
+                    const hitlResult = await (0, langsmith_tracing_1.withTraceParentContext)(traceParent, async () => {
+                        const llmStepTraceHooks = (0, resumable_stream_executor_1.createLlmStepTraceHooks)(traceParent);
+                        const resumeOptions = {
+                            modelSettings: { temperature: model_settings_1.TEMPERATURE.BUILDER },
+                            providerOptions: {
+                                anthropic: { cacheControl: { type: 'ephemeral' } },
+                            },
+                        };
+                        const stream = await subAgent.stream(briefing, {
+                            maxSteps: max_steps_1.MAX_STEPS.BUILDER,
+                            abortSignal: signal,
+                            modelSettings: { temperature: model_settings_1.TEMPERATURE.BUILDER },
+                            providerOptions: {
+                                anthropic: { cacheControl: { type: 'ephemeral' } },
+                            },
+                            ...(llmStepTraceHooks?.executionOptions ?? {}),
                         });
-                        finalText = await hitlResult.text;
-                    }
-                    catch (error) {
-                        const recovered = resultFromPostStreamError({
-                            error,
-                            submitAttempts: submitAttemptHistory,
-                            mainWorkflowPath,
-                            workItemId,
-                            taskId,
+                        return await (0, consume_with_hitl_1.consumeStreamWithHitl)({
+                            agent: subAgent,
+                            stream: stream,
+                            runId: context.runId,
+                            agentId: subAgentId,
+                            eventBus: context.eventBus,
+                            logger: context.logger,
+                            threadId: context.threadId,
+                            abortSignal: signal,
+                            waitForConfirmation: context.waitForConfirmation,
+                            drainCorrections,
+                            waitForCorrection,
+                            llmStepTraceHooks,
+                            maxSteps: max_steps_1.MAX_STEPS.BUILDER,
+                            resumeOptions,
+                        });
+                    });
+                    const toolFinalText = await hitlResult.text;
+                    await promoteMainWorkflow(domainContext, context.logger, fallbackMainWorkflowId);
+                    return { text: toolFinalText };
+                }
+                finally {
+                    if (activeBuilderSession && context.builderSandboxSessionRegistry) {
+                        await context.builderSandboxSessionRegistry.release(activeBuilderSession.sessionId, {
+                            keep: !signal.aborted,
+                            reason: signal.aborted ? 'aborted' : 'builder_run_finished',
                         });
-                        if (recovered)
-                            return recovered;
-                        throw error;
-                    }
-                    const mainWorkflowAttempt = submitAttempts.get(mainWorkflowPath);
-                    const currentMainWorkflow = await (0, sandbox_fs_1.readFileViaSandbox)(workspace, mainWorkflowPath);
-                    const currentMainWorkflowHash = hashContent(currentMainWorkflow);
-                    if (!mainWorkflowAttempt) {
-                        const text = 'Error: workflow builder finished without submitting /src/workflow.ts.';
-                        return {
-                            text,
-                            outcome: buildOutcome(workItemId, taskId, undefined, text),
-                        };
-                    }
-                    if (!mainWorkflowAttempt.success) {
-                        const errorText = mainWorkflowAttempt.errors?.join(' ') ?? 'Unknown submit-workflow failure.';
-                        const text = `Error: workflow builder stopped after a failed submit-workflow for /src/workflow.ts. ${errorText}`;
-                        return {
-                            text,
-                            outcome: buildOutcome(workItemId, taskId, mainWorkflowAttempt, text),
-                        };
                     }
-                    if (mainWorkflowAttempt.sourceHash !== currentMainWorkflowHash) {
-                        const submitTool = tracedBuilderTools['submit-workflow'];
-                        if (submitTool && 'execute' in submitTool) {
-                            const resubmit = await submitTool.execute({
-                                filePath: mainWorkflowPath,
-                                workflowId: mainWorkflowAttempt.workflowId,
-                            });
-                            const refreshedAttempt = submitAttempts.get(mainWorkflowPath);
-                            if (refreshedAttempt?.success) {
-                                await promoteMainWorkflow(domainContext, context.logger, refreshedAttempt.workflowId);
-                                return {
-                                    text: finalText,
-                                    outcome: buildOutcome(workItemId, taskId, refreshedAttempt, finalText),
-                                };
-                            }
-                            const resubmitErrors = refreshedAttempt?.errors?.join(' ') ??
-                                (typeof resubmit?.errors === 'string'
-                                    ? resubmit.errors
-                                    : 'Auto-re-submit failed.');
-                            const text = `Error: auto-re-submit of edited /src/workflow.ts failed. ${resubmitErrors}`;
-                            return {
-                                text,
-                                outcome: buildOutcome(workItemId, taskId, refreshedAttempt ?? undefined, text),
-                            };
-                        }
+                    else {
+                        await builderWs?.cleanup();
                     }
-                    await promoteMainWorkflow(domainContext, context.logger, mainWorkflowAttempt.workflowId);
-                    return {
-                        text: finalText,
-                        outcome: buildOutcome(workItemId, taskId, mainWorkflowAttempt, finalText),
-                    };
                 }
-                let fallbackMainWorkflowId;
-                recordSuccessfulWorkflowBuilds(builderTools['build-workflow'], (workflowId) => {
-                    fallbackMainWorkflowId = workflowId;
-                });
-                const tracedBuilderTools = (0, tracing_utils_1.traceSubAgentTools)(context, builderTools, 'workflow-builder');
-                const subAgent = new agent_1.Agent({
-                    id: subAgentId,
-                    name: 'Workflow Builder Agent',
-                    instructions: {
-                        role: 'system',
-                        content: prompt,
-                        providerOptions: {
-                            anthropic: { cacheControl: { type: 'ephemeral' } },
-                        },
-                    },
-                    model: context.modelId,
-                    tools: tracedBuilderTools,
-                });
-                (0, langsmith_tracing_1.mergeTraceRunInputs)(traceContext?.actorRun, (0, langsmith_tracing_1.buildAgentTraceInputs)({
-                    systemPrompt: prompt,
-                    tools: tracedBuilderTools,
-                    modelId: context.modelId,
-                }));
-                (0, register_with_mastra_1.registerWithMastra)(subAgentId, subAgent, context.storage);
-                const traceParent = (0, langsmith_tracing_1.getTraceParentRun)();
-                const hitlResult = await (0, langsmith_tracing_1.withTraceParentContext)(traceParent, async () => {
-                    const llmStepTraceHooks = (0, resumable_stream_executor_1.createLlmStepTraceHooks)(traceParent);
-                    const stream = await subAgent.stream(briefing, {
-                        maxSteps: max_steps_1.MAX_STEPS.BUILDER,
-                        abortSignal: signal,
-                        providerOptions: {
-                            anthropic: { cacheControl: { type: 'ephemeral' } },
-                        },
-                        ...(llmStepTraceHooks?.executionOptions ?? {}),
-                    });
-                    return await (0, consume_with_hitl_1.consumeStreamWithHitl)({
-                        agent: subAgent,
-                        stream: stream,
-                        runId: context.runId,
-                        agentId: subAgentId,
-                        eventBus: context.eventBus,
-                        logger: context.logger,
-                        threadId: context.threadId,
-                        abortSignal: signal,
-                        waitForConfirmation: context.waitForConfirmation,
-                        drainCorrections,
-                        waitForCorrection,
-                        llmStepTraceHooks,
-                    });
-                });
-                const toolFinalText = await hitlResult.text;
-                await promoteMainWorkflow(domainContext, context.logger, fallbackMainWorkflowId);
-                return { text: toolFinalText };
-            }
-            finally {
-                await builderWs?.cleanup();
-            }
-        }),
+            }),
+        });
+    }
+    catch (error) {
+        if (reusedBuilderSession) {
+            void context.builderSandboxSessionRegistry?.release(reusedBuilderSession.sessionId, {
+                keep: true,
+                reason: 'spawn_failed',
+            });
+        }
+        throw error;
+    }
+    if (spawnOutcome.status === 'duplicate') {
+        if (reusedBuilderSession) {
+            void context.builderSandboxSessionRegistry?.release(reusedBuilderSession.sessionId, {
+                keep: true,
+                reason: 'spawn_duplicate',
+            });
+        }
+        return {
+            result: `Workflow build already in progress (task: ${spawnOutcome.existing.taskId}). Acknowledge and wait for the planned-task-follow-up — do not dispatch again.`,
+            taskId: spawnOutcome.existing.taskId,
+            agentId: spawnOutcome.existing.agentId,
+        };
+    }
+    if (spawnOutcome.status === 'limit-reached') {
+        if (reusedBuilderSession) {
+            void context.builderSandboxSessionRegistry?.release(reusedBuilderSession.sessionId, {
+                keep: true,
+                reason: 'spawn_limit_reached',
+            });
+        }
+        return {
+            result: 'Could not start build: concurrent background-task limit reached. Wait for an existing task to finish and try again.',
+            taskId: '',
+            agentId: '',
+        };
+    }
+    context.eventBus.publish(context.threadId, {
+        type: 'agent-spawned',
+        runId: context.runId,
+        agentId: subAgentId,
+        payload: {
+            parentId: context.orchestratorAgentId,
+            role: 'workflow-builder',
+            tools: Object.keys(builderTools),
+            taskId,
+            kind: 'builder',
+            title: 'Building workflow',
+            subtitle: (0, display_utils_1.truncateLabel)(input.task),
+            goal: input.task,
+            targetResource: input.workflowId
+                ? { type: 'workflow', id: input.workflowId }
+                : { type: 'workflow' },
+        },
     });
     return {
         result: `Workflow build started (task: ${taskId}). Reply with one short sentence — e.g. name what's being built. Do NOT summarize the plan or list details.`,
@@ -503,19 +968,127 @@ exports.buildWorkflowAgentInputSchema = zod_1.z.object({
         .string()
         .optional()
         .describe('Brief summary of the conversation so far — what was discussed, decisions made, and information gathered (e.g., which credentials are available). The builder uses this to avoid repeating information the user already knows.'),
+    workItemId: zod_1.z
+        .string()
+        .optional()
+        .describe('Workflow-loop work item ID. Required for repair builds so remediation budgets continue on the same work item.'),
+    bypassPlan: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Set to true for any edit to an existing workflow — adding/removing/rewiring a node, changing an expression, swapping a credential, changing a schedule, fixing a Code node. Requires an existing `workflowId` and a one-sentence `reason`. The orchestrator verifies the result afterwards via `verify-built-workflow` when the trigger is mockable. ' +
+        'A runtime guard rejects direct calls without `bypassPlan: true` outside replan/checkpoint follow-ups: new workflow builds, multi-workflow work, and data-table schema changes must go through `plan` so the build gets its orchestrator-run checkpoint.'),
+    reason: zod_1.z
+        .string()
+        .optional()
+        .describe('One sentence explaining why the planner is being bypassed (e.g. "swap Slack channel on workflow X", "fix Code node shape issue"). Required when bypassPlan is true.'),
+});
+const buildWorkflowAgentSuspendSchema = zod_1.z.object({
+    requestId: zod_1.z.string(),
+    message: zod_1.z.string(),
+    severity: zod_1.z.literal('warning'),
+});
+const buildWorkflowAgentResumeSchema = zod_1.z.object({
+    approved: zod_1.z.boolean(),
 });
+function isPostPlanFollowUp(context) {
+    return context.isReplanFollowUp === true || context.isCheckpointFollowUp === true;
+}
+function isBuildViaPlanGuardEnabled() {
+    const raw = process.env.N8N_INSTANCE_AI_ENFORCE_BUILD_VIA_PLAN;
+    if (raw === undefined)
+        return true;
+    return raw.toLowerCase() !== 'false' && raw !== '0';
+}
+async function resolveWorkflowNameForEditConfirmation(context, workflowId) {
+    try {
+        const workflow = await context.domainContext?.workflowService.get(workflowId);
+        const workflowName = workflow?.name?.trim();
+        return workflowName && workflowName.length > 0 ? workflowName : workflowId;
+    }
+    catch {
+        return workflowId;
+    }
+}
 function createBuildWorkflowAgentTool(context) {
     return (0, tools_1.createTool)({
         id: 'build-workflow-with-agent',
         description: 'Build or modify an n8n workflow using a specialized builder agent. ' +
-            'The agent handles node discovery, schema lookups, code generation, ' +
-            'and validation internally.',
+            'The agent handles node discovery, schema lookups, code generation, and validation internally. ' +
+            'For edits to an existing workflow, call directly with `bypassPlan: true`, the existing `workflowId`, and a one-sentence `reason` — the orchestrator runs a lightweight verify afterwards. ' +
+            'For new workflows, multi-workflow builds, or data-table schema changes, go through `plan` — ' +
+            'a runtime guard rejects direct calls without `bypassPlan: true` outside replan/checkpoint follow-ups, because those paths need the orchestrator-run checkpoint for end-to-end verification.',
         inputSchema: exports.buildWorkflowAgentInputSchema,
         outputSchema: zod_1.z.object({
             result: zod_1.z.string(),
             taskId: zod_1.z.string(),
         }),
-        execute: async (input) => {
+        suspendSchema: buildWorkflowAgentSuspendSchema,
+        resumeSchema: buildWorkflowAgentResumeSchema,
+        execute: async (input, ctx) => {
+            const isPostPlanFollowUpRun = isPostPlanFollowUp(context);
+            if (isBuildViaPlanGuardEnabled() && !isPostPlanFollowUpRun) {
+                if (!input.bypassPlan) {
+                    context.logger.warn('build-workflow-with-agent called outside plan/replan context — rejecting', {
+                        threadId: context.threadId,
+                        hasWorkflowId: Boolean(input.workflowId),
+                    });
+                    return {
+                        result: 'Error: direct builder calls require `bypassPlan: true` + an existing ' +
+                            '`workflowId` + a one-sentence `reason`. Use that combination for any edit to ' +
+                            'an existing workflow. For new workflows, multi-workflow builds, or data-table ' +
+                            'schema changes, call `plan` with a `build-workflow` task instead — the planner ' +
+                            'discovers credentials, data tables, and best practices, and schedules an ' +
+                            'orchestrator-run verification checkpoint.',
+                        taskId: '',
+                    };
+                }
+                if (!input.workflowId) {
+                    return {
+                        result: 'Error: `bypassPlan: true` is for edits to an EXISTING workflow and requires a ' +
+                            '`workflowId`. New workflow builds must go through `plan` so an orchestrator-run ' +
+                            'verification checkpoint is scheduled. Call `plan` with a `build-workflow` task ' +
+                            'instead.',
+                        taskId: '',
+                    };
+                }
+                if (!input.reason || input.reason.trim().length === 0) {
+                    return {
+                        result: 'Error: `bypassPlan: true` requires a one-sentence `reason` describing the edit ' +
+                            '(e.g. "swap Slack channel", "fix Code node shape issue").',
+                        taskId: '',
+                    };
+                }
+                context.logger.warn('build-workflow-with-agent bypassing plan with bypassPlan=true', {
+                    threadId: context.threadId,
+                    workflowId: input.workflowId,
+                    reason: input.reason,
+                });
+            }
+            if (input.workflowId && !isPostPlanFollowUpRun && context.domainContext) {
+                const updateWorkflowPermission = context.domainContext.permissions?.updateWorkflow ?? 'require_approval';
+                if (updateWorkflowPermission === 'blocked') {
+                    return { result: 'Action blocked by admin', taskId: '' };
+                }
+                const isOwnInFlightWorkflow = context.domainContext.aiCreatedWorkflowIds?.has(input.workflowId) ?? false;
+                if (!isOwnInFlightWorkflow) {
+                    const resumeData = ctx?.agent?.resumeData;
+                    const suspend = ctx?.agent?.suspend;
+                    const needsApproval = updateWorkflowPermission !== 'always_allow';
+                    if (needsApproval && (resumeData === undefined || resumeData === null)) {
+                        const workflowName = await resolveWorkflowNameForEditConfirmation(context, input.workflowId);
+                        const reason = input.reason?.trim();
+                        await suspend?.({
+                            requestId: (0, nanoid_1.nanoid)(),
+                            message: `Edit existing workflow "${workflowName}" (ID: ${input.workflowId})?${reason ? ` Reason: ${reason}` : ''}`,
+                            severity: 'warning',
+                        });
+                        return { result: '', taskId: '' };
+                    }
+                    if (resumeData !== undefined && resumeData !== null && !resumeData.approved) {
+                        return { result: 'User declined the workflow edit.', taskId: '' };
+                    }
+                }
+            }
             const result = await startBuildWorkflowAgentTask(context, input);
             return { result: result.result, taskId: result.taskId };
         },