n8n 2.22.4 → 2.23.0

package/dist/modules/agents/builder/prompts/config-mutation.prompt.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigMutationPrompt = getConfigMutationPrompt;
+const config_rules_prompt_1 = require("./config-rules.prompt");
+function getConfigMutationPrompt() {
+    return `\
+## Config Mutation Guidance
+
+### Purpose
+
+Use this after deciding a config change is needed and before calling
+\`read_config\`, \`write_config\`, or \`patch_config\`.
+
+### Workflow
+
+1. Call \`read_config\` immediately before every \`write_config\` or \`patch_config\`.
+2. Use only the \`config\` and \`configHash\` returned by that same \`read_config\`.
+3. For \`write_config\`, send the complete config JSON string plus \`baseConfigHash\`.
+4. For \`patch_config\`, send RFC 6902 operations as a JSON string plus \`baseConfigHash\`.
+5. Use JSON Pointer paths like \`/field\`, \`/nested/field\`, \`/array/0\`, and \`/array/-\`.
+6. On \`stage: "stale"\`, retry once from the returned \`config\` and \`configHash\`.
+7. On parse, patch, or schema errors, fix the payload, call \`read_config\`
+   again, and retry from the fresh \`configHash\`.
+
+### Rules
+
+${(0, config_rules_prompt_1.getConfigRulesSection)()}
+
+${(0, config_rules_prompt_1.getSchemaReferenceSection)()}
+
+- Follow the Config schema reference exactly; do not invent top-level fields.
+- Keep each feature in the schema path where it belongs.
+- Preserve unrelated existing config unless the user asked to change it.
+- Never write placeholder instructions.
+- Never copy credential IDs from \`list_credentials\`; use \`resolve_llm\`, \`ask_llm\`, or \`ask_credential\`.
+- Valid provider tool keys are complete provider tool IDs documented in the Tool Guidance section.
+- \`providerTools\` keys must be complete provider tool IDs from the valid key list.
+
+### Recipes
+
+#### Create Or Replace A Fresh Runnable Agent
+
+- Requires \`name\`, \`model\`, \`credential\`, and \`instructions\`.
+- Keep \`tools\` and \`skills\` arrays if present.
+
+Good minimal shape:
+\`\`\`json
+{
+  "name": "Support assistant",
+  "model": "openrouter/openai/gpt-5.5",
+  "credential": "<main-llm-credential-id>",
+  "instructions": "Help the user with support questions.",
+  "tools": [],
+  "skills": []
+}
+\`\`\`
+
+#### Update Only Instructions
+
+Use \`patch_config\` with:
+\`\`\`json
+[{ "op": "replace", "path": "/instructions", "value": "New instructions" }]
+\`\`\`
+
+#### Add A Target-Agent Skill Ref
+
+- If \`skills\` exists, append to \`/skills/-\`.
+- If \`skills\` is missing, add \`/skills\` with an array.
+- Ref shape: \`{ "type": "skill", "id": "<returned-id>" }\`.
+
+#### Configure Native Provider Features
+
+- Thinking lives under \`config.thinking\`.
+- The write path fills native provider tool defaults. Do not invent provider tool keys.
+
+#### Configure Fallback Services
+
+- Services that require credentials must call \`ask_credential\` first.
+- Persist only the credential id returned by \`ask_credential\`.
+- If credential selection is skipped, do not enable the feature unless it supports missing credentials.
+
+#### Add Node Or Workflow Tools
+
+- Node and workflow tools live in \`tools[]\`.
+- Use Tool Guidance for node/workflow details.
+- Do not mix node tool config into \`config.*\` fields.
+
+### Do Not Do This
+
+Bad: inventing top-level fields
+\`\`\`json
+{ "temperature": 0.7 }
+\`\`\`
+
+Bad: provider namespace as provider tool
+\`\`\`json
+{ "providerTools": { "anthropic": {} } }
+\`\`\`
+
+Bad: copying credential IDs from \`list_credentials\`
+\`\`\`json
+{ "credential": "<id-from-list_credentials>" }
+\`\`\`
+
+Bad: replacing \`config\` while dropping unrelated settings
+\`\`\`json
+{ "config": { "thinking": { "provider": "anthropic", "budgetTokens": 1024 } } }
+\`\`\`
+
+### Gotchas
+
+- \`write_config\` replaces the full config; include every field that should survive.
+- \`patch_config\` cannot create a config when none exists; use \`write_config\` first.
+- \`/array/-\` appends to an array; \`/array/0\` inserts before the current first item.
+- Empty, placeholder, or guessed \`instructions\` are rejected; ask for details instead.
+
+### Verify
+
+- The final payload validates against the Config schema reference.
+- Existing unrelated config, tools, skills, integrations, and memory remain present unless intentionally changed.
+- Credential fields use ids returned by the correct interactive credential tools.
+- Provider tool keys are valid and match the selected model provider.
+
+### Error Recovery
+
+- \`stage: "stale"\`: retry once from the returned \`config\` and \`configHash\`.
+- \`stage: "parse"\`: fix JSON syntax, then call \`read_config\` before retrying.
+- \`stage: "patch"\`: fix JSON Pointer paths or operation shape, then call \`read_config\` before retrying.
+- \`stage: "schema"\`: compare the payload against the Config schema reference, then call \`read_config\` before retrying.
+- \`ask_credential\` skipped: omit or disable the feature that required it.`;
+}
+//# sourceMappingURL=config-mutation.prompt.js.map

