callman-mcp 0.4.0 → 0.6.0

package/dist-cjs/tools/scenarioAdmin.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerScenarioAdminTools = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const lookups_js_1 = require("./lookups.js");
+const scenarios_js_1 = require("./scenarios.js");
+const shared_js_1 = require("./shared.js");
+// Scenario folders and the on-prem review workflow (approve / reject, the
+// approved-version history) — what the desktop's scenario sidebar and Review
+// Mode do, for AI tools. list_scenarios already returns the folders.
+const versionsOf = (raw) => (Array.isArray(raw) ? raw : (raw.items ?? []));
+const versionRow = (version) => ({
+    version: version.versionNumber,
+    name: version.name,
+    savedVersion: version.scenarioSaveVersion,
+    active: version.isActive,
+    submittedBy: version.submittedByLabel,
+    submittedAt: version.submittedAt,
+    approvedBy: version.approvedByLabel,
+    approvedAt: version.approvedAt,
+});
+const cloudOnlyNote = (error) => error instanceof errors_js_1.CallmanApiError && (error.status === 400 || error.status === 404 || error.status === 409) && /cloud|on-prem|onprem/i.test(error.message)
+    ? "Cloud has no review workflow — every save is approved at once."
+    : null;
+const registerScenarioAdminTools = (server, ctx) => {
+    server.registerTool("create_scenario_folder", {
+        title: "Create a scenario folder",
+        description: "Create a folder in the scenario sidebar (flat — folders do not nest). File scenarios into it with create_scenario / update_scenario `folder`. On-prem, `group` binds the folder to one of your scenario groups.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            name: zod_1.z.string().trim().min(1).max(120),
+            group: zod_1.z.string().max(200).optional().describe('On-prem: the scenario group (name or id from list_scenarios `groups`, or "personal")'),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, name, group }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const targetGroup = await (0, scenarios_js_1.resolveGroup)(ctx, ws.id, group);
+        const created = await ctx.api.createScenarioFolder(ws.id, { name, ...(targetGroup && targetGroup.id !== null ? { groupId: targetGroup.id } : {}) });
+        ctx.invalidate("scenarios:");
+        return (0, shared_js_1.ok)({ folder: { id: created.id, name: created.name }, ...(targetGroup?.note ? { warnings: [targetGroup.note] } : {}) });
+    }));
+    server.registerTool("update_scenario_folder", {
+        title: "Rename a scenario folder",
+        description: "Rename a scenario folder (id or name).",
+        inputSchema: { workspace: shared_js_1.workspaceArg, folder: (0, shared_js_1.refArg)("Scenario folder"), name: zod_1.z.string().trim().min(1).max(120) },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, folder, name }) => {
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws?.id ?? null, folder);
+        const updated = await ctx.api.updateScenarioFolder(ws?.id ?? null, resolved.item.id, { name });
+        ctx.invalidate("scenarios:");
+        return (0, shared_js_1.ok)({ folder: { id: updated.id ?? resolved.item.id, name: updated.name ?? name }, ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(folder, resolved)] } : {}) });
+    }));
+    server.registerTool("delete_scenario_folder", {
+        title: "Delete a scenario folder",
+        description: "Delete a scenario folder (exact name or id). The scenarios inside are kept and move out of the folder. Confirm with the user first.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, folder: (0, shared_js_1.refArg)("Scenario folder"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, folder, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a scenario folder");
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws?.id ?? null, folder);
+        await ctx.api.deleteScenarioFolder(ws?.id ?? null, resolved.item.id);
+        ctx.invalidate("scenarios:");
+        return (0, shared_js_1.ok)({ deleted: { id: resolved.item.id, name: resolved.item.name }, note: "Its scenarios are now outside any folder." });
+    }));
+    server.registerTool("review_scenario", {
+        title: "Approve or reject a scenario",
+        description: "As an approver (on-prem), approve a scenario waiting for review — its current content becomes the approved version that schedules, pipelines and personal-token runs use — or reject it with a note explaining the changes needed. list_scenario_versions shows the approved history.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            scenario: (0, shared_js_1.refArg)("Scenario"),
+            decision: zod_1.z.enum(["approve", "reject"]),
+            note: zod_1.z.string().trim().max(2000).optional().describe("Required when rejecting"),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, decision, note }) => {
+        if (decision === "reject" && !note)
+            throw new errors_js_1.ToolInputError("NOTE_REQUIRED", "Rejecting needs a note that says what to change.");
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        try {
+            const result = decision === "approve" ? await ctx.api.approveScenario(ws?.id ?? null, resolved.item.id) : await ctx.api.rejectScenario(ws?.id ?? null, resolved.item.id, note);
+            ctx.invalidate("scenarios:");
+            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name, reviewStatus: result.reviewStatus ?? null, approvedVersion: result.approvedVersion ?? null } });
+        }
+        catch (error) {
+            const cloudNote = cloudOnlyNote(error);
+            if (cloudNote)
+                return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, note: cloudNote });
+            throw error;
+        }
+    }));
+    server.registerTool("list_scenario_versions", {
+        title: "Scenario approved versions",
+        description: "The approved versions of a scenario (on-prem): number, who submitted and approved it, when, and which one is ACTIVE (what schedules and personal-token runs execute). With `version`: that version's graph (nodes and edges).",
+        inputSchema: { workspace: shared_js_1.workspaceArg, scenario: (0, shared_js_1.refArg)("Scenario"), version: zod_1.z.number().int().min(1).optional() },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, version }) => {
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        try {
+            if (version !== undefined) {
+                const detail = await ctx.api.getScenarioVersion(ws?.id ?? null, resolved.item.id, version);
+                const nodes = (detail.snapshot?.nodes ?? []);
+                return (0, shared_js_1.ok)({
+                    scenario: { id: resolved.item.id, name: resolved.item.name },
+                    version: versionRow(detail),
+                    graph: { nodes: nodes.map((node) => ({ id: node.id, type: node.type, label: node.data?.label ?? null })), edges: detail.snapshot?.edges ?? [] },
+                });
+            }
+            const items = versionsOf(await ctx.api.listScenarioVersions(ws?.id ?? null, resolved.item.id));
+            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name, version: resolved.item.version }, versions: items.map(versionRow) });
+        }
+        catch (error) {
+            const cloudNote = cloudOnlyNote(error);
+            if (cloudNote)
+                return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, versions: [], note: cloudNote });
+            throw error;
+        }
+    }));
+    server.registerTool("restore_scenario_version", {
+        title: "Restore an approved scenario version",
+        description: "Make an earlier approved version the ACTIVE one again (on-prem; approvers): schedules, pipelines and personal-token runs execute it from now on. The scenario's current content and review status are not changed.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, scenario: (0, shared_js_1.refArg)("Scenario"), version: zod_1.z.number().int().min(1) },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, version }) => {
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        try {
+            await ctx.api.restoreScenarioVersion(ws?.id ?? null, resolved.item.id, version);
+            ctx.invalidate("scenarios:");
+            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, activeVersion: version });
+        }
+        catch (error) {
+            const cloudNote = cloudOnlyNote(error);
+            if (cloudNote)
+                return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, note: cloudNote });
+            throw error;
+        }
+    }));
+};
+exports.registerScenarioAdminTools = registerScenarioAdminTools;

