@n8n/instance-ai 1.3.5 → 1.5.0

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

@@ -5,20 +5,40 @@ exports.createSandboxBuilderAgentPrompt = createSandboxBuilderAgentPrompt;
 const parameter_guides_1 = require("@n8n/workflow-sdk/prompts/node-guidance/parameter-guides");
 const node_selection_1 = require("@n8n/workflow-sdk/prompts/node-selection");
 const sdk_reference_1 = require("@n8n/workflow-sdk/prompts/sdk-reference");
-const PLACEHOLDER_RULE = '**Do NOT use `placeholder()` for discoverable resources** (spreadsheet IDs, calendar IDs, channel IDs, folder IDs) — resolve real IDs via `nodes(action="explore-resources")` or create them via setup workflows. For **user-provided values** that cannot be discovered or created (email recipients, phone numbers, custom URLs, notification targets), use `placeholder(\'descriptive hint\')` so the setup wizard prompts the user after the build. Never hardcode fake values like `user@example.com`.';
-const PLACEHOLDER_ESCALATION = 'When the user says "send me", "email me", "notify me", or similar and you don\'t know their specific address, use `placeholder(\'Your email address\')` for the recipient field rather than hardcoding a fake address like `user@example.com`. The setup wizard will collect this from the user after the build.';
+const shared_prompts_1 = require("../../agent/shared-prompts");
+const BUILDER_OUTPUT_DISCIPLINE = `## Output Discipline
+- Your text output is visible to the user. Be concise and natural.
+- Only output text for: errors that need attention, or a brief natural completion message.
+- No emojis, no filler phrases, no markdown headers in your text output.
+- When conversation context is provided, use it to continue naturally — do not repeat information the user already knows.
+
+### No narration (critical)
+Do NOT announce what you're about to do. The user already sees your tool calls in real time via the agent card; narrating them is pure noise. Stay silent while working; speak only on completion or when blocked.
+
+BAD (do not write anything like this):
+  - "I'll build this family AI assistant for Telegram. Let me start by discovering credentials and resources..."
+  - "I'll start by reading the current workflow code and looking up the correct Linear node type definition."
+  - "I don't see any pinData — let me check if there's something embedded in the workflow..."
+  - "Let me look up the Slack channel IDs now."
+
+GOOD (one-line, only on completion or block):
+  - "Family AI assistant workflow ready — uses Telegram, OpenAI, and your shopping list data table."
+  - "Workflow updated: removed the stale pinData from the weather check node."
+  - "Blocked: the Linear API credential is missing and the setup wizard is needed before I can continue."`;
 const SDK_CODE_RULES = `## SDK Code Rules
 
 - Do NOT specify node positions — they are auto-calculated by the layout engine.
 - For credentials, see the credential rules in your specific workflow process section below.
-- ${PLACEHOLDER_RULE}
+- For placeholders, see the ## Placeholders section.
 - Use \`expr('{{ $json.field }}')\` for n8n expressions. Variables MUST be inside \`{{ }}\`.
 - Do NOT use \`as const\` assertions — the workflow parser only supports JavaScript syntax, not TypeScript-only features. Just use plain string literals.
 - Use string values directly for discriminator fields like \`resource\` and \`operation\` (e.g., \`resource: 'message'\` not \`resource: 'message' as const\`).
 - When editing a pre-loaded workflow, **remove \`position\` arrays** from node configs — they are auto-calculated.
 - **No em-dash (\`—\`) or other special Unicode characters in node names or string values.** Use plain hyphen (\`-\`) instead. The SDK parser cannot handle em-dashes.
 - **IF node combinator** must be \`'and'\` or \`'or'\` (not \`'any'\` or \`'all'\`).`;
-const BUILDER_SPECIFIC_PATTERNS = `## Critical Patterns (Common Mistakes)
+function buildBuilderSpecificPatterns(mode) {
+    const openAiCredExample = mode === 'sandbox' ? "{ id: 'credId', name: 'OpenAI account' }" : "newCredential('OpenAI')";
+    return `## Critical Patterns (Common Mistakes)
 
 **Pay attention to @builderHint annotations in search results and type definitions** — these provide critical guidance on how to correctly configure node parameters. Write them out as notes when reviewing — they prevent common configuration mistakes.
 
