n8n 2.46.4 → 2.47.1

package/dist/modules/agents/builder/agents-builder-tools.service.js

@@ -40,12 +40,11 @@ const agent_skills_service_1 = require("../agent-skills.service");
 const agent_task_service_1 = require("../agent-task.service");
 const agent_test_run_service_1 = require("../agent-test-run.service");
 const agents_service_1 = require("../agents.service");
-const agent_builder_preview_path_1 = require("./agent-builder-preview-path");
+const agent_builder_test_path_1 = require("./agent-builder-test-path");
 const call_agent_failure_1 = require("./call-agent-failure");
 const builder_model_live_lookup_service_1 = require("./builder-model-live-lookup.service");
 const builder_tool_names_1 = require("./builder-tool-names");
 const interactive_1 = require("./interactive");
-const skill_body_template_1 = require("./skill-body-template");
 const task_objective_template_1 = require("./task-objective-template");
 const verify_mcp_server_tool_1 = require("./verify-mcp-server.tool");
 const agent_skill_refs_service_1 = require("../agent-skill-refs.service");
@@ -53,24 +52,15 @@ const agent_config_composition_1 = require("../json-config/agent-config-composit
 const reconcile_node_tool_gateway_credentials_1 = require("../json-config/reconcile-node-tool-gateway-credentials");
 const agent_secure_runtime_1 = require("../runtime/agent-secure-runtime");
 const agent_config_hash_1 = require("../utils/agent-config-hash");
-const skill_name_taken_error_1 = require("../../../modules/skills/skill-name-taken.error");
+const skills_1 = require("../../../modules/skills");
 const STALE_CONFIG_ERROR = {
     path: '(root)',
     message: 'Agent config changed elsewhere. This result carries the current config and configHash: ' +
         're-apply your change to that config and retry once with that configHash.',
 };
-const BASE_CONFIG_HASH_RULE = 'Requires baseConfigHash: the configHash from the latest agent-context with type "config" result, ' +
-    'or from the latest builder result that returned one (agent_builder_write_config, agent_builder_patch_config, agent_builder_create_skills, ' +
-    'agent_builder_create_tasks, agent_builder_finish_setup, agent_builder_configure_channel, agent_builder_verify_mcp_server with credentialApplied: true, ' +
-    'or a stale failure), whichever came last. ';
-const BASE_CONFIG_HASH_FIELD_DESCRIPTION = 'Latest configHash from agent-context with type "config" or from the latest builder result that ' +
-    'returned one; null only if no config exists';
-const CONFIG_WRITE_RESULT_RULE = 'Returns { ok: true, configMutated: true, agentId, configHash } on success. The result also carries ' +
-    '`config` when the saved config differs from what you sent (for example applied defaults or kept ' +
-    'omitted fields); treat that `config` as the current state. On failure returns { ok: false, stage, ' +
-    'errors } and nothing is saved, so on a parse, patch, or schema error fix the payload and retry with ' +
-    'the same baseConfigHash. On stage: "stale", the result carries the current config and configHash: ' +
-    're-apply your change to it and retry once. ';
+const BASE_CONFIG_HASH_RULE = 'Pass baseConfigHash as the Config freshness rules of the agent-builder skill say. ' +
+    'Results that need an action carry `nextStep`: follow it.';
+const BASE_CONFIG_HASH_FIELD_DESCRIPTION = 'configHash of your latest config read or write; null only when no config exists';
 function configuredTriggerTypes(config) {
     return new Set((config?.integrations ?? [])
         .filter((integration) => typeof integration.credentialId === 'string' && !(0, api_types_1.isDraftIntegration)(integration))
@@ -116,10 +106,40 @@ const AGENT_LOCKED_BY_EDITOR_ERROR = {
     message: 'The agent is being edited by a user in the n8n builder right now, so it cannot be modified. ' +
         'Stop editing and tell the user to finish or close their editing session, then retry.',
 };
+function configWriteNextStep(result) {
+    if (result.ok === true) {
+        return result.config === undefined
+            ? undefined
+            : 'The saved config differs from what you sent. Treat `config` as the current state.';
+    }
+    if (result.ok !== false || result.stage === 'stale' || result.stage === 'locked')
+        return undefined;
+    const errors = Array.isArray(result.errors) ? result.errors : [];
+    const locked = errors.some((error) => (0, is_record_1.isRecord)(error) && error.message === AGENT_LOCKED_BY_EDITOR_ERROR.message);
+    return locked
+        ? undefined
+        : 'Nothing was saved. Fix the payload and retry with the same baseConfigHash.';
+}
+function withConfigWriteNextStep(result) {
+    if (!(0, is_record_1.isRecord)(result))
+        return result;
+    const nextStep = configWriteNextStep(result);
+    return nextStep ? { ...result, nextStep } : result;
+}
 const STALE_SKILL_ERROR_MESSAGE = 'Skill changed. Call agent-context with type "skill", then retry with its skill and skillHash.';
+function incompleteObjectivesNextStep(tasks) {
+    const gaps = tasks.flatMap(({ name, objective }) => {
+        const objectiveGaps = (0, task_objective_template_1.objectiveTemplateGaps)(objective);
+        return objectiveGaps.length > 0 ? [`"${name}" (${objectiveGaps.join(', ')})`] : [];
+    });
+    if (gaps.length === 0)
+        return undefined;
+    return (`These objectives do not follow the template: ${gaps.join('; ')}. Load ` +
+        `agent-builder-target-tasks and replace each objective with ${builder_tool_names_1.BUILDER_TOOLS.UPDATE_TASK}.`);
+}
 function updateSkillErrorMessage(error, message) {
-    if (error instanceof skill_name_taken_error_1.SkillNameTakenError)
-        return (0, skill_name_taken_error_1.skillNameTakenToolMessage)(error.skillName);
+    if (error instanceof skills_1.SkillNameTakenError)
+        return (0, skills_1.skillNameTakenToolMessage)(error.skillName);
     return error instanceof errors_1.ConflictError ? STALE_SKILL_ERROR_MESSAGE : message;
 }
 function isEmptyConfigValue(value) {
@@ -132,13 +152,12 @@ const CLI_AGENT_CONFIG_MESSAGES = {
 };
 const createSkillInputSchema = zod_1.z
     .object({
-    name: api_types_1.agentSkillSchema.shape.name.describe('Human-readable skill name. It must be unique in the project: no other skill of this ' +
-        'project may have a name like it (case, spaces, hyphens and underscores do not count).'),
-    description: api_types_1.agentSkillSchema.shape.description.describe(skill_body_template_1.SKILL_DESCRIPTION_RULE),
-    instructions: api_types_1.agentSkillSchema.shape.instructions.describe(skill_body_template_1.SKILL_BODY_GUIDANCE),
+    name: api_types_1.agentSkillSchema.shape.name.describe('Must be unique in the project'),
+    description: api_types_1.agentSkillSchema.shape.description.describe('Routing contract'),
+    instructions: api_types_1.agentSkillSchema.shape.instructions.describe('Body in the template'),
     references: api_types_1.agentSkillSchema.shape.references
         .optional()
-        .describe('Markdown-only supporting files under references/... paths. References are not automatically loaded; instructions must say exactly when to load each reference by path.'),
+        .describe('Markdown files under references/'),
 })
     .strict();
 const updateSkillFieldsSchema = zod_1.z
@@ -147,22 +166,18 @@ const updateSkillFieldsSchema = zod_1.z
     description: api_types_1.agentSkillSchema.shape.description.optional(),
     instructions: api_types_1.agentSkillSchema.shape.instructions
         .optional()
-        .describe('Complete replacement body. Use only for a rewrite of most of the body.'),
+        .describe('Complete replacement body'),
     instructionEdits: zod_1.z
         .array(zod_1.z
         .object({
-        oldText: zod_1.z
-            .string()
-            .min(1)
-            .describe('Exact text from the current instructions. It must match exactly one place.'),
-        newText: zod_1.z.string().describe('Replacement text. Use an empty string to delete.'),
+        oldText: zod_1.z.string().min(1).describe('Exact text that matches one place'),
+        newText: zod_1.z.string().describe('Empty string deletes'),
     })
         .strict())
         .min(1)
         .max(20)
         .optional()
-        .describe('Targeted replacements in the current instructions, applied in order. Prefer this to ' +
-        '`instructions` for a partial change. Do not pass both.'),
+        .describe('Partial body edits, applied in order. Do not pass with `instructions`.'),
     references: api_types_1.agentSkillSchema.shape.references
         .unwrap()
         .refine((references) => references.length > 0, 'Pass null to clear references.')
@@ -178,20 +193,22 @@ const updateSkillFieldsSchema = zod_1.z
 });
 const updateSkillInputSchema = zod_1.z
     .object({
-    skillId: zod_1.z.string().min(1).describe('Persisted target-agent skill id to update.'),
+    skillId: zod_1.z.string().min(1),
     baseSkillHash: zod_1.z
         .string()
         .min(1)
-        .describe('skillHash from the immediately preceding agent-context with type "skill" result for this skill.'),
-    updates: updateSkillFieldsSchema.describe('Only the fields to change. Pass null for references to remove them; an empty array is invalid.'),
+        .describe('skillHash from the preceding agent-context type "skill" result'),
+    updates: updateSkillFieldsSchema.describe('Only the fields to change. Pass null for references to remove them.'),
 })
     .strict();
 const updateTaskFieldsSchema = zod_1.z
     .object({
     name: api_types_1.agentTaskSchema.shape.name.optional(),
-    objective: api_types_1.agentTaskSchema.shape.objective.optional().describe(task_objective_template_1.TASK_OBJECTIVE_GUIDANCE),
+    objective: api_types_1.agentTaskSchema.shape.objective
+        .optional()
+        .describe('Complete replacement objective'),
     cronExpression: api_types_1.agentTaskSchema.shape.cronExpression.optional(),
-    timezone: api_types_1.agentTaskSchema.shape.timezone.describe('IANA zone the cron runs in. Pass null to move the task back to the instance timezone.'),
+    timezone: api_types_1.agentTaskSchema.shape.timezone.describe('Pass null for the instance timezone'),
 })
     .strict()
     .refine((updates) => Object.keys(updates).length > 0, {
@@ -199,8 +216,8 @@ const updateTaskFieldsSchema = zod_1.z
 });
 const updateTaskInputSchema = zod_1.z
     .object({
-    taskId: zod_1.z.string().min(1).describe('Persisted target-agent task id to update.'),
-    updates: updateTaskFieldsSchema.describe('Only the task fields to change.'),
+    taskId: zod_1.z.string().min(1),
+    updates: updateTaskFieldsSchema.describe('Only the fields to change'),
 })
     .strict();
 const notedContinuationSchema = zod_1.z.object({ run: zod_1.z.unknown(), sessionNote: zod_1.z.string() }).strict();
@@ -276,6 +293,17 @@ function applyPromptCachingBuilderDefaults(config) {
         },
     };
 }