package/dist/modules/agents/builder/prompts/config-mutation.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-mutation.prompt.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/prompts/config-mutation.prompt.ts"],"names":[],"mappings":";;AAEA,0DA8HC;AAhID,+DAAyF;AAEzF,SAAgB,uBAAuB;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;EAqBN,IAAA,2CAAqB,GAAE;;EAEvB,IAAA,+CAAyB,GAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4EAqG+C,CAAC;AAC7E,CAAC"}

package/dist/modules/agents/builder/prompts/config-rules.prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function getConfigRulesSection(): string;
+export declare function getSchemaReferenceSection(): string;

package/dist/modules/agents/builder/prompts/config-rules.prompt.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigRulesSection = getConfigRulesSection;
+exports.getSchemaReferenceSection = getSchemaReferenceSection;
+const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const api_types_1 = require("@n8n/api-types");
+const schema_text_serializer_1 = require("../../json-config/schema-text-serializer");
+const BuilderPromptMemoryConfigSchema = zod_1.z.object({
+    enabled: zod_1.z.boolean(),
+    storage: zod_1.z.literal('n8n'),
+    lastMessages: zod_1.z.number().int().min(1).max(200).optional(),
+    observationalMemory: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+        observerThresholdTokens: zod_1.z.number().int().min(1).optional(),
+        reflectorThresholdTokens: zod_1.z.number().int().min(1).optional(),
+        renderTokenBudget: zod_1.z.number().int().min(1).optional(),
+        observationLogTailLimit: zod_1.z.number().int().min(1).optional(),
+        lockTtlMs: zod_1.z.number().int().min(0).optional(),
+    })
+        .optional(),
+    episodicMemory: zod_1.z
+        .discriminatedUnion('enabled', [
+        zod_1.z.object({ enabled: zod_1.z.literal(false) }),
+        zod_1.z.object({
+            enabled: zod_1.z.literal(true),
+            credential: zod_1.z.string().min(1),
+            topK: zod_1.z.number().int().min(1).max(100).optional(),
+            maxEntriesPerRun: zod_1.z.number().int().min(1).max(50).optional(),
+        }),
+    ])
+        .optional(),
+});
+const BuilderPromptAgentJsonConfigSchema = api_types_1.RunnableAgentJsonConfigSchema.extend({
+    memory: BuilderPromptMemoryConfigSchema.optional(),
+});
+function getConfigRulesSection() {
+    return `\
+#### Agent Config Rules
+
+- \`model\` must be "provider/model-name".
+- \`credential\` must be the id returned by \`resolve_llm\` or \`ask_llm\`.
+- Fresh agents must include
+  \`memory: { "enabled": true, "storage": "n8n", "lastMessages": 50 }\`
+  unless the user explicitly asks to disable memory.
+- \`memory.storage\` must be "n8n"; \`memory.lastMessages\` defaults to 50.
+- \`memory.episodicMemory\` requires \`ask_credential\` with
+  \`credentialType: "openAiApi"\`.
+- \`config.maxIterations\` caps the number of agent loop iterations per run. Do not set or change this unless the user explicitly asks.
+- Fresh agents need a real model, credential, and instructions before config
+  is written.`;
+}
+function getSchemaReferenceSection() {
+    const jsonSchemaText = (0, schema_text_serializer_1.jsonSchemaToCompactText)((0, zod_to_json_schema_1.zodToJsonSchema)(BuilderPromptAgentJsonConfigSchema));
+    return `\
+#### Config Schema Reference
+
+\`\`\`text
+${jsonSchemaText}
+\`\`\``;
+}
+//# sourceMappingURL=config-rules.prompt.js.map