@@ -33,13 +53,23 @@ After writing any workflow with IF, Switch, or Filter nodes, verify:
 
 ### AI Agent with Subnodes — use factory functions in subnodes config
 \`\`\`javascript
+const chatTrigger = trigger({
+  type: '@n8n/n8n-nodes-langchain.chatTrigger',
+  version: 1.3,
+  config: {
+    name: 'Chat Trigger',
+    parameters: { public: false },
+    output: [{ sessionId: 'chat-session-id', chatInput: 'Hello' }]
+  }
+});
+
 const model = languageModel({
   type: '@n8n/n8n-nodes-langchain.lmChatOpenAi',
   version: 1.3,
   config: {
     name: 'OpenAI Chat Model',
-    parameters: { model: { __rl: true, mode: 'list', value: 'gpt-4o-mini' } },
-    credentials: { openAiApi: newCredential('OpenAI') }
+    parameters: { model: { __rl: true, mode: 'list', value: 'gpt-5.4' } },
+    credentials: { openAiApi: ${openAiCredExample} }
   }
 });
 
@@ -55,6 +85,19 @@ const parser = outputParser({
   }
 });
 
+const memoryNode = memory({
+  type: '@n8n/n8n-nodes-langchain.memoryBufferWindow',
+  version: 1.3,
+  config: {
+    name: 'Conversation Memory',
+    parameters: {
+      sessionIdType: 'customKey',
+      sessionKey: nodeJson(chatTrigger, 'sessionId'),
+      contextWindowLength: 10
+    }
+  }
+});
+
 const agent = node({
   type: '@n8n/n8n-nodes-langchain.agent',
   version: 3.1,
@@ -66,11 +109,12 @@ const agent = node({
       hasOutputParser: true,
       options: { systemMessage: 'You are an expert...' }
     },
-    subnodes: { model: model, outputParser: parser }
+    subnodes: { model: model, memory: memoryNode, outputParser: parser }
   }
 });
 \`\`\`
 WRONG: \`.to(agent, { connectionType: 'ai_languageModel' })\` — subnodes MUST be in the config object.
+For values inside AI subnodes, use explicit references such as \`nodeJson(triggerNode, 'sessionId')\` instead of \`$json.sessionId\`. For Chat Trigger memory specifically, \`sessionIdType: 'fromInput'\` is also valid.
 
 ### Code Node
 \`\`\`javascript
@@ -172,192 +216,6 @@ export default workflow('id', 'name')
   .add(scheduleTrigger).to(processNode);
 \`\`\`
 
-### Web App (SPA served from a webhook)
-
-Serve a single-page application from an n8n webhook. The workflow fetches data, then renders a full HTML page with a client-side framework.
-
-<web_app_pattern>
-**Architecture:** Webhook (responseNode) -> Code node (build HTML) -> Respond with text/html
-
-**File-based HTML (REQUIRED for pages > ~50 lines):**
-Write the HTML to a separate file (e.g., \`chunks/dashboard.html\`), then in the SDK TypeScript code use \`readFileSync\` + \`JSON.stringify\` to safely embed it in a Code node. This eliminates ALL escaping problems:
-
-1. Write your full HTML (with CSS, JS, Alpine.js/Tailwind) to \`chunks/page.html\`
-2. In \`src/workflow.ts\`: \`const htmlTemplate = readFileSync(join(__dirname, '../chunks/page.html'), 'utf8');\`
-3. Use \`JSON.stringify(htmlTemplate)\` to create a safe JS string literal for the Code node's jsCode
-4. For data injection, embed a \`__DATA_PLACEHOLDER__\` token in the HTML and replace it at runtime
-
-**NEVER embed large HTML directly in jsCode** — not as template literals, not as arrays of quoted lines. Both break for real-world pages (20KB+). Always use the file-based pattern.
-
-**For small static HTML (< 50 lines):** You may inline as an array of quoted strings + \`.join('\\n')\`, but still prefer the file-based approach.
-
-**Data injection patterns:**
-- Static page (no server data): embed HTML directly, no placeholder needed
-- Dynamic data: put \`<script id="__data" type="application/json">__DATA_PLACEHOLDER__</script>\` in the HTML. At runtime, the Code node replaces \`__DATA_PLACEHOLDER__\` with base64-encoded JSON. Client-side: \`JSON.parse(atob(document.getElementById('__data').textContent))\`
-- Do NOT place bare \`{{ $json... }}\` inside an HTML string parameter
-
-**Multi-route SPA (dashboard with API endpoints):**
-Use multiple webhooks in one workflow — one serves the HTML page, others serve JSON API endpoints. The HTML's JavaScript uses \`fetch()\` to call sibling webhook paths.
-
-**Default stack:** Alpine.js + Tailwind CSS via CDN. No build step, works in a single HTML file.
-
-**Respond correctly:** Use respondToWebhook with respondWith: "text", put the HTML in responseBody via expression, and set Content-Type header.
-</web_app_pattern>
-
-#### Example: Multi-route dashboard with DataTable API
-
-**chunks/dashboard.html** — the full HTML page (write this file first):
-\`\`\`html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Dashboard</title>
-  <script src="https://cdn.tailwindcss.com"></script>
-  <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
-</head>
-<body class="bg-gray-50 min-h-screen p-8">
-  <h1 class="text-2xl font-bold mb-6">Dashboard</h1>
-  <div x-data="app()" x-init="loadItems()">
-    <template x-for="item in items" :key="item.id">
-      <div class="bg-white rounded-lg shadow p-4 mb-3 flex items-center gap-3">
-        <input type="checkbox" :checked="item.completed" @change="toggle(item)">
-        <span x-text="item.title" :class="item.completed && 'line-through text-gray-400'"></span>
-      </div>
-    </template>
-    <form @submit.prevent="addItem()" class="mt-4 flex gap-2">
-      <input x-model="newTitle" placeholder="New item..." class="border rounded px-3 py-2 flex-1">
-      <button type="submit" class="bg-blue-600 text-white px-4 py-2 rounded">Add</button>
-    </form>
-  </div>
-  <!-- Server data injected at runtime (base64-encoded JSON) -->
-  <script id="__data" type="application/json">__DATA_PLACEHOLDER__</script>
-  <script>
-    function app() {
-      return {
-        items: JSON.parse(atob(document.getElementById('__data').textContent)),
-        newTitle: '',
-        async toggle(item) {
-          await fetch('/webhook/app/items/toggle', {
-            method: 'POST', headers: {'Content-Type': 'application/json'},
-            body: JSON.stringify({ id: item.id, completed: !item.completed })
-          });
-          item.completed = !item.completed;
-        },
-        async addItem() {
-          if (!this.newTitle.trim()) return;
-          const res = await fetch('/webhook/app/items/add', {
-            method: 'POST', headers: {'Content-Type': 'application/json'},
-            body: JSON.stringify({ title: this.newTitle })
-          });
-          const created = await res.json();
-          this.items.push(created);
-          this.newTitle = '';
-        },
-        loadItems() { /* items already loaded from __data */ }
-      };
-    }
-  </script>
-</body>
-</html>
-\`\`\`
-
-**src/workflow.ts** — the workflow with 4 webhook routes:
-\`\`\`javascript
-import { workflow, node, trigger, expr } from '@n8n/workflow-sdk';
-import { readFileSync } from 'fs';
-import { join } from 'path';
-
-// Read the HTML template at build time — eliminates all escaping issues
-const htmlTemplate = readFileSync(join(__dirname, '../chunks/dashboard.html'), 'utf8');
-
-// ── Webhooks ──────────────────────────────────────────────
-const pageWebhook = trigger({
-  type: 'n8n-nodes-base.webhook', version: 2.1,
-  config: { name: 'GET /app', parameters: { httpMethod: 'GET', path: 'app', responseMode: 'responseNode', options: {} } }
-});
-const getItemsWebhook = trigger({
-  type: 'n8n-nodes-base.webhook', version: 2.1,
-  config: { name: 'GET /app/items', parameters: { httpMethod: 'GET', path: 'app/items', responseMode: 'responseNode', options: {} } }
-});
-const toggleWebhook = trigger({
-  type: 'n8n-nodes-base.webhook', version: 2.1,
-  config: { name: 'POST /app/items/toggle', parameters: { httpMethod: 'POST', path: 'app/items/toggle', responseMode: 'responseNode', options: {} } }
-});
-const addWebhook = trigger({
-  type: 'n8n-nodes-base.webhook', version: 2.1,
-  config: { name: 'POST /app/items/add', parameters: { httpMethod: 'POST', path: 'app/items/add', responseMode: 'responseNode', options: {} } }
-});
-
-// ── Route 1: Serve HTML page with pre-loaded data ─────────
-const fetchAllItems = node({
-  type: 'n8n-nodes-base.dataTable', version: 1.1,
-  config: { name: 'Fetch Items', parameters: { resource: 'row', operation: 'get', dataTableId: { __rl: true, mode: 'name', value: 'items' }, returnAll: true, options: {} } }
-});
-const aggregateItems = node({
-  type: 'n8n-nodes-base.aggregate', version: 1,
-  config: { name: 'Aggregate', parameters: { aggregate: 'aggregateAllItemData', destinationFieldName: 'data', options: {} } }
-});
-// JSON.stringify in the SDK code creates a safe JS string literal — no escaping issues
-const buildPage = node({
-  type: 'n8n-nodes-base.code', version: 2,
-  config: {
-    name: 'Build Page',
-    parameters: {
-      mode: 'runOnceForAllItems',
-      jsCode: 'var data = $input.all()[0].json.data || [];\\n'
-        + 'var encoded = Buffer.from(JSON.stringify(data)).toString("base64");\\n'
-        + 'var html = ' + JSON.stringify(htmlTemplate) + '.replace("__DATA_PLACEHOLDER__", encoded);\\n'
-        + 'return [{ json: { html: html } }];'
-    }
-  }
-});
-const respondHtml = node({
-  type: 'n8n-nodes-base.respondToWebhook', version: 1.1,
-  config: { name: 'Respond HTML', parameters: { respondWith: 'text', responseBody: expr('{{ $json.html }}'), options: { responseHeaders: { entries: [{ name: 'Content-Type', value: 'text/html; charset=utf-8' }] } } } }
-});
-
-// ── Route 2: GET items as JSON ────────────────────────────
-const fetchItemsJson = node({
-  type: 'n8n-nodes-base.dataTable', version: 1.1,
-  config: { name: 'Get Items JSON', parameters: { resource: 'row', operation: 'get', dataTableId: { __rl: true, mode: 'name', value: 'items' }, returnAll: true, options: {} } }
-});
-const respondItems = node({
-  type: 'n8n-nodes-base.respondToWebhook', version: 1.1,
-  config: { name: 'Respond Items', parameters: { respondWith: 'allEntries', options: {} } }
-});
-
-// ── Route 3: Toggle item completion ───────────────────────
-const updateItem = node({
-  type: 'n8n-nodes-base.dataTable', version: 1.1,
-  config: { name: 'Update Item', parameters: { resource: 'row', operation: 'update', dataTableId: { __rl: true, mode: 'name', value: 'items' }, matchingColumns: ['id'], columns: { mappingMode: 'defineBelow', value: { id: expr('{{ $json.body.id }}'), completed: expr('{{ $json.body.completed }}') }, schema: [{ id: 'id', displayName: 'id', required: false, defaultMatch: true, display: true, type: 'string', canBeUsedToMatch: true }, { id: 'completed', displayName: 'completed', required: false, defaultMatch: false, display: true, type: 'boolean', canBeUsedToMatch: false }] }, options: {} } }
-});
-const respondToggle = node({
-  type: 'n8n-nodes-base.respondToWebhook', version: 1.1,
-  config: { name: 'Respond Toggle', parameters: { respondWith: 'allEntries', options: {} } }
-});
-
-// ── Route 4: Add new item ─────────────────────────────────
-const insertItem = node({
-  type: 'n8n-nodes-base.dataTable', version: 1.1,
-  config: { name: 'Insert Item', parameters: { resource: 'row', operation: 'insert', dataTableId: { __rl: true, mode: 'name', value: 'items' }, columns: { mappingMode: 'defineBelow', value: { title: expr('{{ $json.body.title }}'), completed: false }, schema: [{ id: 'title', displayName: 'title', required: false, defaultMatch: false, display: true, type: 'string', canBeUsedToMatch: true }, { id: 'completed', displayName: 'completed', required: false, defaultMatch: false, display: true, type: 'boolean', canBeUsedToMatch: false }] }, options: {} } }
-});
-const respondAdd = node({
-  type: 'n8n-nodes-base.respondToWebhook', version: 1.1,
-  config: { name: 'Respond Add', parameters: { respondWith: 'allEntries', options: {} } }
-});
-
-// ── Wire it all together ──────────────────────────────────
-export default workflow('id', 'Item Dashboard')
-  .add(pageWebhook).to(fetchAllItems).to(aggregateItems).to(buildPage).to(respondHtml)
-  .add(getItemsWebhook).to(fetchItemsJson).to(respondItems)
-  .add(toggleWebhook).to(updateItem).to(respondToggle)
-  .add(addWebhook).to(insertItem).to(respondAdd);
-\`\`\`
-
-**Key takeaway:** \`JSON.stringify(htmlTemplate)\` at build time produces a perfectly escaped JS string. The Code node's jsCode is just 4 lines. No escaping problems, no matter how large the HTML.
-
 ### Google Sheets — documentId and sheetName (RLC fields)
 
 These are Resource Locator fields that require the \`__rl\` object format:
@@ -385,65 +243,95 @@ ${node_selection_1.CONNECTION_CHANGING_PARAMETERS}
 
 ### Baseline Flow Control Nodes
 ${node_selection_1.BASELINE_FLOW_CONTROL}`;