+const FRESH_AGENT_MEMORY = {
+    enabled: true,
+    storage: 'n8n',
+    observationalMemory: { enabled: true },
+};
+function applyFreshAgentMemoryDefault(config, currentConfig) {
+    const isFresh = !currentConfig?.instructions?.trim();
+    if (!isFresh || config.memory !== undefined)
+        return config;
+    return { ...config, memory: FRESH_AGENT_MEMORY };
+}
 let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     constructor(agentsService, agentConfigService, agentCustomToolsService, agentIntegrationPersistenceService, agentSkillsService, secureRuntime, builderModelLiveLookupService, mcpRegistryService, oauthService, credentialTypes, agentTaskService, agentPublishService, agentTestRunService, aiService, aiGatewayService, outboundHttp, nodeTypes, freeAiCreditsService, telemetry, collaborationService, agentSkillRefs) {
         this.agentsService = agentsService;
@@ -421,7 +449,6 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             this.withConfigMutationMarker(unpublishAgentTool, agentId),
             callAgentTool,
             this.createLlmTool(credentialProvider, modelLookup, user, projectId),
-            (0, interactive_1.buildAskQuestionsTool)({ track }),
             this.withConfigMutationMarker(this.withConfigSnapshotOnResume(this.createConfigureChannelTool(agentId, projectId, user, track), agentId, projectId, (result) => typeof result.configured === 'boolean'), agentId),
             this.withConfigMutationMarker(this.withConfigSnapshotOnResume(this.createFinishSetupTool(credentialService, agentId, projectId, user, track), agentId, projectId, (result) => result.completed === true), agentId),
             this.createVerifyMcpServerTool(agentId, credentialProvider, projectId, user),
@@ -503,20 +530,18 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildCallAgentTool(user, projectId, agentId, credentialProvider) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.CALL_AGENT)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.CALL_AGENT))
-            .description('Do not call this tool by default after a build. Call it when the user reports a problem with the agent, to reproduce the problem and confirm the fix. ' +
-            'Tests the draft agent through built-in Preview chat. It does not test configured channel integrations, including their triggers, platform context, message delivery, or replies. ' +
-            'Omit sessionId to start a new conversation. To continue one, pass the exact sessionId from an earlier agent_builder_call_agent result; never make one up. ' +
-            'If the sessionId is not found, the test starts a new conversation and the result has a sessionNote. ' +
-            'The draft uses its real configured tools and credentials, so external side effects are possible. ' +
-            'Standard tool approvals pause this test until the user approves or rejects them in chat. ' +
-            'Unsupported interactive requests return approval_required with a Preview path.')
+            .description('Call it only when the user reports a problem with the agent, to reproduce it and ' +
+            'confirm the fix; not by default after a build. Tests the draft agent in the built-in ' +
+            'Preview chat, not channel integrations (triggers, platform context, delivery, or ' +
+            'replies). It runs the real configured tools and credentials, so external side ' +
+            'effects are possible. Omit sessionId to start a new conversation. To continue one, ' +
+            'pass the exact sessionId from an earlier result; never make one up. An unknown ' +
+            'sessionId starts a new conversation and the result has a sessionNote. Standard tool ' +
+            'approvals pause the test until the user decides in chat. Unsupported interactive ' +
+            'requests return approval_required with a Preview path.')
             .input(zod_1.z.object({
-            message: zod_1.z.string().trim().min(1).describe('Message to send to the target agent'),
-            sessionId: zod_1.z
-                .string()
-                .trim()
-                .optional()
-                .describe('Exact sessionId from an earlier agent_builder_call_agent result. Omit it to start a new conversation.'),
+            message: zod_1.z.string().trim().min(1),
+            sessionId: zod_1.z.string().trim().optional(),
         }))
             .suspend(tool_1.APPROVAL_SUSPEND_SCHEMA)
             .resume(tool_1.APPROVAL_RESUME_SCHEMA)