package/dist-cjs/tools/scenarios.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerScenarioTools = void 0;
+exports.registerScenarioTools = exports.resolveGroup = void 0;
 const zod_1 = require("zod");
 const errors_js_1 = require("../client/errors.js");
 const resolve_js_1 = require("../domain/resolve.js");
@@ -43,7 +43,67 @@ const resolveGroup = async (ctx, ws, ref) => {
         return { id: null, note: "Scenario groups exist only on-prem — `group` was ignored." };
     return { id: (0, resolve_js_1.resolveRef)("scenario group", ref, items).item.id };
 };
+exports.resolveGroup = resolveGroup;
 const latestScenario = async (ctx, ws, id) => ctx.api.getScenario(ws, id);
+// The version of each scenario this session last READ or wrote. update_scenario
+// replaces the whole graph, so without an explicit expectedVersion it checks
+// against what the model actually saw — a newer save from the desktop (or a
+// teammate) then comes back as a conflict instead of being overwritten.
+const seenVersions = new WeakMap();
+const rememberVersion = (ctx, scenario) => {
+    if (!scenario.id || typeof scenario.version !== "number")
+        return;
+    let map = seenVersions.get(ctx);
+    if (!map) {
+        map = new Map();
+        seenVersions.set(ctx, map);
+    }
+    map.set(scenario.id, scenario.version);
+};
+const seenVersion = (ctx, id) => seenVersions.get(ctx)?.get(id);
+// scenario-ref nodes name the scenario to link (`config.scenario`: name or
+// id); the server copies it in when the snapshot is empty.
+const resolveScenarioLinks = async (ctx, ws, nodes) => {
+    const out = [];
+    for (const node of nodes) {
+        const ref = node.type.trim() === "scenario-ref" && node.config ? node.config.scenario : undefined;
+        if (typeof ref !== "string" || !ref.trim()) {
+            out.push(node);
+            continue;
+        }
+        const target = await (0, lookups_js_1.resolveScenario)(ctx, ws, ref);
+        const { scenario: _ref, ...rest } = node.config;
+        void _ref;
+        out.push({ ...node, config: { ...rest, referencedScenarioId: target.item.id, nodes: [], edges: [] } });
+    }
+    return out;
+};
+// Labels must be unique across the whole graph; a linked scenario brings its
+// own nodes' labels, which this tool can only check after the server copied
+// them in.
+const labelClashWarnings = (nodes) => {
+    const owners = new Map();
+    const clashes = [];
+    const walk = (list, container) => {
+        for (const node of list) {
+            const label = node.data?.label;
+            if (typeof label === "string" && label) {
+                const where = container ? `${node.id} (inside ${container})` : node.id;
+                const first = owners.get(label);
+                if (first)
+                    clashes.push(`"${label}" is used by ${first} and ${where}`);
+                else
+                    owners.set(label, where);
+            }
+            const inner = node.data?.config?.nodes;
+            if (Array.isArray(inner))
+                walk(inner, container ?? node.id);
+        }
+    };
+    walk(nodes, null);
+    return clashes.length > 0 ? [`Label clash after linking — later nodes read the wrong output until you rename one: ${clashes.join("; ")}.`] : [];
+};
+const hasLink = (graph) => Boolean(graph?.nodes.some((node) => node.type === "scenario-ref" && Array.isArray(node.data.config.nodes) && node.data.config.nodes.length === 0));
 const registerScenarioTools = (server, ctx) => {
     server.registerTool("list_scenarios", {
         title: "List scenarios",
@@ -92,6 +152,7 @@ const registerScenarioTools = (server, ctx) => {
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
         const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
         const fresh = resolved.matched === "id" && !reveal ? resolved.item : await ctx.api.getScenario(ws?.id ?? null, resolved.item.id, reveal ?? false);
+        rememberVersion(ctx, fresh);
         if (node) {
             const found = (0, summarize_js_1.scenarioNodeView)(fresh, node, { reveal });
             if (!found) {
@@ -104,7 +165,7 @@ const registerScenarioTools = (server, ctx) => {
     }));
     server.registerTool("get_scenario_report", {
         title: "Get a scenario run report",
-        description: "The result of a scenario run: status, summary counts, an error outside any node (unexpectedError), a per-node timeline and every failing node expanded (failed tests, assertion checks with expected vs actual, failed contracts, script error with line, the input as resolved at run time, response, logs). `node` returns one node's result in that detail. Defaults to the latest run; `list: true` lists recent runs instead.",
+        description: "The result of a scenario run: status, summary counts, an error outside any node (unexpectedError), a per-node timeline and every failing node expanded (failed tests, assertion checks with expected vs actual, failed contracts, script error with line, the input as resolved at run time, response, logs). `node` returns one node's result in that detail. Defaults to the latest run; `list: true` lists recent runs instead. Covers every run the server knows: server runs, schedules, CLI/pipeline runs, desktop-relay runs (run_scenario target \"desktop\") and runs started in the desktop app (saved there unless the user turned that off) — `triggerType` / `executor` say which.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
@@ -125,7 +186,7 @@ const registerScenarioTools = (server, ctx) => {
             const runs = await ctx.api.listScenarioReports(ws?.id ?? null, resolved.item.id, 5);
             const latest = runs.items[0];
             if (!latest)
-                return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, report: null, note: "This scenario has not been run on the server yet. Use run_scenario." });
+                return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, report: null, note: "No saved runs yet. Use run_scenario (target \"desktop\" for what only the user's machine reaches)." });
             reportId = latest.reportId;
         }
         const detail = await ctx.api.getScenarioReport(ws?.id ?? null, resolved.item.id, reportId);
@@ -151,14 +212,22 @@ const registerScenarioTools = (server, ctx) => {
     }, (0, shared_js_1.guarded)(async ({ workspace, folder, group, dryRun, ...input }) => {
         const ws = await ctx.resolveWorkspace(workspace);
         const targetFolder = folder ? await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws.id, folder) : null;
-        const targetGroup = await resolveGroup(ctx, ws.id, group);
-        const { body, graph } = (0, build_js_1.buildScenarioCreateBody)(input, targetFolder?.item.id ?? null, targetGroup?.id === null ? undefined : targetGroup?.id);
+        const targetGroup = await (0, exports.resolveGroup)(ctx, ws.id, group);
+        const linkedInput = { ...input, nodes: await resolveScenarioLinks(ctx, ws.id, input.nodes) };
+        const { body, graph } = (0, build_js_1.buildScenarioCreateBody)(linkedInput, targetFolder?.item.id ?? null, targetGroup?.id === null ? undefined : targetGroup?.id);
         if (dryRun) {
             return (0, shared_js_1.ok)({ dryRun: true, scenario: { name: body.name, nodes: graph.nodes.map((node) => ({ id: node.id, type: node.type, label: node.data.label, config: node.data.config })), edges: graph.edges }, warnings: graph.warnings });
         }
         const created = await ctx.api.createScenario(ws.id, body);
         ctx.invalidate("scenarios:");
-        const warnings = [...graph.warnings, ...droppedFieldWarnings(graph, created), ...(created.graph?.warnings ?? []), ...(targetGroup?.note ? [targetGroup.note] : [])];
+        rememberVersion(ctx, created);
+        const warnings = [
+            ...graph.warnings,
+            ...droppedFieldWarnings(graph, created),
+            ...(created.graph?.warnings ?? []),
+            ...(targetGroup?.note ? [targetGroup.note] : []),
+            ...(hasLink(graph) ? labelClashWarnings(created.nodes) : []),
+        ];
         return (0, shared_js_1.ok)({
             scenario: (0, summarize_js_1.scenarioGraphView)(created),
             ...(warnings.length > 0 ? { warnings } : {}),
@@ -226,12 +295,12 @@ const registerScenarioTools = (server, ctx) => {
                 }
             }
         }
-        const graph = (0, build_js_1.buildScenarioGraph)([...nodes.values()], edges, { existing: current.nodes });
+        const graph = (0, build_js_1.buildScenarioGraph)(await resolveScenarioLinks(ctx, ws?.id ?? null, [...nodes.values()]), edges, { existing: current.nodes });
         return saveGraph(ctx, ws?.id ?? null, current, graph, { expectedVersion, annotation: resolved.annotation ? (0, resolve_js_1.resolvedSummary)(scenario, resolved) : undefined });
     }));
     server.registerTool("update_scenario", {
         title: "Update a scenario",
-        description: "Update a scenario's name / description / priority / folder / environments / dataset / dbSettings and/or replace its graph (nodes AND edges together). A node whose id already exists MERGES into the stored node (only the config keys you send change, its position is kept); new ids merge over the type's defaults; nodes you leave out are removed. `environments` replaces the whole list (stored ids are kept by name; a masked value sent back unchanged keeps the stored one). For small edits prefer patch_scenario. Version-checked: pass the `version` you read (expectedVersion) or it is fetched first; a conflict comes back structured. On-prem: editing an approved scenario returns it to draft.",
+        description: "Update a scenario's name / description / priority / folder / environments / dataset / dbSettings and/or replace its graph (nodes AND edges together). A node whose id already exists MERGES into the stored node (only the config keys you send change, its position is kept); new ids merge over the type's defaults; nodes you leave out are removed. `environments` replaces the whole list (stored ids are kept by name; a masked value sent back unchanged keeps the stored one). For small edits prefer patch_scenario. Version-checked: a graph replace is checked against the `version` you last read (or expectedVersion) — if someone saved since (e.g. in the desktop app) you get a structured conflict instead of overwriting their work. On-prem: editing an approved scenario returns it to draft.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
@@ -256,7 +325,7 @@ const registerScenarioTools = (server, ctx) => {
         const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
         const current = await latestScenario(ctx, ws?.id ?? null, resolved.item.id);
         const targetFolder = folder ? await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws?.id ?? null, folder) : null;
-        const graph = nodes && edges ? (0, build_js_1.buildScenarioGraph)(nodes, edges, { existing: current.nodes }) : null;
+        const graph = nodes && edges ? (0, build_js_1.buildScenarioGraph)(await resolveScenarioLinks(ctx, ws?.id ?? null, nodes), edges, { existing: current.nodes }) : null;
         const extra = {
             ...(name !== undefined ? { name } : {}),
             ...(description !== undefined ? { description } : {}),
@@ -268,7 +337,9 @@ const registerScenarioTools = (server, ctx) => {
         };
         if (!graph && Object.keys(extra).length === 0)
             throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass at least one field to change.");
-        return saveGraph(ctx, ws?.id ?? null, current, graph, { expectedVersion, force, extra, annotation: resolved.annotation ? (0, resolve_js_1.resolvedSummary)(scenario, resolved) : undefined });
+        // A whole-graph replace checks against the version this session read.
+        const checkedVersion = expectedVersion ?? (graph ? seenVersion(ctx, current.id) : undefined);
+        return saveGraph(ctx, ws?.id ?? null, current, graph, { expectedVersion: checkedVersion, force, extra, annotation: resolved.annotation ? (0, resolve_js_1.resolvedSummary)(scenario, resolved) : undefined });
     }));
     server.registerTool("submit_scenario", {
         title: "Submit a scenario for approval",
@@ -310,17 +381,18 @@ const registerScenarioTools = (server, ctx) => {
         return (0, shared_js_1.ok)({ deleted: { id: resolved.item.id, name: resolved.item.name }, resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] });
     }));
     server.registerTool("run_scenario", {
-        title: "Run a scenario on the server",
-        description: "Start a server-side run of a scenario (with one of its inline environments, by name or id; the first one when omitted) and wait for the result (default up to 5 minutes, max 30). Returns the report as in get_scenario_report. A personal token runs the scenario's APPROVED version on-prem — the result says when that differs from the version you edited. If it times out you get the reportId to check later.",
+        title: "Run a scenario",
+        description: "Run a scenario (with one of its inline environments, by name or id; the first one when omitted) and wait for the result (default up to 5 minutes, max 30). Returns the report as in get_scenario_report. WHERE it runs matters: target \"server\" (default) runs on the Callman server, which reaches only what the server's network reaches — not the user's localhost, port-forwards, VPN-only hosts or internal databases. target \"desktop\" runs it on the user's own Callman desktop app (it must be open and signed in with Settings → AI tools → \"Let AI tools run scenarios on this computer\" on) — use it for local Kafka, local or internal databases and anything only that machine reaches. A personal token runs the scenario's APPROVED version on-prem (either target) — the result says when that differs from the version you edited. If it times out you get the reportId to check later.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
+            target: zod_1.z.enum(["server", "desktop"]).default("server").describe('"server" (default) or "desktop" — the user\'s own desktop app, for what only their machine reaches'),
             environment: zod_1.z.string().max(200).optional().describe("One of the scenario's own environments (name or id)"),
             wait: zod_1.z.boolean().default(true),
             timeoutSec: zod_1.z.number().int().min(5).max(1800).default(300),
         },
         annotations: shared_js_1.RUN,
-    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, environment, wait, timeoutSec }) => {
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, target, environment, wait, timeoutSec }) => {
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
         const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
         let environmentId;
@@ -333,9 +405,19 @@ const registerScenarioTools = (server, ctx) => {
             }
             environmentId = picked.id;
         }