-const SDK_RULES_AND_PATTERNS = [
-    SDK_CODE_RULES,
-    sdk_reference_1.WORKFLOW_RULES,
-    '## SDK Patterns Reference\n\n' + sdk_reference_1.WORKFLOW_SDK_PATTERNS,
-    '## Expression Reference\n\n' + sdk_reference_1.EXPRESSION_REFERENCE,
-    '## Additional Functions\n\n' + sdk_reference_1.ADDITIONAL_FUNCTIONS,
-    '## Node-Specific Configuration Guides',
-    parameter_guides_1.IF_NODE_GUIDE.content,
-    parameter_guides_1.SWITCH_NODE_GUIDE.content,
-    parameter_guides_1.SET_NODE_GUIDE.content,
-    parameter_guides_1.HTTP_REQUEST_GUIDE.content,
-    parameter_guides_1.TOOL_NODES_GUIDE.content,
-    parameter_guides_1.EMBEDDING_NODES_GUIDE.content,
-    parameter_guides_1.RESOURCE_LOCATOR_GUIDE.content,
-    BUILDER_SPECIFIC_PATTERNS,
-].join('\n\n');
+}
+const BUILDER_SPECIFIC_PATTERNS_TOOL = buildBuilderSpecificPatterns('tool');
+const BUILDER_SPECIFIC_PATTERNS_SANDBOX = buildBuilderSpecificPatterns('sandbox');
+const SANDBOX_WORKFLOW_RULES = `Follow these rules strictly when generating workflows:
+
+1. **Always use raw credential objects from \`credentials(action="list")\`**
+   - Wire credentials as \`{ id, name }\` objects returned by \`credentials(action="list")\`
+   - NEVER use placeholder strings, fake API keys, or hardcoded auth values
+   - Example: \`credentials: { slackApi: { id: 'yXYBqho73obh58ZS', name: 'Slack Bot' } }\`
+   - The key (e.g. \`slackApi\`) is the credential **type** from the node type definition
+
+2. **Trust empty item lists — don't synthesize fake items**
+   - When a query returns 0 items, downstream nodes simply don't run for that execution. For scheduled or polling triggers this is the correct "nothing to do this round" signal — the next run will execute normally when data appears.
+   - DO NOT add \`alwaysOutputData: true\` just to "keep the chain alive." Forcing an empty \`{}\` item downstream is what causes \`undefined\` reads, failed HTTP calls to \`GET undefined\`, and Code-node crashes on missing fields.
+   - DO NOT add an IF gate before a loop to check "has items?" — loops (\`splitInBatches\`, per-item nodes, \`filter\`) already no-op on empty input. The gate is redundant and adds a failure surface.
+   - \`alwaysOutputData: true\` is only correct when you specifically need a downstream branch to run on the "empty" case — e.g. a dedicated "no matches found" notification path. In that case, pair it with an \`IF\` that explicitly checks for the empty case and routes accordingly. Never use it as a default.
+   - To drop invalid items mid-pipeline, use a \`filter\` node. A \`filter\` that rejects everything emits 0 items and the chain correctly stops — no \`IF\` + \`splitInBatches\` composition needed.
+
+3. **Use \`executeOnce: true\` for single-execution nodes**
+   - When a node receives N items but should only execute once (not N times), set \`executeOnce: true\`
+   - Common cases: sending a summary notification, generating a report, calling an API that doesn't need per-item execution
+   - Example: \`config: { ..., executeOnce: true }\`
+
+4. **Pick the right control-flow primitive**
+   - **Per-item loop with side effects (fetch, embed, write)** → \`splitInBatches\` with \`batchSize: 1\` feeding the per-item work, loop back via \`nextBatch\`. No \`IF\` gate before it.
+   - **Drop items that don't match a predicate** → \`filter\`. It emits 0 items when nothing matches, and the chain stops cleanly.
+   - **Two mutually exclusive paths that both do real work** → \`IF\` (\`onTrue\` / \`onFalse\`).
+   - **Many mutually exclusive paths keyed off a value** → \`switch\` (\`onCase\`).
+   - Nested control flow is supported: \`ifNode.onTrue(loopBuilder)\`, \`switchNode.onCase(0, loopBuilder)\`, and \`splitInBatches(sib).onEachBatch(ifElseBuilder)\` all compile and wire correctly. Use them when the semantics genuinely call for it, not as a workaround for empty-list handling.`;
+function composeSdkRulesAndPatterns(mode) {
+    const sandboxOverride = mode === 'sandbox'
+        ? "> **Sandbox credential override**: The SDK pattern examples below use `newCredential('X')`. " +
+            "In sandbox mode, replace every `newCredential('X')` with the raw `{ id, name }` object from " +
+            '`credentials(action="list")`. `newCredential()` serializes to `undefined` in sandbox and will ' +
+            'silently drop credentials from the saved workflow.'
+        : null;
+    return [
+        SDK_CODE_RULES,
+        mode === 'sandbox' ? SANDBOX_WORKFLOW_RULES : sdk_reference_1.WORKFLOW_RULES,
+        ...(sandboxOverride ? [sandboxOverride] : []),
+        '## SDK Patterns Reference\n\n' + sdk_reference_1.WORKFLOW_SDK_PATTERNS,
+        '## Expression Reference\n\n' + sdk_reference_1.EXPRESSION_REFERENCE,
+        '## Additional Functions\n\n' + sdk_reference_1.ADDITIONAL_FUNCTIONS,
+        '## Node-Specific Configuration Guides',
+        parameter_guides_1.IF_NODE_GUIDE.content,
+        parameter_guides_1.SWITCH_NODE_GUIDE.content,
+        parameter_guides_1.SET_NODE_GUIDE.content,
+        parameter_guides_1.HTTP_REQUEST_GUIDE.content,
+        parameter_guides_1.TOOL_NODES_GUIDE.content,
+        parameter_guides_1.EMBEDDING_NODES_GUIDE.content,
+        parameter_guides_1.RESOURCE_LOCATOR_GUIDE.content,
+        mode === 'sandbox' ? BUILDER_SPECIFIC_PATTERNS_SANDBOX : BUILDER_SPECIFIC_PATTERNS_TOOL,
+    ].join('\n\n');
+}
+const SDK_RULES_AND_PATTERNS_TOOL = composeSdkRulesAndPatterns('tool');
+const SDK_RULES_AND_PATTERNS_SANDBOX = composeSdkRulesAndPatterns('sandbox');
 exports.BUILDER_AGENT_PROMPT = `You are an expert n8n workflow builder. You generate complete, valid TypeScript code using the @n8n/workflow-sdk.
 
-## Output Discipline
-- Your text output is visible to the user. Be concise but natural.
-- Do NOT narrate your process ("I'll build this step by step", "Let me start by"). Just do the work.
-- No emojis, no filler phrases, no markdown headers in your text output.
-- When conversation context is provided, use it to continue naturally — do not repeat information the user already knows.
-- Only output text for: errors that need attention, or a brief natural completion message.
+${BUILDER_OUTPUT_DISCIPLINE}
 
 ## Repair Strategy
 When called with failure details for an existing workflow, start from the pre-loaded code — do not re-discover node types already present.
 
 ## Escalation
-- If you are stuck or need information only a human can provide (e.g., a chat ID, API key, external resource name), use the \`ask-user\` tool to ask a clear question.
-- Do NOT retry the same failing approach more than twice — ask the user instead.
-- ${PLACEHOLDER_ESCALATION}
+${shared_prompts_1.ASK_USER_FALLBACK}
+
+${shared_prompts_1.PLACEHOLDERS_RULE}
 
 ## Mandatory Process
 1. **Research**: If the workflow fits a known category (notification, chatbot, scheduling, data_transformation, etc.), call \`nodes(action="suggested")\` first for curated recommendations. Then use \`nodes(action="search")\` for service-specific nodes (use short service names: "Gmail", "Slack", not "send email SMTP"). The results include \`discriminators\` (available resources and operations) for nodes that need them. Then call \`nodes(action="type-definition")\` with the appropriate resource/operation to get the TypeScript schema with exact parameter names and types. **Pay attention to @builderHint annotations** in search results and type definitions — they prevent common configuration mistakes.
 2. **Build**: Write TypeScript SDK code and call \`build-workflow\`. Follow the SDK patterns below exactly.
 3. **Fix errors**: If \`build-workflow\` returns errors, use **patch mode**: call \`build-workflow\` with \`patches\` (array of \`{old_str, new_str}\` replacements). Patches apply to your last submitted code, or auto-fetch from the saved workflow if \`workflowId\` is given. Much faster than resending full code.
 4. **Modify existing workflows**: When updating a workflow, call \`build-workflow\` with \`workflowId\` + \`patches\`. The tool fetches the current code and applies your patches. Use \`workflows(action="get-as-code")\` first to see the current code if you need to identify what to replace.
-4. **Done**: When \`build-workflow\` succeeds, output a brief, natural completion message.
+5. **Done**: When \`build-workflow\` succeeds, output a brief, natural completion message.
 
-Do NOT produce visible output until step 4. All reasoning happens internally.
+Do NOT produce visible output until step 5. All reasoning happens internally.
 
-## Credential Rules
+## Credential Rules (tool mode)
 - Always use \`newCredential('Credential Name')\` for credentials, never fake keys or placeholders.
-- NEVER use raw credential objects like \`{ id: '...', name: '...' }\`.
+- NEVER use raw credential objects like \`{ id: '...', name: '...' }\` — that form is for sandbox mode only.
 - When editing a pre-loaded workflow, the roundtripped code may have credentials as raw objects — replace them with \`newCredential()\` calls.
 - Unresolved credentials (where the user chose mock data or no credential is available) will be automatically mocked via pinned data at submit time. Always declare \`output\` on nodes that use credentials so mock data is available. The workflow will be testable via manual/test runs but not production-ready until real credentials are added.
 
-${SDK_RULES_AND_PATTERNS}
+${SDK_RULES_AND_PATTERNS_TOOL}
 `;
 function createSandboxBuilderAgentPrompt(workspaceRoot) {
     return `You are an expert n8n workflow builder working inside a sandbox with real TypeScript tooling. You write workflow code as files and use \`tsc\` for validation.
 
-## Output Discipline
-- Your text output is visible to the user. Be concise but natural.
-- Do NOT narrate your process ("I'll build this step by step", "Let me start by"). Just do the work.
-- No emojis, no filler phrases, no markdown headers in your text output.
-- When conversation context is provided, use it to continue naturally — do not repeat information the user already knows.
-- Only output text for: errors that need attention, or a brief natural completion message.
+${BUILDER_OUTPUT_DISCIPLINE}
 
 ## Workspace Layout
 
@@ -598,9 +486,9 @@ Replace \`CHUNK_WORKFLOW_ID\` with the actual ID returned by \`submit-workflow\`
 - **Complex workflows** (5+ nodes, multiple integrations): Decompose into chunks.
   Build, test, and compose. Each chunk is reusable across workflows.
 
-## Setup Workflows (Create Missing Resources)
+${shared_prompts_1.PLACEHOLDERS_RULE}
 
-${PLACEHOLDER_RULE}
+## Setup Workflows (Create Missing Resources)
 
 When \`nodes(action="explore-resources")\` returns no results for a required resource:
 
@@ -615,9 +503,7 @@ When \`nodes(action="explore-resources")\` returns no results for a required res
 When called with failure details for an existing workflow, start from the pre-loaded code — do not re-discover node types already present.
 
 ## Escalation
-- If you are stuck or need information only a human can provide (e.g., a chat ID, API key, external resource name), use the \`ask-user\` tool to ask a clear question.
-- Do NOT retry the same failing approach more than twice — ask the user instead.
-- ${PLACEHOLDER_ESCALATION}
+${shared_prompts_1.ASK_USER_FALLBACK}
 
 ## Sandbox Isolation
 
@@ -635,9 +521,9 @@ When called with failure details for an existing workflow, start from the pre-lo
 - **For large HTML, use the file-based pattern.** Write HTML to \`chunks/page.html\`, then \`readFileSync\` + \`JSON.stringify\` in your SDK code. NEVER embed large HTML directly in jsCode — it will break. See the web_app_pattern section.
 - **Em-dash and Unicode**: the sandbox executes real JS so these technically work, but prefer plain hyphens for consistency with the shared SDK rules.
 
-## Credentials
+## Credentials (sandbox mode)
 
-Call \`credentials(action="list")\` early. Each credential has an \`id\`, \`name\`, and \`type\`. Wire them into nodes like this:
+Sandbox mode uses **raw credential objects** (not \`newCredential()\`). Call \`credentials(action="list")\` early. Each credential has an \`id\`, \`name\`, and \`type\`. Wire them into nodes like this:
 
 \`\`\`typescript
 credentials: {
@@ -649,6 +535,8 @@ The key (\`openWeatherMapApi\`) is the credential **type** from the node type de
 
 If the required credential type is not in \`credentials(action="list")\` results, call \`credentials(action="search-types")\` with the service name (e.g. "linear", "notion") to discover available dedicated credential types. Always prefer dedicated types over generic auth (\`httpHeaderAuth\`, \`httpBearerAuth\`, etc.). When generic auth is truly needed (no dedicated type exists), prefer \`httpBearerAuth\` over \`httpHeaderAuth\`.
 
+The credential-selection guidance above applies to outbound service calls. For inbound trigger nodes such as Webhook, Form Trigger, Chat Trigger, and MCP Trigger, keep authentication at its default \`none\` unless the user explicitly asks to authenticate inbound traffic.
+
 ## Data Tables
 
 n8n normalizes column names to snake_case (e.g., \`dayName\` → \`day_name\`). Always call \`data-tables(action="schema")\` before using a data table in workflow code to get the real column names.
@@ -683,8 +571,10 @@ n8n normalizes column names to snake_case (e.g., \`dayName\` → \`day_name\`).
 
 4. **Resolve real resource IDs**: Check the node schemas from step 3 for parameters with \`searchListMethod\` or \`loadOptionsMethod\`. For EACH one, call \`nodes(action="explore-resources")\` with the node type, method name, and the matching credential from step 1 to discover real resource IDs.
    - **This is mandatory for: calendars, spreadsheets, channels, folders, models, databases, and any other list-based parameter.** Do NOT assume values like "primary", "default", or "General" — always look up the real ID.
+   - **LLM models in particular** (OpenAI, Anthropic, Groq, etc.): always call \`explore-resources\` with the node's \`@searchListMethod\` when a credential for that provider is attached. The live list reflects what the credential can actually access — free/cheap tiers are often limited (e.g. an OpenAI free-tier key may only return \`gpt-5-mini\`). Picking a model ID that the credential can't access produces a broken workflow. The list is sorted newest-first; use the \`@builderHint\` as selection guidance (e.g. "prefer the GPT-5.4 family") over the live results, not as a hard-coded pick.
    - Example: Google Calendar's \`calendar\` parameter uses \`searchListMethod: getCalendars\`. Call \`nodes(action="explore-resources")\` with \`methodName: "getCalendars"\` to get the actual calendar ID (e.g., "user@example.com"), not "primary".
    - **Never use \`placeholder()\` or fake IDs for discoverable resources.** Create them via a setup workflow instead (see "Setup Workflows" section). For user-provided values, follow the placeholder rules in "SDK Code Rules".
+   - **If \`explore-resources\` returns more than one match and the user did not name a specific one, use \`placeholder('Select <resource>')\` for that parameter** (e.g. \`placeholder('Select a calendar')\`, \`placeholder('Select a Slack channel')\`). Picking one silently is a guess; the setup wizard surfaces placeholders so the user can choose after the build. Only pick a single match without prompting.
    - If the resource can't be created via n8n (e.g., Slack channels), explain clearly in your summary what the user needs to set up.
 
 5. **Write workflow code** to \`${workspaceRoot}/src/workflow.ts\`.
@@ -722,13 +612,21 @@ Follow the **Compositional Workflow Pattern** above. The process becomes:
 Do NOT produce visible output until the final step. All reasoning happens internally.
 
 ## Modifying Existing Workflows
-When modifying an existing workflow, the current code is **already pre-loaded** into \`${workspaceRoot}/src/workflow.ts\` with SDK imports. You can:
-- Read it with \`read_file\` to see the current code
+When modifying an existing workflow, the current code is **already pre-loaded** into \`${workspaceRoot}/src/workflow.ts\` with SDK imports.
+
+**Pre-flight check before any edit**: If the change introduces a node type not already in the file, or touches parameter values you haven't just looked up (model IDs, RLC values, enum selections, credential types, versions, etc.), call \`nodes(action="type-definition")\` first. Read \`@builderHint\`, \`@default\`, \`@searchListMethod\`, and \`@loadOptionsMethod\` from the output.
+
+**Live credential-backed lookups are the source of truth for RLC/list parameters.** When a node exposes \`@searchListMethod\` or \`@loadOptionsMethod\` and a credential for its type is attached, call \`nodes(action="explore-resources")\` to query what the credential can actually access — don't rely on \`@default\` or memory. Treat \`@builderHint\` as *selection guidance over the live list* ("prefer the GPT-5.4 family", "prefer the most recent Sonnet") rather than as the source of the value itself. When no credential is attached, fall back to \`@default\`. If the hint and \`@default\` disagree on the fallback, prefer the hint — it's curated more actively.
+
+Do not guess method names for \`explore-resources\`, and do not fill parameter values in from memory, even when the node or parameter feels familiar. This applies to swaps (Anthropic → OpenAI), model changes, trigger changes, and any parameter whose allowed values are unclear.
+
+Steps:
+- Read the current code with \`read_file\`
 - Edit using \`edit_file\` for targeted changes or \`write_file\` for full rewrites (always use absolute paths)
 - Run tsc → submit-workflow with the \`workflowId\`
 - Do NOT call \`workflows(action="get-as-code")\` — the file is already populated
 
-${SDK_RULES_AND_PATTERNS}
+${SDK_RULES_AND_PATTERNS_SANDBOX}
 `;
 }
 //# sourceMappingURL=build-workflow-agent.prompt.js.map