@@ -528,7 +553,7 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
                     message: 'You do not have permission to run agents in this project.',
                 };
             }
-            const previewPath = (0, agent_builder_preview_path_1.buildAgentPreviewPath)(projectId, agentId);
+            const previewPath = (0, agent_builder_test_path_1.buildAgentTestPath)(projectId, agentId);
             try {
                 const { result, sessionNote } = await this.runDraftTest(ctx, agentId, projectId, message, sessionId || undefined, credentialProvider, user);
                 return await this.formatDraftTestResult(result, ctx, agentId, user, previewPath, sessionNote);
@@ -587,9 +612,9 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildUnpublishAgentTool(user, projectId, agentId) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.UNPUBLISH_AGENT)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.UNPUBLISH_AGENT))
-            .description('Unpublish this target agent: clears the live version while preserving the draft, disconnects chat ' +
-            'integrations, and stops scheduled tasks. Call when the user asks to unpublish or take the agent offline. ' +
-            'Returns { ok: true, configMutated: true, agentId, activeVersionId: null } or { ok: false, errors }.')
+            .description('Unpublish the target agent: clear the live version but keep the draft, disconnect ' +
+            'chat integrations, and stop scheduled tasks. Call it when the user asks to unpublish ' +
+            'or take the agent offline.')
             .input(zod_1.z.object({}))
             .handler(async () => {
             if (!(await (0, check_access_1.userHasScopes)(user, ['agent:unpublish'], false, { projectId }))) {
@@ -619,17 +644,12 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildPublishAgentTool(user, projectId, agentId) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.PUBLISH_AGENT)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.PUBLISH_AGENT))
-            .description('Publish this target agent so it becomes live: integrations sync and scheduled tasks start running. ' +
-            'Idempotent when the draft is already the active published version. Pass optional `versionId` to ' +
-            'activate an existing history row instead of publishing the current draft. Call only when the user ' +
-            'asks to publish, activate, or make the agent live/usable — never tell them to click Publish in the editor. ' +
-            'Returns { ok: true, configMutated: true, agentId, activeVersionId, versionId } or { ok: false, errors }.')
+            .description('Publish the target agent so it goes live: integrations sync and scheduled tasks ' +
+            'start. Pass `versionId` to activate a history version instead of the draft. Call it ' +
+            'only when the user asks to publish, activate, or make the agent live or usable. Never ' +
+            'tell them to click Publish in the editor.')
             .input(zod_1.z.object({
-            versionId: zod_1.z
-                .string()
-                .min(1)
-                .optional()
-                .describe('Optional history version ID to activate. Omit to publish the current draft.'),
+            versionId: zod_1.z.string().min(1).optional().describe('Omit to publish the draft'),
         }))
             .handler(async ({ versionId }) => {
             if (!(await (0, check_access_1.userHasScopes)(user, ['agent:publish'], false, { projectId }))) {
@@ -669,17 +689,14 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildPatchConfigTool(agentId, projectId, user, track) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.PATCH_CONFIG)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.PATCH_CONFIG))
-            .description('Apply RFC 6902 JSON Patch operations to the current agent configuration. ' +
-            'Pass the patch operations as an array of objects, not as a JSON string. ' +
-            BASE_CONFIG_HASH_RULE +
-            'Supported ops: add, remove, replace, move, copy, test. ' +
-            CONFIG_WRITE_RESULT_RULE +
-            'stage is "locked", "parse", "stale", "patch", or "schema". On stage: "locked", stop and tell the user to close ' +
-            'their editing session in the n8n builder.')
+            .description('Apply RFC 6902 JSON Patch operations to the agent config. Pass `operations` as an ' +
+            'array, not as a JSON string. ' +
+            BASE_CONFIG_HASH_RULE)
+            .toModelOutput(withConfigWriteNextStep)
             .input(zod_1.z.object({
             operations: zod_1.z
                 .preprocess(parseJsonStringInput, zod_1.z.array(jsonPatchOperationSchema))
-                .describe('RFC 6902 JSON Patch operations'),
+                .describe('RFC 6902 operations'),
             baseConfigHash: zod_1.z.string().nullable().describe(BASE_CONFIG_HASH_FIELD_DESCRIPTION),
         }))
             .handler(async ({ operations, baseConfigHash, }) => await this.patchBuilderConfig(agentId, projectId, user, operations, baseConfigHash, track))