package/dist/modules/agents/builder/prompts/config-rules.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-rules.prompt.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/prompts/config-rules.prompt.ts"],"names":[],"mappings":";;AAuCA,sDAeC;AAED,8DAUC;AAjED,6BAAwB;AACxB,2DAAqD;AAErD,8CAA+D;AAE/D,qFAAmF;AAEnF,MAAM,+BAA+B,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;IACpB,OAAO,EAAE,OAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACzB,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IACzD,mBAAmB,EAAE,OAAC;SACpB,MAAM,CAAC;QACP,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC/B,uBAAuB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;QAC3D,wBAAwB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;QAC5D,iBAAiB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;QACrD,uBAAuB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;QAC3D,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;KAC7C,CAAC;SACD,QAAQ,EAAE;IACZ,cAAc,EAAE,OAAC;SACf,kBAAkB,CAAC,SAAS,EAAE;QAC9B,OAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,OAAC,CAAC,MAAM,CAAC;YACR,OAAO,EAAE,OAAC,CAAC,OAAO,CAAC,IAAI,CAAC;YACxB,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;YACjD,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;SAC5D,CAAC;KACF,CAAC;SACD,QAAQ,EAAE;CACZ,CAAC,CAAC;AAEH,MAAM,kCAAkC,GAAG,yCAA6B,CAAC,MAAM,CAAC;IAC/E,MAAM,EAAE,+BAA+B,CAAC,QAAQ,EAAE;CAClD,CAAC,CAAC;AAEH,SAAgB,qBAAqB;IACpC,OAAO;;;;;;;;;;;;;cAaM,CAAC;AACf,CAAC;AAED,SAAgB,yBAAyB;IACxC,MAAM,cAAc,GAAG,IAAA,gDAAuB,EAC7C,IAAA,oCAAe,EAAC,kCAAkC,CAAgB,CAClE,CAAC;IACF,OAAO;;;;EAIN,cAAc;OACT,CAAC;AACR,CAAC"}

package/dist/modules/agents/builder/prompts/llm-selection.prompt.d.ts

@@ -0,0 +1 @@
+export declare function getLlmSelectionPrompt(modelRecommendationsSection: string | null): string;

package/dist/modules/agents/builder/prompts/llm-selection.prompt.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLlmSelectionPrompt = getLlmSelectionPrompt;
+function getLlmSelectionPrompt(modelRecommendationsSection) {
+    const recommendationGuidance = modelRecommendationsSection
+        ? `\n\n${modelRecommendationsSection}`
+        : '\n\nNo Recommended LLM models section is available; do not recommend or name current, best, latest, or fallback model IDs from memory. Call ask_llm when the user needs model guidance or choice.';
+    return `\
+## LLM Selection Guidance
+
+### Purpose
+
+Use this to resolve the target agent's main \`model\` and \`credential\`.
+
+### Workflow
+
+1. Use \`resolve_llm\` before \`ask_llm\` when the request contains enough provider/model detail.
+2. If \`resolve_llm\` succeeds, persist \`model = "{provider}/{model}"\` and \`credential = credentialId\`.
+3. If the user asks to pick, change, confirm, or configure a model or main credential, call \`ask_llm\`; do not ask in prose.
+4. If \`resolve_llm\` reports missing or ambiguous credentials/provider, call \`ask_llm\`.
+5. If \`resolve_llm\` reports \`unknown_model\`, retry with a plausible returned model value or call \`ask_llm\`.
+
+### Rules
+
+- Fresh agents need a resolved \`model\` and \`credential\` before config is written.
+- Explicit provider/model requests go to \`resolve_llm\` first.
+- If the user asks to pick, change, confirm, or configure a model or main credential, call \`ask_llm\`; do not ask in prose.
+- If \`resolve_llm\` succeeds, persist \`model = "{provider}/{model}"\` and \`credential = credentialId\`.
+- If \`resolve_llm\` reports missing or ambiguous credentials/provider, call \`ask_llm\`.
+- If it reports \`unknown_model\`, retry with a plausible returned model value or call \`ask_llm\`.
+- For "Anthropic via OpenRouter", pass \`provider: "openrouter"\`; if the user names a routed model, pass the routed id without adding another provider prefix.
+- Prefer a provider the user already has credentials for when choosing from recommendations.
+- Never copy main LLM credential IDs from \`list_credentials\`.
+
+### Gotchas
+
+- Use \`resolve_llm\` or \`ask_llm\` only for the target agent's main model credential.
+- Use \`ask_credential\` for node tools, integrations, and Episodic Memory.
+- For OpenRouter, \`provider\` is \`"openrouter"\`; the model can be a routed id such as \`anthropic/...\`.
+- Do not recommend current, best, latest, or fallback model IDs from memory when the recommendation catalog is unavailable.
+
+### Verify
+
+- The persisted \`model\` is in \`provider/model\` form.
+- The persisted \`credential\` came from \`resolve_llm\` or \`ask_llm\`.${recommendationGuidance}`;
+}
+//# sourceMappingURL=llm-selection.prompt.js.map

package/dist/modules/agents/builder/prompts/llm-selection.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-selection.prompt.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/prompts/llm-selection.prompt.ts"],"names":[],"mappings":";;AAAA,sDA2CC;AA3CD,SAAgB,qBAAqB,CAAC,2BAA0C;IAC/E,MAAM,sBAAsB,GAAG,2BAA2B;QACzD,CAAC,CAAC,OAAO,2BAA2B,EAAE;QACtC,CAAC,CAAC,mMAAmM,CAAC;IAEvM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EAqCkE,sBAAsB,EAAE,CAAC;AACnG,CAAC"}