package/dist/tools/orchestration/build-workflow-agent.prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-workflow-agent.prompt.js","sourceRoot":"","sources":["../../../src/tools/orchestration/build-workflow-agent.prompt.ts"],"names":[],"mappings":";;;AA+dA,0EAuSC;AA9vBD,+FAQkE;AAClE,6EAIkD;AAClD,2EAKiD;AAKjD,MAAM,gBAAgB,GACrB,6eAA6e,CAAC;AAG/e,MAAM,sBAAsB,GAC3B,kTAAkT,CAAC;AAIpT,MAAM,cAAc,GAAG;;;;IAInB,gBAAgB;;;;;;qFAMiE,CAAC;AAEtF,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwWhC,iCAAgB;;;EAGhB,+CAA8B;;;EAG9B,sCAAqB,EAAE,CAAC;AAI1B,MAAM,sBAAsB,GAAG;IAC9B,cAAc;IACd,8BAAc;IACd,+BAA+B,GAAG,qCAAqB;IACvD,6BAA6B,GAAG,oCAAoB;IACpD,6BAA6B,GAAG,oCAAoB;IACpD,uCAAuC;IACvC,gCAAa,CAAC,OAAO;IACrB,oCAAiB,CAAC,OAAO;IACzB,iCAAc,CAAC,OAAO;IACtB,qCAAkB,CAAC,OAAO;IAC1B,mCAAgB,CAAC,OAAO;IACxB,wCAAqB,CAAC,OAAO;IAC7B,yCAAsB,CAAC,OAAO;IAC9B,yBAAyB;CACzB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAIF,QAAA,oBAAoB,GAAG;;;;;;;;;;;;;;;IAehC,sBAAsB;;;;;;;;;;;;;;;;;EAiBxB,sBAAsB;CACvB,CAAC;AAIF,SAAgB,+BAA+B,CAAC,aAAqB;IACpE,OAAO;;;;;;;;;;;0BAWkB,aAAa,6DAA6D,aAAa;;;EAG/G,aAAa;;;;;;;;;;;;;;;;;;KAkBV,aAAa;;;;;;;;;;;;;;;KAeb,aAAa;;;;;;;;;;;;;;;;;;;;;KAqBb,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsDb,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0ChB,gBAAgB;;;;;;;;;;;;;;;;;IAiBd,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sCA0DY,aAAa;;;;;;;;;;;;kCAYjB,aAAa;;;;;;;;;;;;;;;;;;;;;;;;6BAwBlB,aAAa;;;;sCAIJ,aAAa;;;;;;;yFAOsC,aAAa;;;;;;EAMpG,sBAAsB;CACvB,CAAC;AACF,CAAC"}
+{"version":3,"file":"build-workflow-agent.prompt.js","sourceRoot":"","sources":["../../../src/tools/orchestration/build-workflow-agent.prompt.ts"],"names":[],"mappings":"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"}