@@ -688,17 +705,16 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildWriteConfigTool(agentId, projectId, user, track) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.WRITE_CONFIG)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.WRITE_CONFIG))
-            .description('Create or update the agent configuration. Pass the config as an object, not as a JSON string. ' +
-            'Send only the top-level fields you set or change: every top-level field you omit ' +
-            '(including model and credential) keeps its stored value, and a field you send replaces ' +
-            'the stored field whole. A fresh agent with no stored config needs name, model, and instructions. ' +
-            BASE_CONFIG_HASH_RULE +
-            CONFIG_WRITE_RESULT_RULE +
-            'Failure errors carry path, message, expected, and received fields.')
+            .description('Create or update the agent config. Pass `config` as an object, not as a JSON string, ' +
+            'with only the top-level fields you set or change. An omitted field (including model ' +
+            'and credential) keeps its stored value. A sent field replaces the stored field whole. ' +
+            'A fresh agent needs name, model, and instructions. ' +
+            BASE_CONFIG_HASH_RULE)
+            .toModelOutput(withConfigWriteNextStep)
             .input(zod_1.z.preprocess(renameLegacyWriteConfigKey, zod_1.z.object({
             config: zod_1.z
                 .preprocess(parseJsonStringInput, zod_1.z.record(zod_1.z.unknown()))
-                .describe('Agent configuration object with the top-level fields to set'),
+                .describe('Top-level fields to set'),
             baseConfigHash: zod_1.z.string().nullable().describe(BASE_CONFIG_HASH_FIELD_DESCRIPTION),
         })))
             .handler(async ({ config, baseConfigHash }) => await this.writeBuilderConfig(agentId, projectId, user, config, baseConfigHash, track))