package/dist/modules/agents/builder/prompts/memory.prompt.d.ts

@@ -0,0 +1 @@
+export declare const MEMORY_PROMPT = "## Memory Guidance\n\n### Purpose\n\nUse this to configure the target agent's memory behavior.\n\n### Workflow\n\nFresh agents must include this default memory config unless the user explicitly asks to disable or change memory:\n```json\n{\n  \"enabled\": true,\n  \"storage\": \"n8n\",\n  \"lastMessages\": 50,\n  \"observationalMemory\": {\n    \"enabled\": true\n  }\n}\n```\n\nThis is the configurable agent's session memory. The runtime-managed\n`observationalMemory` settings tune that memory behavior; they are not a\nseparate user-facing memory product.\n\n### Rules\n\n- When creating a new agent, always write the exact default `memory` object above.\n- Set `storage` to \"n8n\".\n- `lastMessages` defaults to 50.\n- Set `observationalMemory.enabled` to `true` for new agents unless the user explicitly asks to disable observational memory.\n- Keep the rest of `observationalMemory` optional; add tuning fields only for explicit tuning or disabling.\n- Supported observational memory tuning fields: `enabled`, `observerThresholdTokens`, `reflectorThresholdTokens`, `renderTokenBudget`, `observationLogTailLimit`, and `lockTtlMs`.\n\n### Episodic Memory\n\n- Enable `memory.episodicMemory` only when the user asks for Episodic Memory, long-term memory, prior conversations, remembered decisions, exact artifacts, or cross-session memory.\n- Before enabling it, call `ask_credential({ credentialType: \"openAiApi\", purpose: \"OpenAI credential for Episodic Memory embeddings\" })`.\n- On success, set `memory.episodicMemory = { \"enabled\": true, \"credential\": \"<credentialId>\" }` and preserve existing `topK` or `maxEntriesPerRun`.\n- If credential selection is skipped, do not enable Episodic Memory; explain that it needs an OpenAI credential for embeddings.\n- Do not add instructions saying the agent should remember, store, save, or decide what context matters. The runtime handles memory extraction and indexing.\n- If instructions mention Episodic Memory, phrase it as retrieval/use only, e.g. \"Use recalled prior context when relevant to the user's request.\"\n- Do not invent Episodic Memory credential IDs or reuse the main model credential unless `ask_credential` returned it for this purpose.\n\n### Gotchas\n\n- Session memory and Episodic Memory are different features; do not use one as a substitute for the other.\n- Observational memory is runtime-managed session memory behavior; do not add target-agent instructions telling it how to save observations.\n- A skipped Episodic Memory credential means Episodic Memory stays disabled.\n\n### Verify\n\n- Fresh runnable agents have enabled n8n memory unless explicitly disabled.\n- Fresh runnable agents set `observationalMemory.enabled` to `true` unless explicitly disabled.\n- Episodic Memory has an OpenAI credential returned by `ask_credential`.\n- Existing memory tuning is preserved unless the user asked to change it.";

package/dist/modules/agents/builder/prompts/memory.prompt.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_PROMPT = void 0;
+exports.MEMORY_PROMPT = `\
+## Memory Guidance
+
+### Purpose
+
+Use this to configure the target agent's memory behavior.
+
+### Workflow
+
+Fresh agents must include this default memory config unless the user explicitly asks to disable or change memory:
+\`\`\`json
+{
+  "enabled": true,
+  "storage": "n8n",
+  "lastMessages": 50,
+  "observationalMemory": {
+    "enabled": true
+  }
+}
+\`\`\`
+
+This is the configurable agent's session memory. The runtime-managed
+\`observationalMemory\` settings tune that memory behavior; they are not a
+separate user-facing memory product.
+
+### Rules
+
+- When creating a new agent, always write the exact default \`memory\` object above.
+- Set \`storage\` to "n8n".
+- \`lastMessages\` defaults to 50.
+- Set \`observationalMemory.enabled\` to \`true\` for new agents unless the user explicitly asks to disable observational memory.
+- Keep the rest of \`observationalMemory\` optional; add tuning fields only for explicit tuning or disabling.
+- Supported observational memory tuning fields: \`enabled\`, \`observerThresholdTokens\`, \`reflectorThresholdTokens\`, \`renderTokenBudget\`, \`observationLogTailLimit\`, and \`lockTtlMs\`.
+
+### Episodic Memory
+
+- Enable \`memory.episodicMemory\` only when the user asks for Episodic Memory, long-term memory, prior conversations, remembered decisions, exact artifacts, or cross-session memory.
+- Before enabling it, call \`ask_credential({ credentialType: "openAiApi", purpose: "OpenAI credential for Episodic Memory embeddings" })\`.
+- On success, set \`memory.episodicMemory = { "enabled": true, "credential": "<credentialId>" }\` and preserve existing \`topK\` or \`maxEntriesPerRun\`.
+- If credential selection is skipped, do not enable Episodic Memory; explain that it needs an OpenAI credential for embeddings.
+- Do not add instructions saying the agent should remember, store, save, or decide what context matters. The runtime handles memory extraction and indexing.
+- If instructions mention Episodic Memory, phrase it as retrieval/use only, e.g. "Use recalled prior context when relevant to the user's request."
+- Do not invent Episodic Memory credential IDs or reuse the main model credential unless \`ask_credential\` returned it for this purpose.
+
+### Gotchas
+
+- Session memory and Episodic Memory are different features; do not use one as a substitute for the other.
+- Observational memory is runtime-managed session memory behavior; do not add target-agent instructions telling it how to save observations.
+- A skipped Episodic Memory credential means Episodic Memory stays disabled.
+
+### Verify
+
+- Fresh runnable agents have enabled n8n memory unless explicitly disabled.
+- Fresh runnable agents set \`observationalMemory.enabled\` to \`true\` unless explicitly disabled.
+- Episodic Memory has an OpenAI credential returned by \`ask_credential\`.
+- Existing memory tuning is preserved unless the user asked to change it.`;
+//# sourceMappingURL=memory.prompt.js.map