package/dist/tools/orchestration/build-workflow-agent.tool.d.ts

@@ -1,18 +1,57 @@
 import { z } from 'zod';
-import type { BackgroundTaskResult, OrchestrationContext } from '../../types';
-import { type SubmitWorkflowAttempt } from '../workflows/submit-workflow.tool';
+import type { OrchestrationContext } from '../../types';
+import { type WorkflowBuildOutcome, type WorkflowLoopState } from '../../workflow-loop';
+import { type SubmitWorkflowAttempt, type SubmitWorkflowOutput } from '../workflows/submit-workflow.tool';
+export declare function buildWarmBuilderFollowUp(input: {
+    task: string;
+    conversationContext?: string;
+    workflowId: string;
+    workItemId: string;
+}): string;
 export declare function recordSuccessfulWorkflowBuilds(tool: unknown, onWorkflowId: (workflowId: string) => void): void;
+export declare function mergeLatestVerificationIntoOutcome(outcome: WorkflowBuildOutcome, latestOutcome: WorkflowBuildOutcome | undefined): WorkflowBuildOutcome;
+export declare function withTerminalLoopState(outcome: WorkflowBuildOutcome, state: WorkflowLoopState | undefined): WorkflowBuildOutcome;
+export declare function finalizeBuildResult(context: OrchestrationContext, workItemId: string, result: {
+    text: string;
+    outcome: WorkflowBuildOutcome;
+}): Promise<{
+    text: string;
+    outcome: WorkflowBuildOutcome;
+}>;
 export declare function resultFromPostStreamError(input: {
     error: unknown;
     submitAttempts: SubmitWorkflowAttempt[];
     mainWorkflowPath: string;
     workItemId: string;
+    runId: string;
+    taskId: string;
+}): {
+    text: string;
+    outcome: WorkflowBuildOutcome;
+} | undefined;
+export declare function resultFromLaterFailedMainSubmit(input: {
+    failedAttempt: SubmitWorkflowAttempt;
+    submitAttempts: SubmitWorkflowAttempt[];
+    mainWorkflowPath: string;
+    workItemId: string;
+    runId: string;
     taskId: string;
-}): BackgroundTaskResult | undefined;
+}): {
+    text: string;
+    outcome: WorkflowBuildOutcome;
+} | undefined;
+export declare function attemptFromAutoResubmit(input: {
+    latestAttempt: SubmitWorkflowAttempt | undefined;
+    resubmit: SubmitWorkflowOutput;
+    filePath: string;
+    sourceHash: string;
+}): SubmitWorkflowAttempt | undefined;
+export declare function shouldRecoverSavedWorkflowAfterFailedSubmit(attempt: SubmitWorkflowAttempt): boolean;
 export interface StartBuildWorkflowAgentInput {
     task: string;
     workflowId?: string;
     conversationContext?: string;
+    workItemId?: string;
     taskId?: string;
     agentId?: string;
     plannedTaskId?: string;
@@ -27,13 +66,22 @@ export declare const buildWorkflowAgentInputSchema: z.ZodObject<{
     task: z.ZodString;
     workflowId: z.ZodOptional<z.ZodString>;
     conversationContext: z.ZodOptional<z.ZodString>;
+    workItemId: z.ZodOptional<z.ZodString>;
+    bypassPlan: z.ZodOptional<z.ZodBoolean>;
+    reason: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     task: string;
     workflowId?: string | undefined;
+    reason?: string | undefined;
+    workItemId?: string | undefined;
     conversationContext?: string | undefined;
+    bypassPlan?: boolean | undefined;
 }, {
     task: string;
     workflowId?: string | undefined;
+    reason?: string | undefined;
+    workItemId?: string | undefined;
     conversationContext?: string | undefined;
+    bypassPlan?: boolean | undefined;
 }>;
 export declare function createBuildWorkflowAgentTool(context: OrchestrationContext): import("@mastra/core/tools").Tool<InferPublicSchema<T>, InferPublicSchema<T>, InferPublicSchema<T>, InferPublicSchema<T>, import("@mastra/core/tools").ToolExecutionContext<InferPublicSchema<T>, InferPublicSchema<T>, unknown>, "build-workflow-with-agent", unknown>;