@@ -721,39 +737,20 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildCreateTasksTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.CREATE_TASKS)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.CREATE_TASKS))
-            .description('Create one or more recurring scheduled tasks for the target agent (name + objective + cron ' +
-            'schedule per task) in a single call. Pass every task you currently know how to write in one ' +
-            "`tasks` array — do not spread multiple fully-specified tasks across separate calls; each task's " +
-            'objective field carries its own structured template. The whole batch is all-or-nothing: an ' +
-            'invalid cron or objective rejects every task in the call. This adds a `{ type: "task", id, ' +
-            'enabled }` ref per task to the agent config (config.tasks) and each task starts running once ' +
-            'the agent is (re)published via `agent_builder_publish_agent`. Returns { ok: true, configMutated: true, agentId, ' +
-            'configHash, tasks: [{ id, name, enabled }, ...] } (same order as input, objectives and crons are ' +
-            'not echoed back) or { ok: false, errors }. Use the returned configHash as baseConfigHash for your ' +
-            'next config write.')
-            .systemInstruction('Never create a task with a vague, broad, or placeholder objective, an objective missing any ' +
-            'required section, or an unclear schedule. Each objective must follow the required structured ' +
-            'Markdown template (Objective, Context, Steps, Output, Constraints, Success criteria) with every ' +
-            'section filled in with concrete, run-specific content. Agent Instructions still apply and ' +
-            'configured Skills remain available during scheduled runs, so never repeat universal rules or ' +
-            "copy reusable procedures into an objective. If anything is ambiguous, derive it from the user's goal as " +
-            'stated assumptions listed in your summary; ask the user clarifying questions with agent_builder_ask_questions ' +
-            'only when even a reasonable assumption is impossible, before calling ' +
-            'agent_builder_create_tasks. A task can only use tools the agent already has: if any step in an objective ' +
-            'requires a tool, integration, or web search the agent is missing, you MUST add it to the agent ' +
-            'config (agent_builder_patch_config/agent_builder_write_config) BEFORE calling agent_builder_create_tasks — otherwise the task will fail at ' +
-            'runtime. Batch every task you currently know how to write into one call.')
+            .description('Create recurring scheduled tasks for the target agent. Load agent-builder-target-tasks ' +
+            'first: it has the required objective template and the task rules. Pass every task you ' +
+            'can write in one `tasks` array; the batch is all-or-nothing. Tasks run after the next ' +
+            'agent_builder_publish_agent.')
             .input(zod_1.z.object({
             tasks: zod_1.z
                 .array(zod_1.z.object({
-                name: api_types_1.agentTaskSchema.shape.name.describe('Short, human-readable task name.'),
-                objective: api_types_1.agentTaskSchema.shape.objective.describe(task_objective_template_1.TASK_OBJECTIVE_GUIDANCE),
-                cronExpression: api_types_1.agentTaskSchema.shape.cronExpression.describe('A 5-field cron expression for when the task runs, e.g. "0 9 * * 1-5" = weekdays at 09:00.'),
-                timezone: api_types_1.agentTaskSchema.shape.timezone.describe('IANA timezone the cron runs in, e.g. "Europe/London". Set it when the user names a timezone or a location; omit it to use the instance timezone.'),
+                name: api_types_1.agentTaskSchema.shape.name,
+                objective: api_types_1.agentTaskSchema.shape.objective.describe('Objective in the template'),
+                cronExpression: api_types_1.agentTaskSchema.shape.cronExpression,
+                timezone: api_types_1.agentTaskSchema.shape.timezone.describe('Set when the user names a timezone or location'),
             }))
                 .min(1)
-                .max(20)
-                .describe('Every task to create, in the order they should be created.'),
+                .max(20),
         }))
             .handler(async ({ tasks, }) => {
             const editorLock = await this.getEditorLockFailure(agentId);
@@ -769,10 +766,12 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
                     errors: [{ message: e instanceof Error ? e.message : String(e) }],
                 };
             }