package/dist/modules/agents/builder/prompts/memory.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.prompt.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/prompts/memory.prompt.ts"],"names":[],"mappings":";;;AAAa,QAAA,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EAuD6C,CAAC"}

package/dist/modules/agents/builder/prompts/tools.prompt.d.ts

@@ -0,0 +1 @@
+export declare const TOOLS_PROMPT = "## Tool Guidance\n\n### Purpose\n\nUse this to give the target agent callable capabilities through workflows,\nnodes, custom code tools, or provider tools.\n\n### Workflow\n\nUse this guidance before calling `search_nodes`, `get_node_types`, `build_custom_tool`,\nor adding, changing, or removing entries in `tools[]` / `providerTools`.\n\nPrefer existing workflow tools and node tools over custom tools for real-world actions.\nCustom tools are for pure computation, validation, formatting, or planning logic;\nthey cannot perform live network, filesystem, process, timer, or host I/O.\n\n#### Workflow Tools\n\n- Call `list_workflows`; reference supported workflows by name with `{ \"type\": \"workflow\", \"workflow\": \"<name>\" }`.\n\n#### Node Tools\n\n- Use `search_nodes`, then `get_node_types`; never guess node type names.\n- Use the tool node id from discovery, usually ending in `Tool`.\n- Put fixed values in `nodeParameters`; use complete n8n expressions for values the agent should decide at runtime:\n  `={{ $fromAI('url', 'The URL to inspect', 'string') }}`.\n- Never write literal `\"$fromAI\"` or bare `$fromAI`; the node will treat it as the actual value.\n- Do not pipe AI-chosen fields through `$json`.\n- Do not include `inputSchema` or `toolDescription` for node tools.\n- For each required credential slot, call `ask_credential` once before config mutation. If skipped, still add the tool and omit only that credential slot.\n\n#### Custom Tools\n\n- Use `build_custom_tool` with `export default new Tool(...)` and imports only from `@n8n/agents` and `zod`.\n- Do not use custom tools for live website crawling, HTTP fetching, API calls, SEO crawlers, or scraping. Use workflow or node tools for those.\n- Register the returned custom tool id in config after `build_custom_tool`.\n- Custom handlers are pure functions: take validated `input`, compute, and return a JSON-serializable value. Do not call `.build()`.\n- Follow this pattern:\n```typescript\nimport { Tool } from '@n8n/agents';\nimport { z } from 'zod';\n\nexport default new Tool('tool_name')\n  .description('What the tool does')\n  .input(z.object({ query: z.string() }))\n  .handler(async ({ query }, ctx) => {\n    return { result: query.toUpperCase() };\n  });\n```\n- Custom handlers run in a V8 isolate. No network, filesystem, process, Buffer, fetch, timers, wall-clock waiting, or host I/O.\n- Some globals may exist as stubs: `setTimeout` fires synchronously, `console.log` goes nowhere, and `TextEncoder.encode` returns its input unchanged.\n- Safe globals include `Math`, `Date`, `JSON`, `RegExp`, `Array`, `Object`, `Map`, `Set`, `Promise`, typed arrays, and methods on provided values.\n- The handler receives `(input, ctx)`; `ctx.suspend(payload)` pauses for human-in-the-loop flows. Ignore `ctx` otherwise.\n- Execution is capped at 5 seconds and about 32 MB memory. If runtime fails, fix the code from the returned error and call `build_custom_tool` again.\n\n#### Provider Tools\n\n- Match provider tools to the configured model provider.\n- Anthropic: `providerTools[\"anthropic.web_search\"]`.\n- OpenAI: `providerTools[\"openai.web_search\"]` or `providerTools[\"openai.image_generation\"]`, only for compatible OpenAI models.\n\n### Gotchas\n\n- Live crawling, fetching, and API integrations need workflow or node tools, not custom tools.\n- Do not include `inputSchema` or `toolDescription` for node tools.\n- `$fromAI(...)` placeholders define the node tool input schema; do not add it manually.\n- Do not invent node type names, workflow names, credential ids, or provider tool keys.\n- If a required node-tool credential is skipped, add the tool and omit only that credential slot.\n- `build_custom_tool` stores code only; the config still needs a `{ \"type\": \"custom\", \"id\": \"<returned id>\" }` tool ref.\n\n### Verify\n\n- Workflow tools reference discovered workflow names.\n- Node tools use discovered tool node ids and valid node parameters.\n- Custom tools return a stored custom tool id that is registered in config.\n- Provider tool keys match the configured model provider and the valid key list.";

