@codesys/mcp-toolkit 1.5.8 → 2.0.0-alpha.0

package/dist/tools.js

@@ -0,0 +1,793 @@
+/** The CODESYS actions (ST only), all behind the one model-facing tool. See actions.ts. */
+import { copyFile } from "node:fs/promises";
+import { registerActionTool } from "./actions.js";
+import { getUiCapability } from "@modelcontextprotocol/ext-apps/server";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import * as z from "zod/v4";
+import { BridgeError } from "./bridge/bridge.js";
+import { buildOutline, ioList } from "./codesys/outline.js";
+import { describeDevices, parseIoMappingCsv, shortVariable } from "./codesys/devices.js";
+import { diffObjects, formatDiff, lineDiff, snapshot } from "./codesys/changes.js";
+import { parseDeclaration } from "./codesys/decl.js";
+import { browseCacheFile, describeBrowse, newestLibrary, readBrowseCache } from "./codesys/library-browse.js";
+import { registerCodesysSim } from "./codesys/simulation.js";
+import { heldMessage } from "./driver.js";
+import { checkDeclaration, kindLabel, normalizeText } from "./codesys/st.js";
+const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError } : {}) });
+async function run(ctx, fn) {
+    try {
+        if (!(await ctx.bridge.waitReady(ctx.startWaitMs))) {
+            const h = ctx.bridge.health();
+            const secs = h.startedAt ? Math.round((Date.now() - Date.parse(h.startedAt)) / 1000) : 0;
+            return text(`CODESYS is still starting (${secs}s so far; a cold start takes 1-3 minutes). Call the tool again shortly, or check codesys_status.`, true);
+        }
+        return text(await fn());
+    }
+    catch (e) {
+        if (e instanceof BridgeError)
+            return text(`${e.code}: ${e.message}`, true);
+        return text(`error: ${e.message}`, true);
+    }
+}
+const pathArg = z.string().describe("Object path relative to the application, e.g. 'PLC_PRG', 'FB_Pump/Start', 'FB_Pump/Speed/Get'. Prefix '/' for a path from the project root.");
+function absPath(ctx, p) {
+    return isAbsolute(p) ? p : resolvePath(ctx.workspace, p);
+}
+function formatObject(o) {
+    if (o.error)
+        return `=== ${o.path} ===\nerror: ${o.error}`;
+    const parts = [`=== ${o.path} (${kindLabel(o)}) ===`];
+    if (o.declaration !== undefined)
+        parts.push("--- declaration ---", normalizeText(o.declaration).replace(/\n+$/, ""));
+    if (o.implementation !== undefined)
+        parts.push("--- implementation ---", normalizeText(o.implementation).replace(/\n+$/, ""));
+    else if (o.st === false)
+        parts.push("--- implementation ---", "(graphical body: SFC/CFC/LD/FBD; not editable as ST)");
+    return parts.join("\n");
+}
+const CREATE_TO_NODE = {
+    program: { kind: "pou", sub: "program" },
+    function_block: { kind: "pou", sub: "function_block" },
+    function: { kind: "pou", sub: "function" },
+    method: { kind: "method" },
+    property: { kind: "property" },
+    action: { kind: "action" },
+    interface: { kind: "interface" },
+    dut: { kind: "dut" },
+    gvl: { kind: "gvl" },
+    folder: { kind: "folder" },
+};
+/** " Compiler 3.5.21.0. Defines: FAST, MODE." plus a note when CODESYS is newer than the project. */
+export function describeBuildSettings(r, codesysLabel) {
+    const out = [];
+    if (r.compiler_version) {
+        const label = codesysLabel?.replace(/^CODESYS\s*/i, "");
+        const installed = /(\d+\.\d+\.\d+)\.\d+/.exec(codesysLabel ?? "")?.[1];
+        const key = (v) => v.split(".").slice(0, 3).map((n) => n.padStart(4, "0")).join(".");
+        const compared = installed ? key(r.compiler_version).localeCompare(key(installed)) : 0;
+        if (compared > 0)
+            out.push(`Compiler version ${r.compiler_version}, which this CODESYS (${label}) doesn't have: the project won't compile here. Open it in CODESYS ${r.compiler_version.split(".").slice(0, 3).join(".")} or later.`);
+        else
+            out.push(`Compiler version ${r.compiler_version}${compared < 0 ? ` (this CODESYS is ${label}; the project keeps its version unless you update it in CODESYS)` : ""}.`);
+    }
+    if (r.defines?.length)
+        out.push(`Compiler defines: ${r.defines.join(", ")}.`);
+    if (r.project_defines?.length)
+        out.push(`Project defines: ${r.project_defines.join(", ")}.`);
+    return out.length ? ` ${out.join(" ")}` : "";
+}
+/** Which CODESYS a session uses, for the panel: "CODESYS 3.5.22.40 · Scripting 4.2.0.0 · compiler 3.5.19.40". */
+export function versionLine(codesysLabel, scripting, compiler) {
+    return [codesysLabel, scripting && `Scripting ${scripting}`, compiler && `compiler ${compiler}`].filter(Boolean).join(" · ");
+}
+/**
+ * The useful part of CODESYS's PLCopenXML export of one object: its <pou> (or <dataType>)
+ * element, without the vendor <addData> blocks (GUID-coded attributes, layout data).
+ */
+export function compactPlcOpen(xml) {
+    const start = xml.search(/<(pou|dataType)\s/);
+    let body = xml;
+    if (start >= 0) {
+        const tag = /<(pou|dataType)\s/.exec(xml.slice(start))[1];
+        const end = xml.indexOf(`</${tag}>`, start);
+        body = end > start ? xml.slice(start, end + tag.length + 3) : xml.slice(start);
+    }
+    return body
+        .replace(/<addData>[\s\S]*?<\/addData>\s*/g, "")
+        .replace(/^\s*\n/gm, "")
+        .trim();
+}
+/** One line per task, as list_tasks and configure_task show it. */
+export function describeTask(t) {
+    const interval = t.interval ? `, interval ${t.interval}${t.interval_unit && !/[a-z]/i.test(t.interval) ? " " + t.interval_unit : ""}` : "";
+    const wd = t.watchdog?.enabled ? `, watchdog ${t.watchdog.time ?? "?"}${t.watchdog.time && /[a-z]/i.test(t.watchdog.time) ? "" : ` ${t.watchdog.time_unit ?? ""}`.trimEnd()} ×${t.watchdog.sensitivity ?? "1"}` : "";
+    return (`${t.name}: ${t.kind ?? "?"}${interval}${t.priority ? `, priority ${t.priority}` : ""}${t.event ? `, event ${t.event}` : ""}` +
+        `${typeof t.core_binding === "number" && t.core_binding >= 0 ? `, core ${t.core_binding}` : ""}${wd}; calls ${t.pous.join(", ") || "nothing"}`);
+}
+export function formatBuild(messages) {
+    const isErr = (m) => /error/i.test(m.severity);
+    const isWarn = (m) => /warning/i.test(m.severity);
+    const errs = messages.filter(isErr);
+    const warns = messages.filter(isWarn);
+    const line = (m) => {
+        const code = m.prefix ? `${m.prefix}${m.number ?? ""}` : "";
+        const where = m.object ? `${m.object}${m.position ? ` (${m.position})` : ""}` : "";
+        return `${isErr(m) ? "ERROR" : "WARNING"}${code ? " " + code : ""}${where ? " " + where : ""}: ${m.text}`;
+    };
+    const out = [`Build: ${errs.length} error(s), ${warns.length} warning(s).`];
+    for (const m of [...errs, ...warns])
+        out.push(line(m));
+    if (!errs.length)
+        out.push("Note: CODESYS only compiles POUs reachable from a task; unreferenced POUs are not checked.");
+    return { text: out.join("\n"), errors: errs.length };
+}
+export function registerTools(server, ctx) {
+    const b = ctx.bridge;
+    /** Tools that change the project are held while the user has paused Claude (panel). */
+    const HELD = new Set(["write_object", "create_object", "delete_object", "rename_object", "revert_object", "add_library", "remove_library", "configure_task", "create_project", "open_project", "close_project", "codesys_sim_start", "codesys_sim_stop", "codesys_sim_control", "codesys_sim_cycle", "codesys_sim_write", "codesys_sim_force", "codesys_sim_unforce"]);
+    const actions = new Map();
+    const reg = (name, config, cb) => {
+        actions.set(name, {
+            ...config,
+            run: async (args) => {
+                if (HELD.has(name) && ctx.driver?.held)
+                    return text(heldMessage(ctx.driver, name), true);
+                ctx.driver?.note(name); // the panel picks its view from what Claude does
+                return cb(args);
+            },
+        });
+    };
+    const cache = ctx.cache;
+    /** Export all ST (and keep the workspace cache current). */
+    const exportNodes = async () => {
+        const nodes = (await b.call("export", {}, { timeoutMs: 120_000 })).nodes;
+        cache?.setAll(nodes);
+        return nodes;
+    };
+    /** Re-read one object into the cache after a change (best effort). */
+    const refresh = async (path, action) => {
+        if (!cache)
+            return;
+        try {
+            const o = (await b.call("objects.read", { paths: [path] })).objects[0];
+            if (o && !o.error)
+                cache.upsert(o);
+        }
+        catch {
+            /* the cache is best effort */
+        }
+        cache.touch(path, action);
+    };
+    /**
+     * After opening a project: fill the cache with one export, and take the
+     * session-start checkpoint from it the first time in this process.
+     */
+    const sessionStart = async (project) => {
+        cache?.reset(project);
+        // The card is the only live view that opens by itself; its Open workspace button expands it.
+        const shown = getUiCapability(server.server.getClientCapabilities()) ? " Call open_sim_panel now so the user can watch the project tree and the code as you write it." : "";
+        if (!cache && !ctx.changes)
+            return shown;
+        let nodes;
+        try {
+            nodes = await exportNodes();
+        }
+        catch {
+            return shown;
+        }
+        if (!ctx.changes)
+            return shown;
+        const taken = await ctx.changes.sessionStart(project, async () => nodes);
+        return (taken ? " Checkpoint 'session-start' saved (get_changes shows what changes from here)." : "") + shown;
+    };
+    const save = () => ({ save: ctx.autosave });
+    const savedNote = (r) => (r.saved ? " Project saved." : ctx.autosave ? "" : " (not saved; call save_project)");
+    reg("codesys_status", {
+        description: "Show the CODESYS connection state, installation and open project. Never waits on CODESYS, so it is safe while CODESYS starts or is busy.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const h = b.health();
+        const lines = [
+            `CODESYS: ${ctx.codesys ? `${ctx.codesys.label} (profile "${ctx.codesys.profile}")${h.scripting ? `, Scripting ${h.scripting}` : ""}` : "unknown"}`,
+            `Bridge: ${h.state} / ${h.verdict}${h.pid ? `, pid ${h.pid}` : ""}${h.readyAfterMs ? `, started in ${Math.round(h.readyAfterMs / 1000)}s` : ""}, ${h.calls} call(s), ${h.restarts} restart(s)`,
+        ];
+        if (h.heartbeat)
+            lines.push(`Watcher: ${h.heartbeat.state}${h.heartbeat.op ? ` (${h.heartbeat.op})` : ""}, heartbeat ${Math.round(h.heartbeat.ageMs / 1000)}s ago`);
+        if (h.lastError)
+            lines.push(`Last error: ${h.lastError}`);
+        lines.push(ctx.project ? `Project (last opened): ${ctx.project.path}, application ${ctx.project.application ?? "none"}.${describeBuildSettings(ctx.project, ctx.codesys?.label)}` : "Project: none opened in this session");
+        if (h.sessionDir)
+            lines.push(`Session folder: ${h.sessionDir}`);
+        return text(lines.join("\n"));
+    });
+    reg("open_project", {
+        description: "Open a CODESYS .project file, or a .projectarchive (extracted next to the archive, or to extractTo; an existing project is never overwritten). All other tools work on the open project. Refuses to drop unsaved changes in a different open project unless discardChanges is true. Projects are opened without version upgrades.",
+        inputSchema: z.object({
+            path: z.string().describe("Path to the .project or .projectarchive file (absolute, or relative to the workspace)"),
+            discardChanges: z.boolean().optional(),
+            extractTo: z.string().optional().describe("For an archive: the .project file to extract to (default: next to the archive)"),
+        }),
+    }, async ({ path, discardChanges, extractTo }) => run(ctx, async () => {
+        const r = await b.call("project.open", { path: absPath(ctx, path), discard_changes: !!discardChanges, ...(extractTo ? { extract_to: absPath(ctx, extractTo) } : {}) }, { timeoutMs: 300_000 });
+        ctx.project = r;
+        const cp = await sessionStart(r.path);
+        const from = r.extracted_from ? ` (extracted from ${r.extracted_from})` : "";
+        return `${r.reused ? "Already open" : "Opened"}: ${r.path}${from}. Active application: ${r.application ?? "none"}.${describeBuildSettings(r, ctx.codesys?.label)}${cp}`;
+    }));
+    reg("create_project", {
+        description: "Create a new CODESYS project and open it. template 'standard' copies CODESYS's Standard.project (device + application + PLC_PRG) and brings the new copy up to this CODESYS's device and compiler; 'empty' creates an empty project; any other value is a path to a template .project file, used as it is.",
+        inputSchema: z.object({
+            path: z.string().describe("New .project file path"),
+            template: z.string().optional().describe("'standard' (default), 'empty', or a template file path"),
+        }),
+    }, async ({ path, template }) => run(ctx, async () => {
+        const target = absPath(ctx, path);
+        if (existsSync(target))
+            throw new Error(`File already exists: ${target}`);
+        const t = template ?? "standard";
+        if (t === "empty") {
+            const r = await b.call("project.create_empty", { path: target }, { timeoutMs: 120_000 });
+            ctx.project = { path: r.path, application: r.application };
+            await sessionStart(r.path);
+            return `Created empty project ${r.path}.`;
+        }
+        const src = t === "standard" ? (ctx.templatesDir ? join(ctx.templatesDir, "Standard.project") : "") : absPath(ctx, t);
+        if (!src || !existsSync(src))
+            throw new Error(`Template not found: ${src || "this install has no Templates folder with a Standard.project"}. Pass template as the path of a .project file to copy, or 'empty'.`);
+        await copyFile(src, target);
+        // CODESYS's own template can be years old; a new project should match this CODESYS.
+        const r = await b.call(t === "standard" ? "project.open_new" : "project.open", { path: target }, { timeoutMs: 300_000 });
+        ctx.project = r;
+        await sessionStart(r.path);
+        return `Created ${r.path} from ${t === "standard" ? "Standard.project" : src}. Active application: ${r.application ?? "none"}.${describeBuildSettings(r, ctx.codesys?.label)}${r.updated_device ? ` Device updated to ${r.updated_device}.` : ""} Run compile to check that its libraries are installed.`;
+    }));
+    reg("save_project", {
+        description: "Save the open project. Pass archive to also write a .projectarchive (e.g. a snapshot before a big change); an existing file is never overwritten.",
+        inputSchema: z.object({ archive: z.string().optional().describe("Path of a .projectarchive to write as well") }),
+    }, async ({ archive }) => run(ctx, async () => {
+        const r = await b.call("project.save", archive ? { archive: absPath(ctx, archive) } : {}, { timeoutMs: 300_000 });
+        return `Saved ${r.path}.${r.archive ? ` Archive written: ${r.archive}.` : ""}`;
+    }));
+    reg("close_project", {
+        description: "Close the open project. Refuses when there are unsaved changes unless discardChanges is true.",
+        inputSchema: z.object({ discardChanges: z.boolean().optional() }),
+    }, async ({ discardChanges }) => run(ctx, async () => {
+        const r = await b.call("project.close", { discard_changes: !!discardChanges });
+        ctx.project = undefined;
+        cache?.reset();
+        return r.closed ? "Project closed." : "No project was open.";
+    }));
+    reg("get_project_tree", {
+        description: "List the objects of the open project's application (or a sub-tree) with their kinds. Objects with graphical bodies (SFC/CFC/LD/FBD) are marked [non-ST]; v2 reads and edits ST only.",
+        inputSchema: z.object({
+            root: pathArg.optional().describe("Sub-tree to list (default: the active application)"),
+            wholeProject: z.boolean().optional().describe("List from the project root (devices, pool) instead of the application"),
+            maxDepth: z.number().int().min(0).optional(),
+        }),
+    }, async ({ root, wholeProject, maxDepth }) => run(ctx, async () => {
+        const r = await b.call("tree", { root, whole_project: !!wholeProject, max_depth: maxDepth ?? null });
+        const head = root ? `Tree under ${root}:` : wholeProject ? "Project tree:" : `Application ${r.application ?? "?"} (paths are relative to it):`;
+        const lines = r.nodes.map((n) => `${"  ".repeat(n.depth)}${n.name}  [${kindLabel(n)}]${n.st === false ? " [non-ST]" : ""}${n.build?.excluded ? " [excluded from build]" : ""}`);
+        return [head, ...(lines.length ? lines : ["(empty)"])].join("\n");
+    }));
+    reg("read_objects", {
+        description: "Read the declaration and implementation text of ST objects: POUs, methods, property accessors (path 'FB/Prop/Get'), actions, interfaces, DUTs and GVLs. Objects with a graphical body (SFC, CFC, LD, FBD) come with their PLCopenXML, to read (they stay read-only).",
+        inputSchema: z.object({ paths: z.array(pathArg).min(1).max(50) }),
+    }, async ({ paths }) => run(ctx, async () => {
+        const r = await b.call("objects.read", { paths });
+        if (cache) {
+            for (const o of r.objects)
+                if (!o.error)
+                    cache.upsert(o);
+            const last = r.objects.filter((o) => !o.error).at(-1);
+            if (last)
+                cache.touch(last.path, "read");
+        }
+        const graphical = r.objects.filter((o) => !o.error && o.st === false).map((o) => o.path);
+        const xml = new Map();
+        if (graphical.length) {
+            const x = await b.call("objects.xml", { paths: graphical }, { timeoutMs: 180_000 }).catch(() => ({ objects: [] }));
+            for (const o of x.objects)
+                if (o.xml)
+                    xml.set(o.path, `${compactPlcOpen(o.xml)}${o.truncated ? "\n(truncated)" : ""}`);
+        }
+        return r.objects.map((o) => formatObject(o) + (xml.has(o.path) ? `\n--- graphical body as PLCopenXML (read-only) ---\n${xml.get(o.path)}` : "")).join("\n\n");
+    }));
+    reg("write_object", {
+        description: "Replace the declaration and/or implementation text of an ST object. The declaration must keep the object's header (e.g. 'FUNCTION_BLOCK FB_Pump', 'METHOD Start : BOOL'); a GVL declaration starts with VAR_GLOBAL; property accessors hold only VAR blocks.",
+        inputSchema: z.object({
+            path: pathArg,
+            declaration: z.string().optional(),
+            implementation: z.string().optional(),
+            skipHeaderCheck: z.boolean().optional().describe("Skip the header check (only if you know CODESYS accepts the change)"),
+        }),
+    }, async ({ path, declaration, implementation, skipHeaderCheck }) => run(ctx, async () => {
+        if (declaration === undefined && implementation === undefined)
+            throw new Error("Give declaration and/or implementation.");
+        if (declaration !== undefined && !skipHeaderCheck) {
+            const cur = (await b.call("objects.read", { paths: [path] })).objects[0];
+            if (!cur || cur.error)
+                throw new Error(cur?.error ?? `No object ${path}`);
+            const problem = checkDeclaration(cur.kind, cur.sub, cur.name, declaration);
+            if (problem)
+                throw new Error(problem);
+        }
+        const r = await b.call("object.write", { path, declaration, implementation, ...save() });
+        await refresh(r.path, "write");
+        return `Updated ${r.path} (${[declaration !== undefined && "declaration", implementation !== undefined && "implementation"].filter(Boolean).join(" + ")}).${savedNote(r)}`;
+    }));
+    reg("create_object", {
+        description: "Create an ST object. kind: program | function_block | function (needs returnType) | method (under a POU or interface) | property (needs returnType) | action | interface | dut (dutType struct|enum|union|alias) | gvl | folder. Optionally set its declaration/implementation in the same call.",
+        inputSchema: z.object({
+            parent: pathArg.optional().describe("Parent object path (default: the application). Methods/properties/actions go under their POU."),
+            kind: z.enum(["program", "function_block", "function", "method", "property", "action", "interface", "dut", "gvl", "folder"]),
+            name: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "must be an IEC identifier"),
+            returnType: z.string().optional(),
+            dutType: z.enum(["struct", "enum", "union", "alias"]).optional(),
+            baseInterfaces: z.string().optional().describe("Interfaces to extend, comma separated (interfaces only)"),
+            declaration: z.string().optional(),
+            implementation: z.string().optional(),
+        }),
+    }, async (a) => run(ctx, async () => {
+        if (a.declaration !== undefined) {
+            const n = CREATE_TO_NODE[a.kind];
+            const problem = checkDeclaration(n.kind, n.sub, a.name, a.declaration);
+            if (problem)
+                throw new Error(problem);
+        }
+        const r = await b.call("object.create", {
+            parent: a.parent,
+            kind: a.kind,
+            name: a.name,
+            return_type: a.returnType,
+            dut_type: a.dutType,
+            base_interfaces: a.baseInterfaces,
+            declaration: a.declaration,
+            implementation: a.implementation,
+            ...save(),
+        });
+        await refresh(r.path, "create");
+        return `Created ${a.kind} ${r.path}.${savedNote(r)}`;
+    }));
+    reg("delete_object", { description: "Delete an object (and its children).", inputSchema: z.object({ path: pathArg }) }, async ({ path }) => run(ctx, async () => {
+        const r = await b.call("object.delete", { path, ...save() });
+        cache?.remove(r.path);
+        cache?.touch(r.path, "delete");
+        return `Deleted ${r.path}.${savedNote(r)}`;
+    }));
+    reg("rename_object", {
+        description: "Rename an object. References in other code are NOT updated; search_code for the old name afterwards.",
+        inputSchema: z.object({ path: pathArg, newName: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/) }),
+    }, async ({ path, newName }) => run(ctx, async () => {
+        const r = await b.call("object.rename", { path, new_name: newName, ...save() });
+        cache?.rename(path.replace(/^\/+/, ""), newName);
+        cache?.touch(r.path, "rename");
+        return `Renamed to ${r.path}.${savedNote(r)}`;
+    }));
+    reg("search_code", {
+        description: "Search all ST text (declarations and implementations) of the application. Returns path, part and line for each hit.",
+        inputSchema: z.object({
+            pattern: z.string().min(1),
+            regex: z.boolean().optional(),
+            caseSensitive: z.boolean().optional(),
+            maxResults: z.number().int().min(1).max(500).optional(),
+        }),
+    }, async ({ pattern, regex, caseSensitive, maxResults }) => run(ctx, async () => {
+        const re = new RegExp(regex ? pattern : pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), caseSensitive ? "" : "i");
+        const r = { nodes: await exportNodes() };
+        const hits = [];
+        const limit = maxResults ?? 50;
+        let total = 0;
+        for (const n of r.nodes) {
+            for (const [part, body] of [["decl", n.declaration], ["impl", n.implementation]]) {
+                if (!body)
+                    continue;
+                normalizeText(body).split("\n").forEach((l, i) => {
+                    if (re.test(l)) {
+                        total++;
+                        if (hits.length < limit)
+                            hits.push(`${n.path} [${part}]:${i + 1}: ${l.trim().slice(0, 200)}`);
+                    }
+                });
+            }
+        }
+        if (!total)
+            return `No matches for ${regex ? "/" + pattern + "/" : JSON.stringify(pattern)}.`;
+        return [`${total} match(es)${total > hits.length ? `, showing ${hits.length}` : ""}:`, ...hits].join("\n");
+    }));
+    reg("compile", {
+        description: [
+            "Build the active application and return errors and warnings with object and line.",
+            "A plain build only compiles POUs a task reaches; check_all (default true) also checks every other POU, so new code that nothing calls yet is checked too.",
+            "deep: also generate code, which finds errors the build alone doesn't (slower). clean: build from scratch.",
+        ].join(" "),
+        inputSchema: z.object({
+            check_all: z.boolean().optional().describe("Also check POUs no task calls (default true)"),
+            deep: z.boolean().optional().describe("Also generate code (default false)"),
+            clean: z.boolean().optional().describe("Clean first, for a build from scratch (default false)"),
+        }),
+    }, async ({ check_all, deep, clean }) => run(ctx, async () => {
+        const r = await b.call("build", { check_all: check_all ?? true, deep: !!deep, clean: !!clean }, { timeoutMs: 900_000 });
+        const f = formatBuild(r.messages);
+        if (cache) {
+            const counted = r.messages.filter((m) => /error|warning/i.test(m.severity));
+            cache.setCompile({
+                at: new Date().toISOString(),
+                errors: f.errors,
+                warnings: counted.length - f.errors,
+                messages: counted.map((m) => ({ severity: /error/i.test(m.severity) ? "error" : "warning", text: m.text, object: m.object, position: m.position, ...(m.length ? { length: m.length } : {}), ...(m.prefix ? { code: `${m.prefix}${m.number ?? ""}` } : {}) })),
+            });
+        }
+        const checked = r.steps?.includes("check_all") ? " Checked every POU, including those no task calls." : "";
+        return `${f.text}${checked}${r.steps?.includes("generate_code") ? " Code generated." : ""}`;
+    }));
+    reg("list_libraries", { description: "List the libraries referenced by the application's Library Manager.", inputSchema: z.object({}) }, async () => run(ctx, async () => {
+        const r = await b.call("libraries.list");
+        if (!r.libraries.length)
+            return "No libraries referenced.";
+        return r.libraries
+            .map((l) => `${l.name}${l.is_placeholder ? " (placeholder)" : ""}${l.namespace ? `, namespace ${l.namespace}` : ""}${l.effective_resolution ? ` -> ${l.effective_resolution}` : ""}`)
+            .join("\n");
+    }));
+    reg("remove_library", {
+        description: "Remove a library reference from the application's Library Manager, by its full name as list_libraries shows it, or by its name alone (e.g. 'Util').",
+        inputSchema: z.object({ name: z.string().min(1) }),
+    }, async ({ name }) => run(ctx, async () => {
+        const r = await b.call("libraries.remove", { name, ...save() });
+        return `Removed library ${r.removed}.${savedNote(r)}`;
+    }));
+    reg("add_library", {
+        description: "Add a library reference by its title, e.g. 'Util', or its full name, e.g. 'Util, 3.5.17.0 (System)'. A bare title takes the newest installed version unless you pass version. The library must be installed in the CODESYS library repository.",
+        inputSchema: z.object({ name: z.string().min(1), version: z.string().optional().describe("With a bare title: a specific version, e.g. '3.5.17.0'") }),
+    }, async ({ name, version }) => run(ctx, async () => {
+        const r = await b.call("libraries.add", { name, ...(version ? { version } : {}), ...save() });
+        return `Added library ${r.added}.${savedNote(r)}`;
+    }));
+    reg("list_tasks", { description: "List the application's tasks with interval, priority and the POUs each one calls.", inputSchema: z.object({}) }, async () => run(ctx, async () => {
+        const r = await b.call("tasks.list");
+        if (!r.tasks.length)
+            return "No tasks found. Create one with configure_task.";
+        return r.tasks.map(describeTask).join("\n");
+    }));
+    reg("configure_task", {
+        description: [
+            "Create or change a task in the application's task configuration, and which programs it calls.",
+            "A PROGRAM that no task calls never runs, and a plain compile doesn't check it: add it to a task with add_calls.",
+            "Settings: kind (cyclic, freewheeling, event, external_event, status), interval with its unit (e.g. 't#10ms'), priority (0 = highest),",
+            "event (the BOOL variable that triggers an event task), core_binding, and the watchdog (enabled, time, time_unit, sensitivity).",
+            "Only names a program; FBs and functions run from inside programs.",
+        ].join(" "),
+        inputSchema: z.object({
+            name: z.string().min(1).describe("Task name, e.g. 'MainTask'"),
+            create: z.boolean().optional().describe("Create the task (and the task configuration) if it doesn't exist"),
+            kind: z.enum(["cyclic", "freewheeling", "event", "external_event", "status"]).optional(),
+            interval: z.string().optional().describe("Cycle time for a cyclic task, e.g. 't#10ms'"),
+            interval_unit: z.string().optional().describe("Unit for the interval field, e.g. 'ms' or 'us'"),
+            priority: z.union([z.string(), z.number()]).optional().describe("0 (highest) to 31"),
+            event: z.string().optional().describe("Event task: the BOOL variable whose rising edge starts it"),
+            core_binding: z.number().int().min(0).optional(),
+            watchdog: z
+                .object({ enabled: z.boolean().optional(), time: z.string().optional(), time_unit: z.string().optional(), sensitivity: z.union([z.string(), z.number()]).optional() })
+                .optional(),
+            add_calls: z.array(z.string().min(1)).optional().describe("Programs the task should call (appended in this order)"),
+            remove_calls: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Programs the task should no longer call. CODESYS V3.5 SP21's scripting can't remove a call: the tool then says so, and the user removes it in CODESYS"),
+        }),
+    }, async (a) => run(ctx, async () => {
+        const r = await b.call("task.configure", {
+            ...a,
+            ...(a.priority !== undefined ? { priority: String(a.priority) } : {}),
+            ...(a.watchdog?.sensitivity !== undefined ? { watchdog: { ...a.watchdog, sensitivity: String(a.watchdog.sensitivity) } } : {}),
+            ...save(),
+        });
+        if (r.created)
+            await exportNodes().catch(() => undefined); // the tree has a new task
+        cache?.touch(r.path, r.created ? "create" : "write");
+        return `${r.created ? "Created" : "Updated"} task ${describeTask(r)}${savedNote(r)}`;
+    }));
+    reg("get_outline", {
+        description: "Outline of the project without reading every object: tasks and what they run, then each POU with its interface (inputs, outputs, methods, properties, actions), interfaces, DUTs (enum members, struct fields), GVLs and tests. Pass path for one object in detail (all variables with types, initial values, AT addresses and comments; method signatures) or for one folder.",
+        inputSchema: z.object({
+            path: pathArg.optional().describe("An object (details) or a folder (its overview). Omit for the whole application."),
+        }),
+    }, async ({ path }) => run(ctx, async () => {
+        const [e, t] = [{ nodes: await exportNodes() }, await b.call("tasks.list")];
+        return buildOutline(e.nodes, t.tasks, { path });
+    }));
+    reg("get_io_list", {
+        description: "Variables mapped to I/O (AT %I, %Q, %M addresses, including the %I* / %Q* placeholders that the device tree maps), with type, owner (GVL or POU) and comment. Filter by text in the name, address or comment.",
+        inputSchema: z.object({ filter: z.string().optional() }),
+    }, async ({ filter }) => run(ctx, async () => {
+        const e = { nodes: await exportNodes() };
+        let io = ioList(e.nodes);
+        if (filter) {
+            const f = filter.toLowerCase();
+            io = io.filter((x) => `${x.owner}.${x.name} ${x.at} ${x.comment ?? ""}`.toLowerCase().includes(f));
+        }
+        const group = (d, label) => {
+            const xs = io.filter((x) => x.direction === d);
+            return xs.length ? [`${label} (${xs.length}):`, ...xs.map((x) => `  ${x.at.padEnd(9)} ${x.owner}.${x.name} : ${x.type}${x.comment ? ` // ${x.comment}` : ""}`)] : [];
+        };
+        // Channels mapped to variables in the device tree (not in the ST).
+        const devices = (await b.call("devices.list", { io: true }, { timeoutMs: 180_000 }).catch(() => ({ devices: [] }))).devices;
+        let mapped = devices.flatMap((d) => (d.io_csv ? parseIoMappingCsv(d.io_csv) : [])).filter((c) => c.variable);
+        if (filter) {
+            const f = filter.toLowerCase();
+            mapped = mapped.filter((c) => `${c.variable} ${c.address} ${c.description} ${c.device}`.toLowerCase().includes(f));
+        }
+        if (!io.length && !mapped.length)
+            return filter ? `No I/O variables match '${filter}'.` : "No variables with AT addresses and no device-tree mappings in the project.";
+        const placeholders = io.filter((x) => x.placeholder).length;
+        return [
+            ...group("input", "Inputs"),
+            ...group("output", "Outputs"),
+            ...group("memory", "Memory"),
+            ...(mapped.length ? [`Mapped in the device tree (${mapped.length}):`, ...mapped.map((c) => `  ${(c.address || "-").padEnd(9)} ${shortVariable(c.variable)}  <- ${c.device} ${c.parameter}${c.description ? ` ${c.description}` : ""}`)] : []),
+            ...(placeholders && !mapped.length ? [`${placeholders} placeholder(s) (%I* / %Q*): no device maps them yet.`] : []),
+        ].join("\n");
+    }));
+    reg("get_devices", {
+        description: "The device tree: each device with its identification (type, id, version) and whether it is enabled, and its I/O channels with address, description and the variable mapped to each (from CODESYS's I/O mapping export). Read-only; never goes online.",
+        inputSchema: z.object({ io: z.boolean().optional().describe("Include I/O channels (default true)") }),
+    }, async ({ io }) => run(ctx, async () => {
+        const r = await b.call("devices.list", { io: io ?? true }, { timeoutMs: 180_000 });
+        return describeDevices(r.devices);
+    }));
+    const libCache = new Map();
+    /** A source library read from CODESYS, or the browse cache of a compiled or unreferenced one. */
+    const readLibrary = async (name, version) => {
+        let lib;
+        if (!version) {
+            try {
+                lib = await b.call("library.api", { name }, { timeoutMs: 180_000 });
+            }
+            catch (e) {
+                if (!(e instanceof BridgeError && e.code === "not_found"))
+                    throw e; // not referenced: look in the repositories below
+            }
+        }
+        if (lib && !lib.compiled)
+            return { ...lib, nodes: lib.nodes.map((n) => ({ ...n, path: n.path.replace(/^\/+/, "") })) };
+        const found = await b.call("library.find", { name: lib?.title ?? name }, { timeoutMs: 180_000 });
+        const candidates = version ? found.matches.filter((m) => m.version === version) : lib ? found.matches.filter((m) => m.version === lib.version && m.company === lib.company) : found.matches;
+        const match = newestLibrary(candidates);
+        const file = match && browseCacheFile(found.repositories, match);
+        if (match && file)
+            return { library: lib?.library ?? `${match.title}, ${match.version} (${match.company})`, path: file, ...match, compiled: true, nodes: [], browse: readBrowseCache(file) };
+        if (lib)
+            return lib;
+        throw new Error(`No installed library '${name}'${version ? ` with version ${version}` : ""}. Installed versions: ${found.matches.map((m) => m.version).join(", ") || "none"}.`);
+    };
+    reg("get_library_api", {
+        description: "What a library offers. For a source library the project references (.library): the real interface of its function blocks, functions, DUTs and GVLs (inputs, outputs, methods, types). For a compiled library, or one the project doesn't reference yet: its objects with their descriptions from CODESYS's library browser, without parameters. Pass symbol for one object, or to search names and descriptions.",
+        inputSchema: z.object({
+            name: z.string().describe("Library, e.g. 'Util' or 'Util, * (System)'"),
+            symbol: z.string().optional().describe("One object in the library, e.g. 'BLINK', or text to search for"),
+            version: z.string().optional().describe("A specific installed version, e.g. '3.5.17.0' (default: the one referenced, else the newest)"),
+        }),
+    }, async ({ name, symbol, version }) => run(ctx, async () => {
+        const key = `${name}|${version ?? ""}`.toLowerCase();
+        let lib = libCache.get(key);
+        if (!lib) {
+            lib = await readLibrary(name, version);
+            libCache.set(key, lib);
+        }
+        const head = `${lib.library}${lib.title ? ` (${lib.title}${lib.version ? ` ${lib.version}` : ""}${lib.company ? `, ${lib.company}` : ""})` : ""}`;
+        if (lib.browse)
+            return describeBrowse(head, lib.browse, symbol);
+        if (lib.compiled)
+            return `${head} is a compiled library (${lib.path}). Its declarations can't be read by scripting; check the library's documentation in CODESYS, or test calls with compile.`;
+        if (symbol) {
+            const hit = lib.nodes.find((n) => n.name.toLowerCase() === symbol.toLowerCase() && ["pou", "dut", "gvl", "interface"].includes(n.kind));
+            if (!hit)
+                return `${head} has no object '${symbol}'.`;
+            return `${head}\n${buildOutline(lib.nodes, [], { path: hit.path })}`;
+        }
+        return `${head}\n${buildOutline(lib.nodes, [], { maxLines: 300 })}`;
+    }));
+    // ---------------------------------------------------------------- changes
+    const store = () => {
+        if (!ctx.changes)
+            throw new Error("Change tracking is not enabled.");
+        if (!ctx.project)
+            throw new Error("No project is open. Call open_project first.");
+        return { store: ctx.changes, project: ctx.project.path };
+    };
+    reg("checkpoint", {
+        description: "Save a named snapshot of all ST in the project, to compare against (get_changes) or go back to (revert_object). A 'session-start' checkpoint is taken automatically when a project is opened. Without a name, lists the checkpoints.",
+        inputSchema: z.object({ name: z.string().regex(/^[A-Za-z0-9_.-]+$/, "letters, digits, _ . -").optional() }),
+    }, async ({ name }) => run(ctx, async () => {
+        const { store: s, project } = store();
+        if (!name) {
+            const list = await s.list(project);
+            return list.length ? list.map((c) => `${c.name}  ${c.at}  (${c.objects} objects)`).join("\n") : "No checkpoints yet.";
+        }
+        const cp = await s.save(project, name, await exportNodes());
+        return `Checkpoint '${name}' saved (${cp.objects.length} objects).`;
+    }));
+    reg("get_changes", {
+        description: "What changed in the project's ST since a checkpoint (default 'session-start'): added, removed and modified objects with line counts. Pass path for the line diff of one object (declaration and implementation, with line numbers).",
+        inputSchema: z.object({ since: z.string().optional(), path: pathArg.optional() }),
+    }, async ({ since, path }) => run(ctx, async () => {
+        const { store: s, project } = store();
+        const name = since ?? "session-start";
+        const cp = await s.load(project, name);
+        if (!cp) {
+            const list = await s.list(project);
+            return `No checkpoint '${name}'.${list.length ? ` Checkpoints: ${list.map((c) => c.name).join(", ")}.` : ""}`;
+        }
+        const now = snapshot(await exportNodes());
+        if (path) {
+            const key = path.replace(/^\/+/, "").toLowerCase();
+            const old = cp.objects.find((o) => o.path.toLowerCase() === key);
+            const cur = now.find((o) => o.path.toLowerCase() === key);
+            if (!old && !cur)
+                return `No object '${path}' now or in '${name}'.`;
+            const out = [`${cur?.path ?? old.path}: ${!old ? "added" : !cur ? "removed" : "compared"} since '${name}' (${cp.at})`];
+            for (const [label, a, bb] of [
+                ["declaration", old?.declaration, cur?.declaration],
+                ["implementation", old?.implementation, cur?.implementation],
+            ]) {
+                const ops = lineDiff(normalizeText(a ?? "").replace(/\s+$/, ""), normalizeText(bb ?? "").replace(/\s+$/, ""));
+                if (ops.every((o) => o.op === " "))
+                    continue;
+                out.push(`--- ${label}`, ...formatDiff(ops));
+            }
+            if (out.length === 1)
+                out.push("No changes.");
+            return out.join("\n");
+        }
+        const changes = diffObjects(cp.objects, now);
+        if (!changes.length)
+            return `No changes since '${name}' (${cp.at}).`;
+        const counts = (x) => (x ? `+${x.plus} -${x.minus}` : "");
+        return [
+            `${changes.length} change(s) since '${name}' (${cp.at}):`,
+            ...changes.map((c) => {
+                const mark = c.change === "added" ? "A" : c.change === "removed" ? "D" : "M";
+                const detail = c.change === "modified" ? ` (${[c.decl && `declaration ${counts(c.decl)}`, c.impl && `implementation ${counts(c.impl)}`].filter(Boolean).join(", ")})` : "";
+                return `${mark} ${c.path} [${c.kind}]${detail}`;
+            }),
+            "Pass path to see one object's diff; revert_object puts it back.",
+        ].join("\n");
+    }));
+    reg("revert_object", {
+        description: "Put an object (and everything under it, e.g. an FB with its methods and properties) back to how it was at a checkpoint (default 'session-start'): modified objects are rewritten, objects added since are deleted, removed ones are recreated.",
+        inputSchema: z.object({ path: pathArg, to: z.string().optional() }),
+    }, async ({ path, to }) => run(ctx, () => revertObject(ctx, path, to ?? "session-start")));
+    reg("wait", {
+        description: "Pause, usually inside a batch: the simulation runs at real speed, so a step like codesys_sim_force, wait, codesys_sim_cycle, codesys_sim_read lets a timer elapse.",
+        inputSchema: z.object({ ms: z.number().int().min(1).max(60_000).describe("How long, in milliseconds (at most 60000)") }),
+    }, async ({ ms }) => {
+        await new Promise((r) => setTimeout(r, ms));
+        return text(`Waited ${ms} ms.`);
+    });
+    reg("open_workspace", {
+        description: "Open the live CODESYS workspace in the user's browser: the project tree, the code as you write it, compile problems and the changes to review. Call this only when the user asks for it there.",
+        inputSchema: z.object({}),
+    }, async () => {
+        if (!ctx.viewer)
+            return text("The browser workspace is switched off (--no-viewer).", true);
+        ctx.viewer.open(true);
+        return text(`The live CODESYS workspace opened in the user's browser: ${ctx.viewer.url} (if they don't see it, give them this link).`);
+    });
+    registerCodesysSim(ctx, {
+        reg,
+        run: (fn) => run(ctx, fn),
+        compileErrors: async () => {
+            const f = formatBuild((await b.call("build", {}, { timeoutMs: 900_000 })).messages);
+            return f.errors ? f.text : undefined;
+        },
+    });
+    registerActionTool(server, actions);
+}
+/**
+ * Put an object (and everything under it) back to how it was at a checkpoint:
+ * modified objects are rewritten, objects added since are deleted, removed
+ * ones are recreated. Used by revert_object and by the panel's Revert.
+ */
+export async function revertObject(ctx, path, name) {
+    if (!ctx.changes)
+        throw new Error("Change tracking is not enabled.");
+    if (!ctx.project)
+        throw new Error("No project is open. Call open_project first.");
+    const s = ctx.changes;
+    const project = ctx.project.path;
+    const b = ctx.bridge;
+    const cache = ctx.cache;
+    const exportNodes = async () => {
+        const nodes = (await b.call("export", {}, { timeoutMs: 120_000 })).nodes;
+        cache?.setAll(nodes);
+        return nodes;
+    };
+    const cp = await s.load(project, name);
+    if (!cp)
+        throw new Error(`No checkpoint '${name}'.`);
+    const key = path.replace(/^\/+/, "").toLowerCase();
+    const inTree = (o) => o.path.toLowerCase() === key || o.path.toLowerCase().startsWith(key + "/");
+    const old = cp.objects.filter(inTree);
+    const now = snapshot(await exportNodes()).filter(inTree);
+    if (!old.length && !now.length)
+        throw new Error(`No object '${path}' now or in '${name}'.`);
+    const oldBy = new Map(old.map((o) => [o.path.toLowerCase(), o]));
+    const nowBy = new Map(now.map((o) => [o.path.toLowerCase(), o]));
+    const done = [];
+    const same = (a, c) => (normalizeText(a ?? "") ?? "").replace(/\s+$/, "") === (normalizeText(c ?? "") ?? "").replace(/\s+$/, "");
+    // 1. delete what was added (top-most only; children go with their parent)
+    const added = now.filter((o) => !oldBy.has(o.path.toLowerCase()));
+    for (const o of added) {
+        if (added.some((p) => o.path.toLowerCase().startsWith(p.path.toLowerCase() + "/")))
+            continue;
+        await b.call("object.delete", { path: o.path, save: false });
+        done.push(`deleted ${o.path}`);
+    }
+    // 2. recreate what was removed (parents first) and rewrite what changed
+    const ordered = [...old].sort((x, y) => x.path.split("/").length - y.path.split("/").length);
+    const imported = [];
+    const under = (p, q) => p.toLowerCase().startsWith(q.toLowerCase() + "/");
+    for (const o of ordered) {
+        if (imported.some((q) => under(o.path, q)))
+            continue; // came back with its graphical parent
+        const cur = nowBy.get(o.path.toLowerCase());
+        if (!cur && o.st === false) {
+            // A graphical body has no text to write: re-import it from the checkpoint's PLCopenXML.
+            if (!o.xml)
+                throw new Error(`${o.path} has a graphical body, and checkpoint '${name}' holds no copy of it (taken before graphical objects were saved). Restore it in CODESYS.`);
+            const parent = o.path.includes("/") ? o.path.slice(0, o.path.lastIndexOf("/")) : undefined;
+            await b.call("object.import_xml", { parent, xml: o.xml, save: false }, { timeoutMs: 120_000 });
+            imported.push(o.path);
+            done.push(`recreated ${o.path} (graphical, from its PLCopenXML)`);
+            continue;
+        }
+        if (!cur) {
+            if (o.kind === "accessor") {
+                // created with its property; write its text below
+            }
+            else {
+                const parent = o.path.includes("/") ? o.path.slice(0, o.path.lastIndexOf("/")) : undefined;
+                const header = parseDeclaration(o.declaration).header;
+                const kind = o.kind === "pou" ? o.sub : o.kind === "interface_method" ? "method" : o.kind;
+                await b.call("object.create", {
+                    parent,
+                    kind,
+                    name: o.name,
+                    return_type: header.returnType,
+                    dut_type: o.kind === "dut" ? o.sub : undefined,
+                    base_interfaces: o.kind === "interface" ? "" : undefined,
+                    declaration: o.kind === "folder" ? undefined : o.declaration,
+                    implementation: o.implementation,
+                    save: false,
+                });
+                done.push(`recreated ${o.path}`);
+                continue;
+            }
+        }
+        if (o.kind === "folder")
+            continue;
+        const args = { path: o.path, save: false };
+        if (o.declaration !== undefined && !same(o.declaration, cur?.declaration))
+            args.declaration = o.declaration;
+        if (o.implementation !== undefined && !same(o.implementation, cur?.implementation))
+            args.implementation = o.implementation;
+        if (args.declaration === undefined && args.implementation === undefined)
+            continue;
+        await b.call("object.write", args);
+        done.push(`restored ${o.path}`);
+    }
+    if (!done.length)
+        return `${path} is already as it was at '${name}'.`;
+    let saved = "";
+    if (ctx.autosave) {
+        await b.call("project.save");
+        saved = " Project saved.";
+    }
+    if (cache) {
+        await exportNodes().catch(() => undefined);
+        cache.touch(path.replace(/^\/+/, ""), "revert");
+    }
+    return `Reverted ${path} to '${name}' (${cp.at}): ${done.join(", ")}.${saved}`;
+}
+//# sourceMappingURL=tools.js.map