n8n 2.43.4 → 2.44.0

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

@@ -10,6 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentsBuilderToolsService = void 0;
+const is_record_1 = require("@n8n/utils/is-record");
 const agents_1 = require("@n8n/agents");
 const tool_1 = require("@n8n/agents/tool");
 const agent_config_1 = require("@n8n/ai-utilities/agent-config");
@@ -51,14 +52,54 @@ 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");
 const agent_config_composition_1 = require("../json-config/agent-config-composition");
 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 STALE_CONFIG_ERROR = {
     path: '(root)',
-    message: 'Agent config changed. Call agent-context with type "config", then retry with its config and configHash.',
+    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 (write_config, patch_config, create_skills, ' +
+    'create_tasks, finish_setup, configure_channel, 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. ';
+function parseJsonStringInput(value) {
+    if (typeof value !== 'string')
+        return value;
+    const parsed = (0, api_types_1.tryParseConfigJson)(value);
+    return parsed.ok ? parsed.data : value;
+}
+function readStructuredToolInput(value) {
+    return typeof value === 'string' ? (0, api_types_1.tryParseConfigJson)(value) : { ok: true, data: value };
+}
+function mergeOmittedTopLevelFields(submitted, stored) {
+    if (!stored || !(0, is_record_1.isRecord)(submitted))
+        return submitted;
+    return { ...stored, ...submitted };
+}
+function renameLegacyWriteConfigKey(value) {
+    if (!(0, is_record_1.isRecord)(value) || value.config !== undefined || value.json === undefined)
+        return value;
+    const { json, ...rest } = value;
+    return { ...rest, config: json };
+}
+const jsonPatchOperationSchema = zod_1.z.object({
+    op: zod_1.z.enum(['add', 'remove', 'replace', 'move', 'copy', 'test']),
+    path: zod_1.z.string().describe('JSON Pointer, e.g. "/instructions" or "/tools/-"'),
+    from: zod_1.z.string().optional().describe('Source JSON Pointer for move and copy'),
+    value: zod_1.z.unknown().optional().describe('New value for add, replace, and test'),
+});
 const AGENT_LOCKED_BY_EDITOR_ERROR = {
     path: '(root)',
     message: 'The agent is being edited by a user in the n8n builder right now, so it cannot be modified. ' +
@@ -87,7 +128,24 @@ const updateSkillFieldsSchema = zod_1.z
     .object({
     name: api_types_1.agentSkillSchema.shape.name.optional(),
     description: api_types_1.agentSkillSchema.shape.description.optional(),
-    instructions: api_types_1.agentSkillSchema.shape.instructions.optional(),
+    instructions: api_types_1.agentSkillSchema.shape.instructions
+        .optional()
+        .describe('Complete replacement body. Use only for a rewrite of most of the 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.'),
+    })
+        .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.'),
     allowedTools: api_types_1.agentSkillSchema.shape.allowedTools.unwrap().min(1).nullable().optional(),
     references: api_types_1.agentSkillSchema.shape.references
         .unwrap()
@@ -98,6 +156,9 @@ const updateSkillFieldsSchema = zod_1.z
     .strict()
     .refine((updates) => Object.keys(updates).length > 0, {
     message: 'At least one skill field must be supplied.',
+})
+    .refine((updates) => !(updates.instructions && updates.instructionEdits), {
+    message: 'Pass either instructions or instructionEdits, not both.',
 });
 const updateSkillInputSchema = zod_1.z
     .object({
@@ -126,6 +187,7 @@ const updateTaskInputSchema = zod_1.z
     updates: updateTaskFieldsSchema.describe('Only the task fields to change.'),
 })
     .strict();
+const notedContinuationSchema = zod_1.z.object({ run: zod_1.z.unknown(), sessionNote: zod_1.z.string() }).strict();
 function snapshotFromConfig(config) {
     return {
         config,
@@ -172,7 +234,7 @@ function applyPromptCachingBuilderDefaults(config) {
     };
 }
 let AgentsBuilderToolsService = class AgentsBuilderToolsService {
-    constructor(logger, agentsService, agentConfigService, agentCustomToolsService, agentIntegrationPersistenceService, agentSkillsService, secureRuntime, agentsToolsService, builderModelLiveLookupService, mcpRegistryService, oauthService, credentialTypes, agentTaskService, agentPublishService, agentTestRunService, aiService, aiGatewayService, outboundHttp, dynamicNodeParametersService, nodeTypes, freeAiCreditsService, telemetry, agentContextAdapter, collaborationService) {
+    constructor(logger, agentsService, agentConfigService, agentCustomToolsService, agentIntegrationPersistenceService, agentSkillsService, secureRuntime, agentsToolsService, builderModelLiveLookupService, mcpRegistryService, oauthService, credentialTypes, agentTaskService, agentPublishService, agentTestRunService, aiService, aiGatewayService, outboundHttp, dynamicNodeParametersService, nodeTypes, freeAiCreditsService, telemetry, agentContextAdapter, collaborationService, agentSkillRefs) {
         this.logger = logger;
         this.agentsService = agentsService;
         this.agentConfigService = agentConfigService;
@@ -197,6 +259,7 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         this.telemetry = telemetry;
         this.agentContextAdapter = agentContextAdapter;
         this.collaborationService = collaborationService;
+        this.agentSkillRefs = agentSkillRefs;
     }
     withConfigMutationMarker(tool, agentId) {
         const handler = tool.handler;
@@ -218,6 +281,22 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             },
         };
     }
+    withConfigSnapshotOnResume(tool, agentId, projectId, isFinal) {
+        const handler = tool.handler;
+        if (!handler)
+            return tool;
+        return {
+            ...tool,
+            handler: async (input, ctx) => {
+                const result = await handler(input, ctx);
+                const resumed = 'resumeData' in ctx && ctx.resumeData !== undefined && ctx.resumeData !== null;
+                if (!resumed || !(0, is_record_1.isRecord)(result) || !isFinal(result))
+                    return result;
+                const snapshot = await this.getConfigSnapshot(agentId, projectId).catch(() => null);
+                return snapshot ? { ...result, ...snapshot } : result;
+            },
+        };
+    }
     async getEditorLockFailure(agentId) {
         try {
             await this.collaborationService.ensureAgentEditable(agentId);
@@ -260,8 +339,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             this.createCredentialTool(credentialService, projectId, agentId, track),
             this.createEmbeddingCredentialTool(credentialService, projectId, track),
             (0, interactive_1.buildAskQuestionsTool)({ track }),
-            this.withConfigMutationMarker(this.createConfigureChannelTool(agentId, projectId, track), agentId),
-            this.withConfigMutationMarker(this.createFinishSetupTool(credentialService, agentId, projectId, track), agentId),
+            this.withConfigMutationMarker(this.withConfigSnapshotOnResume(this.createConfigureChannelTool(agentId, projectId, track), agentId, projectId, (result) => typeof result.configured === 'boolean'), agentId),
+            this.withConfigMutationMarker(this.withConfigSnapshotOnResume(this.createFinishSetupTool(credentialService, agentId, projectId, track), agentId, projectId, (result) => result.completed === true), agentId),
             this.createVerifyMcpServerTool(agentId, credentialProvider, projectId, user),
         ];
         return tools;
@@ -360,7 +439,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildCallAgentTool(user, projectId, agentId, credentialProvider) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.CALL_AGENT)
             .description('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. ' +
-            'Pass the returned sessionId on later calls to continue the same conversation; omit it to start a new one. ' +
+            'Omit sessionId to start a new conversation. To continue one, pass the exact sessionId from an earlier 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.')
@@ -369,9 +449,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             sessionId: zod_1.z
                 .string()
                 .trim()
-                .min(1)
                 .optional()
-                .describe('Session ID from a previous call_agent result'),
+                .describe('Exact sessionId from an earlier call_agent result. Omit it to start a new conversation.'),
         }))
             .suspend(tool_1.APPROVAL_SUSPEND_SCHEMA)
             .resume(tool_1.APPROVAL_RESUME_SCHEMA)
@@ -385,8 +464,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             }
             const previewPath = (0, agent_builder_preview_path_1.buildAgentPreviewPath)(projectId, agentId);
             try {
-                const result = await this.runDraftTest(ctx, agentId, projectId, message, sessionId, credentialProvider, user);
-                return await this.formatDraftTestResult(result, ctx, agentId, user, previewPath);
+                const { result, sessionNote } = await this.runDraftTest(ctx, agentId, projectId, message, sessionId || undefined, credentialProvider, user);
+                return await this.formatDraftTestResult(result, ctx, agentId, user, previewPath, sessionNote);
             }
             catch (error) {
                 if (ctx.abortSignal ? ctx.abortSignal.aborted : (0, agents_1.isAbortError)(error))
@@ -405,31 +484,39 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             .build();
     }
     async runDraftTest(ctx, agentId, projectId, message, sessionId, credentialProvider, user) {
-        let result;
         if (ctx.resumeData === undefined) {
-            result = await this.agentTestRunService.executeDraftRun({
+            const execute = async (id) => await this.agentTestRunService.executeDraftRun({
                 agentId,
                 projectId,
                 message,
-                sessionId,
+                sessionId: id,
                 credentialProvider,
                 user,
                 source: 'instance-ai',
                 ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
             });
+            const result = await execute(sessionId);
+            if (result.status !== 'session_not_found' || sessionId === undefined)
+                return { result };
+            return {
+                result: await execute(undefined),
+                sessionNote: 'The sessionId you passed was not found, so this test started a new conversation. ' +
+                    'To continue this conversation, pass the sessionId from this result.',
+            };
         }
-        else {
-            result = await this.agentTestRunService.resumeDraftApproval({
+        const noted = notedContinuationSchema.safeParse(ctx.continuation);
+        return {
+            result: await this.agentTestRunService.resumeDraftApproval({
                 agentId,
                 projectId,
-                continuation: ctx.continuation,
+                continuation: noted.success ? noted.data.run : ctx.continuation,
                 approved: ctx.resumeData.approved,
                 user,
                 source: 'instance-ai',
                 ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
-            });
-        }
-        return result;
+            }),
+            ...(noted.success ? { sessionNote: noted.data.sessionNote } : {}),
+        };
     }
     buildUnpublishAgentTool(user, projectId, agentId) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.UNPUBLISH_AGENT)
@@ -514,43 +601,37 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
     buildPatchConfigTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.PATCH_CONFIG)
             .description('Apply RFC 6902 JSON Patch operations to the current agent configuration. ' +
-            'Pass an array of patch operations as a JSON string. ' +
-            'Requires baseConfigHash from the immediately preceding agent-context with type "config" result — never from a prior ' +
-            'write_config/patch_config success or from a stale response. ' +
+            '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. ' +
-            'Returns { ok: true, configMutated: true, agentId } on success — no config, hash, or timestamps are returned; call ' +
-            'agent-context with type "config" again before any later inspection or mutation — or ' +
-            '{ ok: false, stage, errors } on failure. ' +
-            'stage is "locked", "parse", "stale", "patch", or "schema". On stage: "stale", call agent-context with type "config" and retry ' +
-            'once using its fresh config and configHash. On stage: "locked", stop and tell the user to close ' +
+            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.')
             .input(zod_1.z.object({
-            operations: zod_1.z.string().describe('RFC 6902 JSON Patch operations array as a JSON string'),
-            baseConfigHash: zod_1.z
-                .string()
-                .nullable()
-                .describe('configHash from the immediately preceding agent-context with type "config" result; null only if no config exists'),
+            operations: zod_1.z
+                .preprocess(parseJsonStringInput, zod_1.z.array(jsonPatchOperationSchema))
+                .describe('RFC 6902 JSON Patch 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))
             .build();
     }
     buildWriteConfigTool(agentId, projectId, user) {
         return new tool_1.Tool(builder_tool_names_1.BUILDER_TOOLS.WRITE_CONFIG)
-            .description('Create or replace the agent configuration by writing a complete JSON string. ' +
-            'Requires baseConfigHash from the immediately preceding agent-context with type "config" result — never from a prior ' +
-            'write_config/patch_config success or from a stale response. ' +
-            'Returns { ok: true, configMutated: true, agentId } on success — no config, hash, or timestamps are returned; call ' +
-            'agent-context with type "config" again before any later inspection or mutation — or ' +
-            '{ ok: false, stage, errors } with path, message, expected, received fields on failure. ' +
-            'On stage: "stale", call agent-context with type "config" and retry once using its fresh config and configHash.')
-            .input(zod_1.z.object({
-            json: zod_1.z.string().describe('Complete agent configuration as a JSON string'),
-            baseConfigHash: zod_1.z
-                .string()
-                .nullable()
-                .describe('configHash from the immediately preceding agent-context with type "config" result; null only if no config exists'),
-        }))
-            .handler(async ({ json, baseConfigHash }) => await this.writeBuilderConfig(agentId, projectId, user, json, baseConfigHash))
+            .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.')
+            .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'),
+            baseConfigHash: zod_1.z.string().nullable().describe(BASE_CONFIG_HASH_FIELD_DESCRIPTION),
+        })))
+            .handler(async ({ config, baseConfigHash }) => await this.writeBuilderConfig(agentId, projectId, user, config, baseConfigHash))
             .build();
     }
     getSharedTools(agentId, projectId, credentialProvider, user) {
@@ -589,8 +670,10 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             '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 `publish_agent`. Returns { ok: true, configMutated: true, agentId, tasks: [{ id, name, enabled }, ...] } (same ' +
-            'order as input, objectives and crons are not echoed back) or { ok: false, errors }.')
+            'the agent is (re)published via `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 ' +
@@ -631,7 +714,8 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             }
             return {
                 ok: true,
-                tasks: created.map(({ id, name }) => ({ id, name, enabled: true })),
+                configHash: created.configHash,
+                tasks: created.tasks.map(({ id, name }) => ({ id, name, enabled: true })),
             };
         })
             .build();