package/dist/modules/agents/builder/prompts/tools.prompt.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLS_PROMPT = void 0;
+exports.TOOLS_PROMPT = `\
+## Tool Guidance
+
+### Purpose
+
+Use this to give the target agent callable capabilities through workflows,
+nodes, custom code tools, or provider tools.
+
+### Workflow
+
+Use this guidance before calling \`search_nodes\`, \`get_node_types\`, \`build_custom_tool\`,
+or adding, changing, or removing entries in \`tools[]\` / \`providerTools\`.
+
+Prefer existing workflow tools and node tools over custom tools for real-world actions.
+Custom tools are for pure computation, validation, formatting, or planning logic;
+they cannot perform live network, filesystem, process, timer, or host I/O.
+
+#### Workflow Tools
+
+- Call \`list_workflows\`; reference supported workflows by name with \`{ "type": "workflow", "workflow": "<name>" }\`.
+
+#### Node Tools
+
+- Use \`search_nodes\`, then \`get_node_types\`; never guess node type names.
+- Use the tool node id from discovery, usually ending in \`Tool\`.
+- Put fixed values in \`nodeParameters\`; use complete n8n expressions for values the agent should decide at runtime:
+  \`={{ $fromAI('url', 'The URL to inspect', 'string') }}\`.
+- Never write literal \`"$fromAI"\` or bare \`$fromAI\`; the node will treat it as the actual value.
+- Do not pipe AI-chosen fields through \`$json\`.
+- Do not include \`inputSchema\` or \`toolDescription\` for node tools.
+- For each required credential slot, call \`ask_credential\` once before config mutation. If skipped, still add the tool and omit only that credential slot.
+
+#### Custom Tools
+
+- Use \`build_custom_tool\` with \`export default new Tool(...)\` and imports only from \`@n8n/agents\` and \`zod\`.
+- Do not use custom tools for live website crawling, HTTP fetching, API calls, SEO crawlers, or scraping. Use workflow or node tools for those.
+- Register the returned custom tool id in config after \`build_custom_tool\`.
+- Custom handlers are pure functions: take validated \`input\`, compute, and return a JSON-serializable value. Do not call \`.build()\`.
+- Follow this pattern:
+\`\`\`typescript
+import { Tool } from '@n8n/agents';
+import { z } from 'zod';
+
+export default new Tool('tool_name')
+  .description('What the tool does')
+  .input(z.object({ query: z.string() }))
+  .handler(async ({ query }, ctx) => {
+    return { result: query.toUpperCase() };
+  });
+\`\`\`
+- Custom handlers run in a V8 isolate. No network, filesystem, process, Buffer, fetch, timers, wall-clock waiting, or host I/O.
+- Some globals may exist as stubs: \`setTimeout\` fires synchronously, \`console.log\` goes nowhere, and \`TextEncoder.encode\` returns its input unchanged.
+- Safe globals include \`Math\`, \`Date\`, \`JSON\`, \`RegExp\`, \`Array\`, \`Object\`, \`Map\`, \`Set\`, \`Promise\`, typed arrays, and methods on provided values.
+- The handler receives \`(input, ctx)\`; \`ctx.suspend(payload)\` pauses for human-in-the-loop flows. Ignore \`ctx\` otherwise.
+- Execution is capped at 5 seconds and about 32 MB memory. If runtime fails, fix the code from the returned error and call \`build_custom_tool\` again.
+
+#### Provider Tools
+
+- Match provider tools to the configured model provider.
+- Anthropic: \`providerTools["anthropic.web_search"]\`.
+- OpenAI: \`providerTools["openai.web_search"]\` or \`providerTools["openai.image_generation"]\`, only for compatible OpenAI models.
+
+### Gotchas
+
+- Live crawling, fetching, and API integrations need workflow or node tools, not custom tools.
+- Do not include \`inputSchema\` or \`toolDescription\` for node tools.
+- \`$fromAI(...)\` placeholders define the node tool input schema; do not add it manually.
+- Do not invent node type names, workflow names, credential ids, or provider tool keys.
+- If a required node-tool credential is skipped, add the tool and omit only that credential slot.
+- \`build_custom_tool\` stores code only; the config still needs a \`{ "type": "custom", "id": "<returned id>" }\` tool ref.
+
+### Verify
+
+- Workflow tools reference discovered workflow names.
+- Node tools use discovered tool node ids and valid node parameters.
+- Custom tools return a stored custom tool id that is registered in config.
+- Provider tool keys match the configured model provider and the valid key list.`;
+//# sourceMappingURL=tools.prompt.js.map