+            const nextStep = incompleteObjectivesNextStep(tasks);
             return {
                 ok: true,
                 configHash: created.configHash,
                 tasks: created.tasks.map(({ id, name }) => ({ id, name, enabled: true })),
+                ...(nextStep ? { nextStep } : {}),
             };
         })
             .build();
@@ -780,9 +779,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildUpdateTaskTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.UPDATE_TASK)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.UPDATE_TASK))
-            .description('Update selected body fields of an existing target-agent scheduled task in place, preserving ' +
-            'its id and config reference. Returns { ok: true, id, name, configMutated: true, agentId } ' +
-            'or { ok: false, errors }.')
+            .description('Update fields of an existing target-agent task in place. It keeps the task id and config ' +
+            'ref. Load agent-builder-target-tasks before you replace an objective.')
             .input(updateTaskInputSchema)
             .handler(async ({ taskId, updates }) => {
             const editorLock = await this.getEditorLockFailure(agentId);
@@ -793,7 +791,16 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
                     user,
                     modifiedBy: 'builder',
                 });
-                return { ok: true, id: task.id, name: task.name, ...(changed ? {} : { changed }) };
+                const nextStep = updates.objective === undefined
+                    ? undefined
+                    : incompleteObjectivesNextStep([{ name: task.name, objective: updates.objective }]);
+                return {
+                    ok: true,
+                    id: task.id,
+                    name: task.name,
+                    ...(changed ? {} : { changed }),
+                    ...(nextStep ? { nextStep } : {}),
+                };
             }
             catch (e) {
                 return {
@@ -807,17 +814,10 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildUpdateSkillTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.UPDATE_SKILL)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.UPDATE_SKILL))
-            .description('Update selected fields of an existing target-agent skill in place, preserving its id and ' +
-            'agent config reference. Requires baseSkillHash from the immediately preceding agent-context with type "skill" ' +
-            'result. To change part of the body, pass instructionEdits with oldText/newText pairs ' +
-            'instead of rewriting instructions. Pass null for references to remove all references; an ' +
-            'empty array is invalid. The skill is shared: the update saves its next version, and every ' +
-            'agent draft that follows the latest version runs that version. Published versions keep ' +
-            'the version they pinned. Returns ' +
-            '{ ok: true, id, name, configMutated: true, agentId } or { ok: false, errors }. A failed edit ' +
-            'saves nothing: fix oldText so it matches exactly one place and retry with the same ' +
-            'baseSkillHash. On a stale skill error, ' +
-            'call agent-context with type "skill" and retry once with its fresh skillHash.')
+            .description('Update fields of an existing target-agent skill in place. It keeps the skill id and ' +
+            'config ref. Load agent-builder-target-skills first. The skill is shared: the update ' +
+            'saves its next version for every draft that follows the latest version. Published ' +
+            'versions keep the version they pinned.')
             .input(updateSkillInputSchema)
             .handler(async ({ skillId, baseSkillHash, updates }) => {
             const editorLock = await this.getEditorLockFailure(agentId);
@@ -847,32 +847,12 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildCreateSkillsTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.CREATE_SKILLS)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.CREATE_SKILLS))
-            .description('Create and store one or more agent skills (reusable, load-on-demand capabilities) in a ' +
-            'single call. Pass every skill you currently know how to write in one `skills` array — do ' +
-            "not spread multiple fully-specified skills across separate calls; each skill's instructions " +
-            'field carries its own structured template. The whole batch is all-or-nothing: an invalid or ' +
-            'duplicate-named skill rejects every skill in the call. It also attaches a `{ type: "skill", id }` ' +
-            'ref per skill to the agent config (config.skills), so do not patch them in yourself; the agent ' +
-            'config must already exist. Returns { ok: true, configMutated: true, agentId, configHash, skills: ' +
-            '[{ id, name }, ...] } (same order as input, bodies are not echoed back) or { ok: false, errors }. ' +
-            'Use the returned configHash as baseConfigHash for your next config write.')
-            .systemInstruction('Never create a vague or placeholder skill. The description field is the routing contract the ' +
-            'runtime uses to decide when to load the skill; the instructions must follow the required ' +
-            'structured Markdown template (Overview, Inputs, Steps, Rules, Example, Gotchas) with each ' +
-            'applicable section filled in with concrete, specific content. If you do not have enough domain ' +
-            "detail to write a genuinely useful skill, derive it from the user's goal as stated assumptions " +
-            'listed in your summary; ask the user clarifying questions only when even a reasonable ' +
-            'assumption is impossible. Use references ' +
-            'only for markdown supporting files under the references/ directory — references are not ' +
-            'automatically loaded, so instructions must say exactly when to load each one by path; scripts and ' +
-            'non-markdown linked files are not supported. Do not invent tool names or reference paths. Batch ' +
-            'every skill you currently know how to write into one call.')
+            .description('Create target-agent skills and attach a ref for each to config.skills. Do not patch the ' +
+            'refs yourself. The agent config must exist. Load agent-builder-target-skills first: it ' +
+            'has the required description and body templates and the skill rules. Pass every skill ' +
+            'you can write in one `skills` array; the batch is all-or-nothing.')
             .input(zod_1.z.object({
-            skills: zod_1.z
-                .array(createSkillInputSchema)
-                .min(1)
-                .max(20)
-                .describe('Every skill to create, in the order they should be created.'),
+            skills: zod_1.z.array(createSkillInputSchema).min(1).max(20),
         }))
             .handler(async ({ skills }) => {
             const editorLock = await this.getEditorLockFailure(agentId);
@@ -887,8 +867,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
                 };
             }
             catch (e) {
-                const message = e instanceof skill_name_taken_error_1.SkillNameTakenError
-                    ? `${(0, skill_name_taken_error_1.skillNameTakenToolMessage)(e.skillName)} The batch is all-or-nothing, so send every skill again.`
+                const message = e instanceof skills_1.SkillNameTakenError
+                    ? `${(0, skills_1.skillNameTakenToolMessage)(e.skillName)} The batch is all-or-nothing, so send every skill again.`
                     : e instanceof Error
                         ? e.message
                         : String(e);
@@ -900,18 +880,12 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildCustomToolTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.BUILD_CUSTOM_TOOL)
             .legacyNames(...(0, api_types_1.getLegacyBuilderToolNames)(builder_tool_names_1.BUILDER_TOOLS.BUILD_CUSTOM_TOOL))