@@ -666,23 +750,26 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         return new tool_1.Tool(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. Pass null for allowedTools to remove the tool restriction, or null ' +
-            'for references to remove all references; empty arrays are invalid. Returns ' +
-            '{ ok: true, id, name, configMutated: true, agentId } or { ok: false, errors }. On a stale ' +
-            'skill error, call agent-context with type "skill" and retry once with its fresh skillHash.')
+            'result. To change part of the body, pass instructionEdits with oldText/newText pairs ' +
+            'instead of rewriting instructions. Pass null for allowedTools to remove the tool restriction, ' +
+            'or null for references to remove all references; empty arrays are invalid. 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.')
             .input(updateSkillInputSchema)
             .handler(async ({ skillId, baseSkillHash, updates }) => {
             const editorLock = await this.getEditorLockFailure(agentId);
             if (editorLock)
                 return editorLock;
-            const { allowedTools, references, ...requiredUpdates } = updates;
+            const { allowedTools, references, instructionEdits, ...requiredUpdates } = updates;
             const normalizedUpdates = {
                 ...requiredUpdates,
                 ...(allowedTools !== undefined ? { allowedTools: allowedTools ?? undefined } : {}),
                 ...(references !== undefined ? { references: references ?? undefined } : {}),
             };
             try {
-                const updated = await this.agentSkillsService.updateSkill(agentId, projectId, skillId, normalizedUpdates, { user, modifiedBy: 'builder' }, baseSkillHash);
+                const updated = await this.agentSkillsService.updateSkill(agentId, projectId, skillId, normalizedUpdates, { user, modifiedBy: 'builder' }, baseSkillHash, instructionEdits);
                 return {
                     ok: true,
                     id: updated.id,
@@ -706,10 +793,11 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             '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. This does NOT attach the skills to the ' +
-            'agent config; follow up with agent-context with type "config" and patch_config (or write_config) to add a ' +
-            '`{ type: "skill", id }` entry per skill to `skills`. Returns { ok: true, skills: [{ id, name }, ' +
-            '...] } (same order as input, bodies are not echoed back) or { ok: false, errors }.')
+            '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 ' +
@@ -733,13 +821,11 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             if (editorLock)
                 return editorLock;
             try {
-                const created = await this.agentSkillsService.createSkills(agentId, projectId, skills, {
-                    user,
-                    modifiedBy: 'builder',
-                });
+                const created = await this.agentSkillsService.createAndAttachSkills(agentId, projectId, skills, { user, modifiedBy: 'builder' });
                 return {
                     ok: true,
-                    skills: created.map(({ id, skill }) => ({ id, name: skill.name })),
+                    configHash: created.configHash,
+                    skills: created.skills.map(({ id, skill }) => ({ id, name: skill.name })),
                 };
             }
             catch (e) {
@@ -790,7 +876,7 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         const agent = await this.agentsService.findById(agentId, projectId);
         if (!agent)
             throw new Error('Agent not found');
-        const config = (0, agent_config_composition_1.composeJsonConfig)(agent);
+        const config = (0, agent_config_composition_1.composeJsonConfig)(agent, await this.agentSkillRefs.refsForDraft(agent, {}));
         return snapshotFromConfig(config);
     }
     async applyCredentialToMcpServer(agentId, projectId, serverName, credentialId, user) {
@@ -819,17 +905,14 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
             throw new Error((0, api_types_1.formatZodErrors)(zodResult.error)[0]?.message ?? 'Invalid MCP server config');
         }
         const configWithDefaults = applyPromptCachingBuilderDefaults((0, agent_config_1.applyNativeWebSearchDefaultOn)(zodResult.data));
-        await this.agentConfigService.updateConfig(agentId, projectId, configWithDefaults, user, {
-            baseConfigHash: snapshot.configHash,
-            modifiedBy: 'builder',
-        });
-        return { applied: true };
+        const saved = await this.agentConfigService.updateConfig(agentId, projectId, configWithDefaults, user, { baseConfigHash: snapshot.configHash, modifiedBy: 'builder' });
+        return { applied: true, config: saved.config, configHash: saved.configHash };
     }
     async getFreshConfigSnapshot(agentId, projectId, baseConfigHash) {
         try {
             const snapshot = await this.getConfigSnapshot(agentId, projectId);
             if (baseConfigHash !== snapshot.configHash) {
-                return { ok: false, stage: 'stale', errors: [STALE_CONFIG_ERROR] };
+                return { ok: false, stage: 'stale', errors: [STALE_CONFIG_ERROR], ...snapshot };
             }
             return { ok: true, snapshot };
         }
@@ -857,43 +940,53 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         const config = applyPromptCachingBuilderDefaults((0, agent_config_1.applyNativeWebSearchDefaultOn)(parsed.data));
         return { ok: true, config };
     }
-    async saveBuilderConfig(agentId, projectId, user, config, baseConfigHash, clearOmittedOptionalFields = false) {
+    async saveBuilderConfig(agentId, projectId, user, config, baseConfigHash, submitted, clearOmittedOptionalFields = false) {
         try {
-            await this.agentConfigService.updateConfig(agentId, projectId, config, user, {
+            const saved = await this.agentConfigService.updateConfig(agentId, projectId, config, user, {
                 baseConfigHash,
                 clearOmittedOptionalFields,
                 modifiedBy: 'builder',
             });
-            return { ok: true };
+            return {
+                ok: true,
+                configHash: saved.configHash,
+                ...((0, agent_config_hash_1.isSameAgentConfig)(saved.config, submitted) ? {} : { config: saved.config }),
+            };
         }
         catch (e) {
+            const errors = [{ path: '(root)', message: e instanceof Error ? e.message : String(e) }];
+            if (!(e instanceof errors_1.ConflictError))
+                return { ok: false, stage: 'schema', errors };
+            const current = await this.getConfigSnapshot(agentId, projectId).catch(() => null);
             return {
                 ok: false,
-                stage: e instanceof errors_1.ConflictError ? 'stale' : 'schema',
-                errors: [{ path: '(root)', message: e instanceof Error ? e.message : String(e) }],
+                stage: 'stale',
+                errors: current ? [STALE_CONFIG_ERROR] : errors,
+                ...(current ?? {}),
             };
         }
     }
-    async writeBuilderConfig(agentId, projectId, user, json, baseConfigHash) {
+    async writeBuilderConfig(agentId, projectId, user, input, baseConfigHash) {
         const editorLock = await this.getEditorLockFailure(agentId);
         if (editorLock)
             return editorLock;
-        const parsed = (0, api_types_1.tryParseConfigJson)(json);
+        const parsed = readStructuredToolInput(input);
         if (!parsed.ok)
             return { ok: false, errors: parsed.errors };
         const fresh = await this.getFreshConfigSnapshot(agentId, projectId, baseConfigHash);
         if (!fresh.ok)
             return fresh;
-        const validated = this.validateBuilderConfig(parsed.data, fresh.snapshot.config);
+        const merged = mergeOmittedTopLevelFields(parsed.data, fresh.snapshot.config);
+        const validated = this.validateBuilderConfig(merged, fresh.snapshot.config);
         if (!validated.ok)
             return validated;
-        return await this.saveBuilderConfig(agentId, projectId, user, validated.config, fresh.snapshot.configHash);
+        return await this.saveBuilderConfig(agentId, projectId, user, validated.config, fresh.snapshot.configHash, merged);
     }
     async patchBuilderConfig(agentId, projectId, user, operations, baseConfigHash) {
         const editorLock = await this.getEditorLockFailure(agentId);
         if (editorLock)
             return { ...editorLock, stage: 'locked' };
-        const parsed = (0, api_types_1.tryParseConfigJson)(operations);
+        const parsed = readStructuredToolInput(operations);
         if (!parsed.ok)
             return { ok: false, stage: 'parse', errors: parsed.errors };
         const fresh = await this.getFreshConfigSnapshot(agentId, projectId, baseConfigHash);
@@ -912,7 +1005,7 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         const validated = this.validateBuilderConfig(patched.config, fresh.snapshot.config);
         if (!validated.ok)
             return { ...validated, stage: 'schema' };
-        return await this.saveBuilderConfig(agentId, projectId, user, validated.config, fresh.snapshot.configHash, true);
+        return await this.saveBuilderConfig(agentId, projectId, user, validated.config, fresh.snapshot.configHash, patched.config, true);
     }
     async applyConfigPatch(operations, config) {
         const jsonpatch = (await import('fast-json-patch')).default;
@@ -928,14 +1021,15 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
         }
         return { ok: true, config: jsonpatch.applyPatch(jsonpatch.deepClone(config), ops).newDocument };
     }
-    async formatDraftTestResult(result, ctx, agentId, user, previewPath) {
+    async formatDraftTestResult(result, ctx, agentId, user, previewPath, sessionNote) {
         if (result.status === 'session_not_found') {
             return {
                 status: 'error',
                 code: 'session_not_found',
-                message: 'Session not found.',
+                message: 'This test session is no longer available. Call call_agent again without sessionId to start a new test.',
             };
         }
+        const note = sessionNote ? { sessionNote } : {};
         if (result.status === 'agent_misconfigured') {
             return {
                 status: 'error',
@@ -955,17 +1049,23 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
                 sessionId: result.sessionId,
                 response: result.response,
                 ...(result.executionId ? { executionId: result.executionId } : {}),
+                ...note,
             };
         }
         if (result.status === 'completed')
-            return result;
+            return { ...result, ...note };
         const approvals = (0, agent_test_run_service_1.collectStandardApprovals)(result);
         const firstApproval = approvals?.[0];
         if (firstApproval) {
             const { continuation, ...approval } = firstApproval;
-            return await ctx.suspend(approval, { continuation });
+            return await ctx.suspend(approval, {
+                continuation: sessionNote ? { run: continuation, sessionNote } : continuation,
+            });
         }
-        return await this.cancelUnsupportedDraftTest(result, agentId, user, previewPath);
+        return {
+            ...(await this.cancelUnsupportedDraftTest(result, agentId, user, previewPath)),
+            ...note,
+        };
     }
     async cancelUnsupportedDraftTest(result, agentId, user, previewPath) {
         const cancelled = await this.agentTestRunService.cancelSuspendedRuns({
@@ -1004,6 +1104,6 @@ let AgentsBuilderToolsService = class AgentsBuilderToolsService {
 exports.AgentsBuilderToolsService = AgentsBuilderToolsService;
 exports.AgentsBuilderToolsService = AgentsBuilderToolsService = __decorate([
     (0, di_1.Service)(),
-    __metadata("design:paramtypes", [backend_common_1.Logger, agents_service_1.AgentsService, agent_config_service_1.AgentConfigService, agent_custom_tools_service_1.AgentCustomToolsService, agent_integration_persistence_service_1.AgentIntegrationPersistenceService, agent_skills_service_1.AgentSkillsService, agent_secure_runtime_1.AgentSecureRuntime, agents_tools_service_1.AgentsToolsService, builder_model_live_lookup_service_1.BuilderModelLiveLookupService, mcp_registry_service_1.McpRegistryService, oauth_service_1.OauthService, credential_types_1.CredentialTypes, agent_task_service_1.AgentTaskService, agent_publish_service_1.AgentPublishService, agent_test_run_service_1.AgentTestRunService, ai_service_1.AiService, ai_gateway_service_1.AiGatewayService, backend_network_1.OutboundHttp, dynamic_node_parameters_service_1.DynamicNodeParametersService, node_types_1.NodeTypes, free_ai_credits_service_1.FreeAiCreditsService, telemetry_1.Telemetry, instance_ai_agent_context_adapter_1.InstanceAiAgentContextAdapterService, collaboration_service_1.CollaborationService])
+    __metadata("design:paramtypes", [backend_common_1.Logger, agents_service_1.AgentsService, agent_config_service_1.AgentConfigService, agent_custom_tools_service_1.AgentCustomToolsService, agent_integration_persistence_service_1.AgentIntegrationPersistenceService, agent_skills_service_1.AgentSkillsService, agent_secure_runtime_1.AgentSecureRuntime, agents_tools_service_1.AgentsToolsService, builder_model_live_lookup_service_1.BuilderModelLiveLookupService, mcp_registry_service_1.McpRegistryService, oauth_service_1.OauthService, credential_types_1.CredentialTypes, agent_task_service_1.AgentTaskService, agent_publish_service_1.AgentPublishService, agent_test_run_service_1.AgentTestRunService, ai_service_1.AiService, ai_gateway_service_1.AiGatewayService, backend_network_1.OutboundHttp, dynamic_node_parameters_service_1.DynamicNodeParametersService, node_types_1.NodeTypes, free_ai_credits_service_1.FreeAiCreditsService, telemetry_1.Telemetry, instance_ai_agent_context_adapter_1.InstanceAiAgentContextAdapterService, collaboration_service_1.CollaborationService, agent_skill_refs_service_1.AgentSkillRefsService])
 ], AgentsBuilderToolsService);
 //# sourceMappingURL=agents-builder-tools.service.js.map