package/dist/modules/agents/builder/prompts/tools.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.prompt.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/prompts/tools.prompt.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iFA4EqD,CAAC"}

package/dist/modules/agents/builder/skills/index.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSkill } from '@n8n/agents';
+export declare function getBuilderRuntimeSkills(): RuntimeSkill[];

package/dist/modules/agents/builder/skills/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBuilderRuntimeSkills = getBuilderRuntimeSkills;
+const integrations_skill_1 = require("./integrations.skill");
+const target_skills_skill_1 = require("./target-skills.skill");
+function getBuilderRuntimeSkills() {
+    return [
+        (0, integrations_skill_1.integrationsSkill)(),
+        (0, target_skills_skill_1.targetSkillsSkill)(),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/modules/agents/builder/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/skills/index.ts"],"names":[],"mappings":";;AAKA,0DASC;AAZD,6DAAyD;AACzD,+DAA0D;AAE1D,SAAgB,uBAAuB;IACtC,OAAO;QACN,IAAA,sCAAiB,GAAE;QACnB,IAAA,uCAAiB,GAAE;KAKnB,CAAC;AACH,CAAC"}

package/dist/modules/agents/builder/skills/integrations.skill.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSkill } from '@n8n/agents';
+export declare function integrationsSkill(): RuntimeSkill;

package/dist/modules/agents/builder/skills/integrations.skill.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.integrationsSkill = integrationsSkill;
+function integrationsSkill() {
+    return {
+        id: 'agent-builder-integrations',
+        name: 'Agent Builder Integrations',
+        description: 'Use when adding or changing target-agent schedule triggers or connected external chat-platform integrations; not for built-in Build chat or Preview chat behavior.',
+        instructions: `\
+## Purpose
+
+Use this to configure entries in the target agent's \`integrations\` array.
+
+## Boundaries
+
+- The user is asking for Build chat or Preview chat behavior.
+- The user wants an agent tool that sends messages; follow the Tool Guidance section instead.
+- The user only needs model, memory, or config-schema guidance.
+- Built-in Preview chat does not need an \`integrations\` entry.
+
+## Workflow
+
+The \`integrations\` array controls how the target agent is triggered.
+
+### Schedule
+
+- One schedule integration per agent.
+- Use \`{ "type": "schedule", "active": false, "cronExpression": "0 9 * * *", "wakeUpPrompt": "..." }\`.
+- Keep \`active: false\`; schedules run only after publish and activation.
+- Use standard 5-field cron.
+
+### Chat Integrations
+
+- These are connected external chat platforms, not built-in Preview chat.
+- Call \`list_integration_types\` first.
+- Pick one returned \`credentialTypes\` entry and pass it to \`ask_credential\`.
+- Persist only \`type\` and \`credentialId\`; never invent credential IDs or names.
+- Preserve existing schedule and chat integrations unless the user asked to remove them.
+
+## Gotchas
+
+- Active schedules are rejected until the agent is published; create or update schedules as inactive.
+- The schedule \`wakeUpPrompt\` is the message sent when the schedule fires, not target-agent system instructions.
+- Chat integration credential types must come from \`list_integration_types\`.
+
+## Verify
+
+- Schedule configs include \`type\`, \`active\`, \`cronExpression\`, and \`wakeUpPrompt\`.
+- Connected chat integrations use a credential id returned by \`ask_credential\`.
+- The final \`integrations\` array keeps unrelated integrations intact.`,
+    };
+}
+//# sourceMappingURL=integrations.skill.js.map

package/dist/modules/agents/builder/skills/integrations.skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrations.skill.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/skills/integrations.skill.ts"],"names":[],"mappings":";;AAEA,8CAiDC;AAjDD,SAAgB,iBAAiB;IAChC,OAAO;QACN,EAAE,EAAE,4BAA4B;QAChC,IAAI,EAAE,4BAA4B;QAClC,WAAW,EACV,oKAAoK;QACrK,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wEAyCwD;KACtE,CAAC;AACH,CAAC"}

package/dist/modules/agents/builder/skills/research.skill.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSkill } from '@n8n/agents';
+export declare function researchSkill(): RuntimeSkill;