-            .description('Compile and store a custom tool. Pass the complete TypeScript source ' +
-            'using `export default new Tool(...)` builder chain. The code is validated in a ' +
-            'sandbox and saved against the agent. The returned `id` equals the tool name ' +
-            'declared in the code (e.g. `new Tool("my_tool")` → id `"my_tool"`). ' +
-            'This does NOT register the tool in the agent config — follow up with ' +
-            'agent_builder_patch_config (or agent_builder_write_config) to add `{ type: "custom", id: "<tool name>" }` ' +
-            'to `tools`.' +
-            'Returns { ok: true, id, name } or { ok: false, errors }.')
+            .description('Compile and store a custom tool from complete TypeScript source that uses ' +
+            '`export default new Tool(...)`. A sandbox validates the code. The returned id is the ' +
+            'tool name in the code. This does NOT add the tool to the config: add ' +
+            '`{ type: "custom", id: "<tool name>" }` to `tools` with a config write.')
             .input(zod_1.z.object({
-            code: zod_1.z
-                .string()
-                .describe('Complete TypeScript source using export default new Tool(...)'),
+            code: zod_1.z.string(),
         }))
             .handler(async ({ code }, ctx) => {
             const editorLock = await this.getEditorLockFailure(agentId);
@@ -1053,7 +1027,7 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         const dynamicSelectorFromAi = (0, agent_config_1.rejectIfDynamicSelectorUsesFromAi)(parsed.data, currentConfig, this.nodeTypes, CLI_AGENT_CONFIG_MESSAGES);
         if (dynamicSelectorFromAi)
             return { ok: false, errors: dynamicSelectorFromAi };
-        const config = applyPromptCachingBuilderDefaults((0, agent_config_1.applyNativeWebSearchDefaultOn)(parsed.data));
+        const config = applyPromptCachingBuilderDefaults((0, agent_config_1.applyNativeWebSearchDefaultOn)(applyFreshAgentMemoryDefault(parsed.data, currentConfig)));
         return { ok: true, config };
     }
     async saveBuilderConfig(agentId, projectId, user, config, baseConfigHash, submitted, clearOmittedOptionalFields = false) {