-        const trigger = await ctx.api.runScenario(ws?.id ?? null, resolved.item.id, environmentId ? { environmentId } : {});
+        const runBody = environmentId ? { environmentId } : {};
+        let trigger;
+        try {
+            trigger = target === "desktop" ? await ctx.api.runScenarioOnDesktop(ws?.id ?? null, resolved.item.id, runBody) : await ctx.api.runScenario(ws?.id ?? null, resolved.item.id, runBody);
+        }
+        catch (error) {
+            if (target === "desktop" && error instanceof errors_js_1.CallmanApiError && error.status === 404 && error.code !== "SCENARIO_NOT_FOUND") {
+                throw new errors_js_1.ToolInputError("SCENARIO_DESKTOP_UNSUPPORTED", "This Callman server cannot run scenarios on a desktop yet (update the backend), so only target \"server\" works.");
+            }
+            throw error;
+        }
         if (!wait)
-            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, reportId: trigger.reportId, status: trigger.status, note: "Check with get_scenario_report." });
+            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, reportId: trigger.reportId, status: trigger.status, target, note: "Check with get_scenario_report." });
         const deadline = Date.now() + timeoutSec * 1000;
         let polls = 0;
         let last = null;
@@ -354,7 +436,15 @@ const registerScenarioTools = (server, ctx) => {
                 break;
         }
         if (!last || !TERMINAL_STATUSES.has(last.status)) {
-            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, reportId: trigger.reportId, status: last?.status ?? "running", timedOut: true, note: `Still running after ${timeoutSec}s — call get_scenario_report with this reportId later.` });
+            return (0, shared_js_1.ok)({
+                scenario: { id: resolved.item.id, name: resolved.item.name },
+                reportId: trigger.reportId,
+                status: last?.status ?? "running",
+                timedOut: true,
+                note: target === "desktop" && (last?.status ?? "queued") === "queued"
+                    ? `No desktop picked the run up within ${timeoutSec}s — the app must be open with "Let AI tools run scenarios on this computer" on. It is failed automatically after 10 minutes; check with get_scenario_report.`
+                    : `Still running after ${timeoutSec}s — call get_scenario_report with this reportId later.`,
+            });
         }
         const warnings = [];
         if (typeof last.scenarioVersion === "number" && last.scenarioVersion !== resolved.item.version) {
@@ -379,7 +469,13 @@ const saveGraph = async (ctx, ws, current, graph, options) => {
     try {
         const updated = await ctx.api.patchScenario(ws, current.id, body);
         ctx.invalidate("scenarios:");
-        const warnings = [...(graph?.warnings ?? []), ...(graph ? droppedFieldWarnings(graph, updated) : []), ...(updated.graph?.warnings ?? [])];
+        rememberVersion(ctx, updated);
+        const warnings = [
+            ...(graph?.warnings ?? []),
+            ...(graph ? droppedFieldWarnings(graph, updated) : []),
+            ...(updated.graph?.warnings ?? []),
+            ...(hasLink(graph) ? labelClashWarnings(updated.nodes) : []),
+        ];
         const removed = graph ? current.nodes.filter((node) => !graph.nodes.some((entry) => entry.id === node.id)).map((node) => node.id) : [];
         return (0, shared_js_1.ok)({
             scenario: (0, summarize_js_1.scenarioGraphView)(updated),

package/dist-cjs/tools/shared.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireConfirm = exports.dryRunArg = exports.confirmArg = exports.cursorArgs = exports.refArg = exports.workspaceArg = exports.RUN = exports.DESTRUCTIVE = exports.IDEMPOTENT_WRITE = exports.WRITE = exports.READ = exports.guarded = exports.failureOf = exports.toolFailure = exports.ok = void 0;
+exports.requireConfirm = exports.dryRunArg = exports.confirmArg = exports.cursorArgs = exports.refArg = exports.workspaceArg = exports.RUN = exports.DESTRUCTIVE = exports.IDEMPOTENT_WRITE = exports.WRITE = exports.READ = exports.guarded = exports.failureOf = exports.toolFailure = exports.okWithImages = exports.ok = void 0;
 const zod_1 = require("zod");
 const errors_js_1 = require("../client/errors.js");
 const truncate_js_1 = require("../lib/truncate.js");
@@ -17,6 +17,17 @@ const ok = (structured, text) => ({
     structuredContent: structured,
 });
 exports.ok = ok;
+// `ok` plus MCP image blocks (screenshots): the structured result stays JSON,
+// each image follows as { type: "image", data: <base64>, mimeType } preceded
+// by a one-line caption so the model knows which is which.
+const okWithImages = (structured, images) => {
+    const result = (0, exports.ok)(structured);
+    for (const image of images) {
+        result.content.push({ type: "text", text: image.caption }, { type: "image", data: image.data, mimeType: image.mimeType });
+    }
+    return result;
+};
+exports.okWithImages = okWithImages;
 const toolFailure = (error) => {
     let payload;
     if (error instanceof errors_js_1.CallmanApiError) {