package/dist/modules/agents/builder/skills/research.skill.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.researchSkill = researchSkill;
+function researchSkill() {
+    return {
+        id: 'agent-builder-research',
+        name: 'Agent Builder Research',
+        description: 'Use when current external API, service, product, standard, or spec facts affect target-agent config, tool choices, credential choices, or instructions; not for n8n internals, local schema, or builder tool contracts.',
+        instructions: `\
+## Purpose
+
+Use this when external facts can change the target-agent build.
+
+## Boundaries
+
+- You need n8n internals, local schema, or builder-tool guidance.
+- The API or service is well known enough to configure confidently from current context.
+- The user is asking for a general explanation that does not affect the target agent build.
+
+## Workflow
+
+1. Loading this skill is not research; when current external facts affect the
+   build, use the available research capability before relying on memory.
+2. Search only for the external facts that change the config or implementation choice.
+3. Prefer primary docs for endpoint, auth, product, or spec details.
+4. Apply only the verified details needed for the current target-agent build.
+5. If no research capability is available, say so instead of filling current facts from memory.
+
+## Gotchas
+
+- Do not browse for n8n internals, common JavaScript or TypeScript patterns, or local schema facts.
+- Do not let a web result override the target agent config schema or builder tool contracts.
+- Do not substitute unsourced model memory for current external facts when the user asked for research.
+- If research does not change the build, stop researching and continue from local context.
+
+## Verify
+
+- Configuration choices that depend on external facts are source-backed.
+- The final config still follows the local Config schema and credential rules.`,
+    };
+}
+//# sourceMappingURL=research.skill.js.map

package/dist/modules/agents/builder/skills/research.skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.skill.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/skills/research.skill.ts"],"names":[],"mappings":";;AAEA,sCAsCC;AAtCD,SAAgB,aAAa;IAC5B,OAAO;QACN,EAAE,EAAE,wBAAwB;QAC5B,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACV,yNAAyN;QAC1N,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+EA8B+D;KAC7E,CAAC;AACH,CAAC"}

package/dist/modules/agents/builder/skills/target-skills.skill.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSkill } from '@n8n/agents';
+export declare function targetSkillsSkill(): RuntimeSkill;

package/dist/modules/agents/builder/skills/target-skills.skill.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.targetSkillsSkill = targetSkillsSkill;
+function targetSkillsSkill() {
+    return {
+        id: 'agent-builder-target-skills',
+        name: 'Agent Builder Target Skills',
+        description: 'Use when creating reusable target-agent skills, playbooks, policies, style guides, or domain instructions with create_skill that should load only for relevant future requests; not for builder guidance or one-off instructions.',
+        instructions: `\
+## Purpose
+
+Use this to create reusable load-on-demand instructions for the target agent.
+
+## Boundaries
+
+- The instruction is one-off and belongs directly in the target agent instructions.
+- You need guidance for your own builder behavior.
+- The user is asking to edit config, tools, integrations, memory, or model settings without a reusable target-agent skill.
+
+## Workflow
+
+- Call \`create_skill\` with \`name\`, \`description\`, and \`body\`.
+- Treat the description as the routing contract: it is what the runtime sees
+  before deciding whether to load the skill.
+- Put all "when to use" and "when not to use" guidance in the description.
+- The body is loaded only after the skill triggers, so it should be a compact
+  operating manual: purpose, workflow, rules, gotchas, and verification where
+  useful.
+- Do not rely on a body "Use when" section for activation; include routing
+  guidance in \`description\`.
+- \`create_skill\` stores the body only; it does not attach the skill.
+- After it returns an id, call \`read_config\`.
+- Use \`patch_config\` or \`write_config\` to add \`{ "type": "skill", "id": "<returned id>" }\` to \`skills\`.
+
+## Rules
+
+- Write descriptions as intent-oriented "Use when..." guidance with concrete
+  triggers, contexts, and boundaries.
+- Keep skill bodies narrow, operational, and verifiable.
+- Do not rely on a body "Use when" section to trigger the skill; the body is
+  not visible until after the skill is selected.
+- Include concrete gotchas that prevent predictable target-agent mistakes.
+- Do not use \`create_skill\` for builder instructions. These skills belong to the target agent.
+
+## Gotchas
+
+- \`create_skill\` does not attach the skill to the target agent config.
+- A skill that is useful for every request probably belongs in instructions, not in \`skills\`.
+- A vague description creates a vague skill, even if the body is excellent.
+- Do not create placeholder or vague skills; ask for missing domain details first.
+
+## Verify
+
+- The returned skill id is attached in config as \`{ "type": "skill", "id": "<returned id>" }\`.
+- The skill description clearly states when it should load.
+- The body tells the target agent what to do differently when the skill is loaded.`,
+    };
+}
+//# sourceMappingURL=target-skills.skill.js.map

package/dist/modules/agents/builder/skills/target-skills.skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-skills.skill.js","sourceRoot":"","sources":["../../../../../src/modules/agents/builder/skills/target-skills.skill.ts"],"names":[],"mappings":";;AAEA,8CAuDC;AAvDD,SAAgB,iBAAiB;IAChC,OAAO;QACN,EAAE,EAAE,6BAA6B;QACjC,IAAI,EAAE,6BAA6B;QACnC,WAAW,EACV,mOAAmO;QACpO,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mFA+CmE;KACjF,CAAC;AACH,CAAC"}