agentic-numerical-control 0.1.6 → 0.2.0

package/dist/server/server.js

@@ -1,16 +1,33 @@
 import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer, } from "@modelcontextprotocol/server";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { z } from "zod";
-import { currentJob, jobSummary, jobsDir, listJobFiles, loadJobFile, loadJobFromCncjs, loadJobText, parsedLineAt, } from "./jobs.js";
+import { currentJob, deleteJobFile, jobFileInfo, jobSummary, jobsDir, listJobFiles, loadJobFile, loadJobFromCncjs, loadJobText, parsedLineAt, } from "./jobs.js";
 import { PRODUCT, ROOT, VERSION } from "./product.js";
-import { CNCJS_URL, cncjs } from "./cncjs.js";
+import { cncjs } from "./cncjs.js";
+import { forgetRun, lastRun, recordRun } from "./history.js";
+import { analyzeGcode } from "./analysis.js";
+import { listMachines, machineName, recordMachine, recordMachineRun, renameMachine } from "./machines.js";
+import { camEngine, camJobInfo, camMachine, cancelCamJob, inspectModel, listCamJobs, listModels, listTools, removeTool, saveTool, startGenerate, waitForCamJob, } from "./cam.js";
+import { findSettings, importTools } from "./settings-import.js";
 // The viewer follows whatever program CNCjs has loaded, including files
 // loaded from the CNCjs interface itself.
 cncjs.onGcodeLoad((name, gcode) => loadJobFromCncjs(name, gcode));
-const VIEWER_HTML = path.join(ROOT, "dist", "viewer.html");
-const VIEWER_URI = "ui://anc/viewer.html";
+cncjs.onRunEnd(recordRun);
+cncjs.onRunEnd((run) => recordMachineRun(cncjs.snapshot().port, run));
+cncjs.onMachine(recordMachine);
+// Each widget is one bundled HTML file in dist/ (see app/).
+const widgetUri = (name) => `ui://anc/${name}.html`;
+const VIEWER_URI = widgetUri("viewer");
+const JOBS_URI = widgetUri("jobs");
+const MACHINE_URI = widgetUri("machine");
+const WIDGETS = [
+    { name: "viewer", description: "Agentic Numerical Control toolpath viewer" },
+    { name: "jobs", description: "Agentic Numerical Control jobs list" },
+    { name: "machine", description: "Agentic Numerical Control machine connection" },
+];
 // Base64 grows by 4/3: 384 KiB of binary is ~512 KiB per tool result, which
 // keeps each relayed message under the cloud WebSocket's 1 MiB limit.
 const CHUNK_BYTES = 384 * 1024;
@@ -20,6 +37,120 @@ function json(value) {
     // been reported to strip structuredContent for local servers.
     return { content: [{ type: "text", text: JSON.stringify(value) }] };
 }
+/** Checks the job against the connected machine's own settings and current zero, when there is one. */
+function machineContext() {
+    const m = cncjs.snapshot();
+    const settings = cncjs.controllerSettings();
+    const context = {
+        controller: m.port ? m.controller : null,
+        settings: settings?.values ?? null,
+        version: settings?.version ?? null,
+        mpos: m.mpos,
+        wpos: m.wpos,
+    };
+    // What the check depends on: the machine, its settings and its current zero.
+    const offset = m.mpos && m.wpos ? [m.mpos.x - m.wpos.x, m.mpos.y - m.wpos.y, m.mpos.z - m.wpos.z].map((n) => n.toFixed(2)).join(",") : "";
+    const key = `${context.controller ?? ""}|${settings ? Object.keys(settings.values).length : 0}|${offset}`;
+    return { context, key };
+}
+function analyzeJob(job) {
+    return analyzeGcode(job.gcode, machineContext().context);
+}
+let boundsCache = null;
+function jobBounds(job) {
+    if (boundsCache?.revision !== job.revision)
+        boundsCache = { revision: job.revision, bounds: analyzeGcode(job.gcode).bounds };
+    return boundsCache.bounds;
+}
+/** A machine record in plain terms: Grbl's numbered settings become named values. */
+function describeMachine(m, live) {
+    const n = (k) => {
+        const v = Number(m.settings?.[`$${k}`]);
+        return Number.isFinite(v) ? v : null;
+    };
+    const flag = (k) => (n(k) === null ? null : (n(k) & 1) === 1);
+    const xyz = (a) => (n(a) === null ? null : { x: n(a), y: n(a + 1), z: n(a + 2) });
+    const p = m.parameters ?? {};
+    // CNCjs passes $# values on as text: {x: "-212.400", ...} and "0.000" for TLO.
+    const num = (v) => (v === undefined || v === null || v === "" || !Number.isFinite(Number(v)) ? null : Number(v));
+    const point = (v) => {
+        const o = v;
+        return o && typeof o === "object" ? { x: num(o.x), y: num(o.y), z: num(o.z) } : null;
+    };
+    const zeros = Object.fromEntries(["G54", "G55", "G56", "G57", "G58", "G59"].filter((k) => point(p[k])).map((k) => [k, point(p[k])]));
+    const dirMask = n(23);
+    const live_ = live && live.mpos && live.wpos ? live : null;
+    return {
+        port: m.port,
+        name: machineName(m),
+        named: !!m.name,
+        simulator: m.port === "GRBL-SIM",
+        connected: !!live,
+        state: live ? (live.activeState ?? live.state) : null,
+        controller: m.controller,
+        firmware: m.firmware,
+        version: m.version,
+        baudrate: m.baudrate,
+        // Settings are null until the controller has reported them (Grbl only).
+        travel: xyz(130),
+        maxRate: xyz(110),
+        acceleration: xyz(120),
+        stepsPerMm: xyz(100),
+        homing: flag(22),
+        // Which end each axis homes to: Grbl homes towards plus unless $23 sets its bit.
+        homesTowardsMinus: dirMask === null ? null : { x: !!(dirMask & 1), y: !!(dirMask & 2), z: !!(dirMask & 4) },
+        softLimits: flag(20),
+        hardLimits: flag(21),
+        spindle: n(30) === null ? null : { min: n(31), max: n(30) },
+        laserMode: flag(32),
+        zeros,
+        activeZero: live?.wcs ?? null,
+        // Where the current zero is in machine coordinates, while connected.
+        workOffset: live_
+            ? { x: live_.mpos.x - live_.wpos.x, y: live_.mpos.y - live_.wpos.y, z: live_.mpos.z - live_.wpos.z }
+            : null,
+        toolLengthOffset: num(p.TLO),
+        jobsRun: m.jobsRun,
+        cuttingMs: m.cuttingMs,
+        lastAlarm: m.lastAlarm,
+        firstSeen: m.firstSeen,
+        lastSeen: live ? new Date().toISOString() : m.lastSeen,
+    };
+}
+/** The machine CAM plans for: the connected one, else the one seen most recently. */
+function camMachineNow() {
+    const live = cncjs.controllerSettings();
+    const m = cncjs.snapshot();
+    const record = (m.port && listMachines().find((r) => r.port === m.port)) || listMachines()[0];
+    return { ...camMachine(live?.values ?? record?.settings), name: record ? machineName(record) : null };
+}
+/** A finished generation, with the job check's headline for the new file. */
+async function camResult(job) {
+    if (job.state !== "done" || !job.file)
+        return job;
+    try {
+        const mc = machineContext();
+        const info = await jobFileInfo(job.file, mc.context, mc.key);
+        return { ...job, check: info.check, bounds: info.bounds, next: "Show it with anc_show_job (file). Nothing has been loaded into CNCjs." };
+    }
+    catch {
+        return job;
+    }
+}
+const OPERATION = z.object({
+    type: z.enum(["rough", "outline", "contour"]).describe("rough: clear material in flat layers (stepDown) down to the part. outline: cut along the part's edges, layer by layer (side outside to cut it out). contour: 3D finishing pass over the surface (best with a ball end mill)."),
+    tool: z.number().int().describe("Tool id from anc_cam_settings / anc_save_tool. One tool per job."),
+    stepDown: z.number().positive().optional().describe("mm per layer (rough, outline)"),
+    stepOver: z.number().min(0.05).max(1).optional().describe("Fraction of the tool diameter between passes (rough, contour), e.g. 0.4"),
+    feed: z.number().positive().describe("Cutting feed, mm/min"),
+    plunge: z.number().positive().optional().describe("Plunge feed, mm/min (rough, outline)"),
+    spindle: z.number().positive().describe("Spindle speed, rpm"),
+    leave: z.number().min(0).optional().describe("rough: mm to leave on walls for a finishing pass; contour: mm to leave on the surface"),
+    area: z.enum(["all", "inside"]).optional().describe("rough: clear all stock around the part (default), or only inside its outline"),
+    side: z.enum(["outside", "inside"]).optional().describe("outline: outside edge (default) or inside edges"),
+    axis: z.enum(["X", "Y"]).optional().describe("contour: direction of passes (default X)"),
+    direction: z.enum(["climb", "conventional"]).optional().describe("Milling direction (default climb)"),
+});
 function fail(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
@@ -61,25 +192,354 @@ export function createServer() {
             if (!job) {
                 return fail("No job is loaded yet. Pass `file` or `gcode`; anc_list_jobs lists the files.");
             }
-            return json({ job: jobSummary(job) });
+            const a = analyzeJob(job);
+            return json({
+                job: jobSummary(job),
+                // Headline only; anc_analyze_job has the full check.
+                check: {
+                    estimatedMinutes: Math.max(1, Math.round(a.time.totalSeconds / 60)),
+                    tools: a.tools,
+                    fit: a.fit.status,
+                    problems: a.checks.filter((c) => c.severity === "problem").map((c) => c.message),
+                    toCheck: a.checks.filter((c) => c.severity === "check").length,
+                },
+            });
         }
         catch (e) {
             return fail(e.message);
         }
     });
-    server.registerTool("anc_list_jobs", {
+    registerAppTool(server, "anc_list_jobs", {
         title: "List CNC job files",
-        description: "List G-code files in the Agentic Numerical Control jobs folder that anc_show_job can open.",
+        description: "List G-code files in the Agentic Numerical Control jobs folder that anc_show_job can open, " +
+            "with each file's size, line count, dimensions and how it last ran. Shows them as a list the person can open from.",
         inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+        _meta: {
+            ui: { resourceUri: JOBS_URI },
+            "openai/toolInvocation/invoking": "Listing jobs…",
+            "openai/toolInvocation/invoked": "Listed jobs",
+        },
     }, async () => {
         try {
-            return json({ folder: jobsDir(), files: await listJobFiles() });
+            const files = await listJobFiles();
+            const mc = machineContext();
+            // `jobs` adds how each file last ran on this computer and what's in it;
+            // `files` stays for older pages.
+            const jobs = await Promise.all(files.map(async (file) => ({ ...(await jobFileInfo(file, mc.context, mc.key).catch(() => ({ file }))), lastRun: lastRun(file) })));
+            return json({ folder: jobsDir(), files, jobs });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_get_status", {
+        title: "Get CNC status",
+        description: "What's happening now: whether the machine is connected and its state (Idle, Run, Hold, Alarm), its position, " +
+            "the job shown in the viewer, whether CNCjs has that same program loaded, run progress, and how this job last ran. Reads only.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => {
+        const job = currentJob();
+        const m = cncjs.snapshot();
+        const sameProgram = !!job && !!m.loadedHash && m.loadedHash === job.hash;
+        const sender = sameProgram ? m.sender : null;
+        return json({
+            machine: {
+                connected: !!m.port,
+                port: m.port,
+                controller: m.controller,
+                link: m.link,
+                state: m.activeState ?? m.state,
+                alarm: m.alarm,
+                workflow: m.workflow,
+                workPosition: m.wpos,
+                machinePosition: m.mpos,
+                coordinateSystem: m.wcs,
+            },
+            job: job ? { name: job.name, lineCount: job.toolpath.lines.length } : null,
+            cncjs: { loadedFile: m.loadedFile, sameProgramAsViewer: sameProgram },
+            // Lines acknowledged by the controller, not finished moves: the planner may still be cutting them.
+            progress: sender
+                ? { sentLines: sender.sent, acknowledgedLines: sender.received, totalLines: sender.total }
+                : null,
+            lastRun: job ? lastRun(job.name) : null,
+            canStart: m.link === "live" && m.activeState === "Idle" && m.workflow === "idle" && sameProgram
+                ? "Ready. The person starts it with the Start button in the viewer (two presses)."
+                : null,
+        });
+    });
+    registerAppTool(server, "anc_analyze_job", {
+        title: "Check CNC job",
+        description: "Check a G-code job before running it: size, run-time estimate, tools and tool changes, steps, deepest cut, feed rates, " +
+            "whether it fits the machine's travel from the current zero, and problems the controller would refuse or that look risky " +
+            "(drilling cycles on Grbl, cutter compensation, cutting with the spindle off, rapids below Z 0). " +
+            "Pass `file` or `gcode` like anc_show_job, or neither for the job already shown. Opens the viewer; never moves the machine.",
+        inputSchema: z.object({
+            file: z.string().optional().describe("G-code file name in the Agentic Numerical Control jobs folder"),
+            gcode: z.string().optional().describe("G-code program text to check"),
+            name: z.string().optional().describe("Display name when passing gcode text"),
+        }),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { resourceUri: VIEWER_URI } },
+    }, async ({ file, gcode, name }) => {
+        try {
+            const job = file
+                ? await loadJobFile(file)
+                : gcode
+                    ? loadJobText(name ?? "Untitled job", gcode)
+                    : currentJob();
+            if (!job)
+                return fail("No job is loaded yet. Pass `file` or `gcode`; anc_list_jobs lists the files.");
+            return json({ job: jobSummary(job), analysis: analyzeJob(job) });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_list_machines", {
+        title: "List CNC machines",
+        description: "The machines this computer has connected to, with what each controller reported the last time it connected: " +
+            "firmware, port, work area (travel), maximum speeds and acceleration, homing and limits, spindle range, saved zeros (G54-G59), " +
+            "jobs run and the last alarm. Reads only.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => {
+        const now = cncjs.snapshot();
+        // The job shown, in mm from its zero, for the work area picture.
+        const job = currentJob();
+        const bounds = job ? jobBounds(job) : null;
+        return json({
+            computer: os.hostname(),
+            job: job && bounds ? { name: job.name, min: bounds.min, max: bounds.max } : null,
+            machines: listMachines().map((m) => describeMachine(m, now.port === m.port ? now : null)),
+        });
+    });
+    registerAppTool(server, "anc_rename_machine", {
+        title: "Name a CNC machine",
+        description: "Give a machine a name, such as its make and model. Grbl doesn't report one. An empty name goes back to the port's name.",
+        inputSchema: z.object({ port: z.string(), name: z.string().max(60) }),
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ port, name }) => {
+        try {
+            const m = renameMachine(port, name);
+            return json({ port: m.port, name: machineName(m) });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    // ---- CAM: 3D models to G-code with the built-in Kiri:Moto. Generating only
+    // writes a job file; nothing here loads it into CNCjs or moves the machine.
+    registerAppTool(server, "anc_list_models", {
+        title: "List 3D models",
+        description: "List the 3D models (STL files) in the Agentic Numerical Control jobs folder that can be turned into G-code. " +
+            "The person adds models by putting STL files in that folder. Each comes with its size in the file's own units, " +
+            "the units the person gave when a job was last made from it, and the jobs made from it. Reads only.",
+        inputSchema: z.object({
+            preview: z.boolean().optional().describe("Include a coarse top view of each model, for the website's Models page"),
+        }),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ preview }) => {
+        try {
+            return json({ computer: os.hostname(), folder: jobsDir(), models: listModels({ preview }) });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_inspect_model", {
+        title: "Inspect 3D model",
+        description: "Size and triangle count of an STL model, read by the CAM engine. STL has no units, so the size is given both as millimetres and as inches: " +
+            "confirm with the person which is right before generating. Reads only.",
+        inputSchema: z.object({ file: z.string().describe("STL file name from anc_list_models") }),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ file }) => {
+        try {
+            return json(await inspectModel(file));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_cam_settings", {
+        title: "CAM settings",
+        description: "What G-code generation will use: the machine (work area, spindle maximum, feed limits, from the controller when it has reported them), " +
+            "the person's tool library, the operations available, how stock and zero are set, and the CAM engine version. Reads only.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => {
+        return json({
+            engine: camEngine(),
+            machine: camMachineNow(),
+            output: "Grbl / grblHAL G-code in mm: G21 G90, spindle on with M3, off with M5, no M6 tool changes.",
+            tools: listTools(),
+            operations: {
+                rough: "Clears material in flat layers. Needs tool, stepDown, stepOver, feed, plunge, spindle; optional leave, area.",
+                outline: "Cuts along the part's edges layer by layer; side outside cuts the part out. Needs tool, stepDown, feed, plunge, spindle; optional side.",
+                contour: "3D finishing over the surface, usually after rough. Needs tool, stepOver, feed, spindle; optional axis, leave.",
+            },
+            placement: "The part sits with its top at the top of the stock. Z zero is the top of the stock; X/Y zero is the stock's front-left corner (origin front-left, default) or its centre (origin center). " +
+                "Stock defaults to the part plus 10 mm in X and Y, and the part's height.",
+            limits: "One tool per job. STL models only for now.",
+            recentGenerations: listCamJobs(),
+        });
+    });
+    registerAppTool(server, "anc_save_tool", {
+        title: "Save cutting tool",
+        description: "Add a cutting tool to the person's tool library, or change one (pass its id). Sizes in mm: convert inch tools (1/8 in = 3.175 mm). " +
+            "Ask the person for the tool's real measurements rather than guessing.",
+        inputSchema: z.object({
+            id: z.number().int().optional().describe("Existing tool to change; leave out to add a new one"),
+            name: z.string().max(60).describe("The person's name for it, e.g. '3 mm 2-flute flat'"),
+            type: z.enum(["flat", "ball", "vbit", "drill"]),
+            diameter: z.number().positive().describe("Cutting diameter, mm"),
+            fluteLength: z.number().positive().describe("Length of the cutting edge, mm"),
+            shankDiameter: z.number().positive().optional().describe("Shank diameter, mm (defaults to the cutting diameter)"),
+            angle: z.number().positive().optional().describe("V-bit included angle, degrees"),
+            number: z.number().int().positive().optional().describe("Tool number (T word), if the machine has a tool changer"),
+        }),
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (input) => {
+        try {
+            return json({ saved: saveTool(input), tools: listTools() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_delete_tool", {
+        title: "Delete cutting tool",
+        description: "Remove a tool from the person's tool library.",
+        inputSchema: z.object({ id: z.number().int() }),
+        annotations: { destructiveHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ id }) => {
+        try {
+            removeTool(id);
+            return json({ deleted: id, tools: listTools() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_find_settings", {
+        title: "Find settings from other CNC software",
+        description: "Look on this computer for settings from other CNC software that could be imported: Kiri:Moto tool exports (.km, .b64), Fusion tool library exports (.json) and CNCjs's ~/.cncrc. " +
+            "Searches only ~/.cncrc and, one level deep, Downloads, Documents, Desktop, the jobs folder and Fusion's local libraries. Reads only; changes nothing. " +
+            "Show the person what was found and ask which tools to import before calling anc_import_tools.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => json(findSettings()));
+    registerAppTool(server, "anc_import_tools", {
+        title: "Import cutting tools",
+        description: "Add tools from a source found by anc_find_settings to the person's tool library, after they have agreed. Only adds: tools already in the library are left as they are, and nothing is replaced or deleted.",
+        inputSchema: z.object({
+            source: z.string().describe("Source id from anc_find_settings"),
+            pick: z.array(z.number().int().min(0)).optional().describe("Which of the source's tools to add (0-based positions in its tools list); leave out for all"),
+        }),
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ source, pick }) => {
+        try {
+            return json(importTools(source, pick));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_generate_gcode", {
+        title: "Generate G-code from a 3D model",
+        description: "Make a G-code job from an STL model with the built-in Kiri:Moto CAM engine, and save it in the jobs folder as a new file. " +
+            "Before calling: confirm the model's units with the person (anc_inspect_model), the stock size, where they will set zero, and the tool and its feeds and speeds. " +
+            "Waits up to about 40 seconds; a longer job keeps going and anc_cam_status reports it. " +
+            "Never loads the job into CNCjs or moves the machine: show it with anc_show_job for the person to review.",
+        inputSchema: z.object({
+            model: z.string().describe("STL file name from anc_list_models"),
+            units: z.enum(["mm", "in"]).describe("Units the model was drawn in, as the person confirmed"),
+            stock: z
+                .object({ x: z.number().positive(), y: z.number().positive(), z: z.number().positive() })
+                .optional()
+                .describe("Stock size in mm; at least the part's size"),
+            origin: z.enum(["front-left", "center"]).optional().describe("Where X/Y zero is on the stock (Z zero is always the top of the stock)"),
+            operations: z.array(OPERATION).min(1).max(8).describe("Operations in order, all with the same tool"),
+            name: z.string().max(80).optional().describe("Job file name (defaults to the model's name)"),
+        }),
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+            "openai/toolInvocation/invoking": "Generating toolpaths…",
+            "openai/toolInvocation/invoked": "Toolpaths generated",
+        },
+    }, async (req) => {
+        try {
+            const started = await startGenerate(req, camMachineNow());
+            return json(await camResult(await waitForCamJob(started.id, 40000)));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_cam_status", {
+        title: "G-code generation status",
+        description: "Progress of a G-code generation started with anc_generate_gcode: running (with progress 0-1), done (with the new job file), failed (with the reason) or cancelled. " +
+            "Waits up to about 20 seconds for a running one to finish. Without id, lists recent generations. Pass file instead to see how a generated job was made.",
+        inputSchema: z.object({
+            id: z.string().optional(),
+            file: z.string().optional().describe("A generated job file: returns its model, units, stock, tool, operations and engine version"),
+        }),
+        annotations: { readOnlyHint: true },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ id, file }) => {
+        try {
+            if (file)
+                return json({ file, generatedWith: camJobInfo(file) });
+            if (!id)
+                return json({ generations: listCamJobs() });
+            return json(await camResult(await waitForCamJob(id, 20000)));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_cam_cancel", {
+        title: "Cancel G-code generation",
+        description: "Stop a G-code generation that is still running. Nothing is saved.",
+        inputSchema: z.object({ id: z.string() }),
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ id }) => {
+        try {
+            return json(cancelCamJob(id));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    // ---- App-only tools: the viewer and the Jobs page call these directly, without a model turn.
+    registerAppTool(server, "anc_delete_job", {
+        title: "Delete job file",
+        description: "Delete a G-code file from the Agentic Numerical Control jobs folder.",
+        inputSchema: z.object({ file: z.string() }),
+        annotations: { destructiveHint: true },
+        _meta: { ui: { visibility: ["app"] } },
+    }, async ({ file }) => {
+        try {
+            const m = cncjs.snapshot();
+            if (m.loadedFile === file && m.workflow !== "idle") {
+                return fail(`"${file}" is ${m.workflow} in CNCjs. Stop it before deleting it.`);
+            }
+            const deleted = await deleteJobFile(file);
+            forgetRun(deleted);
+            return json({ deleted });
         }
         catch (e) {
             return fail(e.message);
         }
     });
-    // ---- App-only tools: the viewer polls these directly, without a model turn.
     registerAppTool(server, "anc_snapshot", {
         title: "Viewer snapshot",
         description: "Current job identity and machine link state for the Agentic Numerical Control viewer.",
@@ -109,7 +569,8 @@ export function createServer() {
                         : 0,
                 }
                 : null,
-            cncjsUrl: CNCJS_URL,
+            machineName: machine.port ? machineName(listMachines().find((r) => r.port === machine.port) ?? { name: null, port: machine.port, firmware: null, controller: machine.controller }) : null,
+            version: VERSION,
             serverTime: new Date().toISOString(),
         });
     });
@@ -156,11 +617,44 @@ export function createServer() {
         }
         return json({ revision, start, lines: job.toolpath.lines.slice(start, start + count) });
     });
+    registerAppTool(server, "anc_get_analysis", {
+        title: "Get job check",
+        description: "The job check for the current job, with program lines mapped to the viewer's timeline.",
+        inputSchema: z.object({ revision: z.number().int() }),
+        _meta: { ui: { visibility: ["app"] } },
+    }, async ({ revision }) => {
+        const job = currentJob();
+        if (!job || job.revision !== revision)
+            return fail(`Job revision ${revision} is no longer current.`);
+        const a = analyzeJob(job);
+        // The viewer's cursor counts parsed (non-blank) lines; map file lines onto it.
+        const raw = job.gcode.split(/\r?\n/);
+        const cursorAt = new Uint32Array(raw.length + 1);
+        for (let i = 0; i < raw.length; i++)
+            cursorAt[i + 1] = cursorAt[i] + (raw[i].trim() !== "" ? 1 : 0);
+        const at = (line) => cursorAt[Math.min(Math.max(line, 0), raw.length)];
+        return json({
+            revision,
+            analysis: {
+                ...a,
+                steps: a.steps.map((st) => ({ ...st, at: at(st.firstLine) })),
+                checks: a.checks.map((c) => ({ ...c, at: c.lines.map(at) })),
+                runs: a.runs.map((r) => ({ ...r, at: at(r.line) })),
+            },
+        });
+    });
     // ---- Machine link and run control (shared by Claude and the viewer).
-    server.registerTool("anc_list_ports", {
+    registerAppTool(server, "anc_list_ports", {
         title: "List machine ports",
-        description: "List serial ports CNCjs can see, to find the CNC controller.",
+        description: "List serial ports CNCjs can see, to find the CNC controller. Shows them so the person can pick one and connect, " +
+            "or, once connected, the machine's state and position.",
         inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+        _meta: {
+            ui: { resourceUri: MACHINE_URI },
+            "openai/toolInvocation/invoking": "Looking for the machine…",
+            "openai/toolInvocation/invoked": "Machine ports listed",
+        },
     }, async () => {
         try {
             return json({ ports: await cncjs.listPorts(), machine: cncjs.snapshot() });
@@ -169,7 +663,7 @@ export function createServer() {
             return fail(e.message);
         }
     });
-    server.registerTool("anc_connect_machine", {
+    registerAppTool(server, "anc_connect_machine", {
         title: "Connect machine",
         description: "Open the CNC controller's serial port in CNCjs. This connects to the real machine; only call it when the user asks to connect.",
         inputSchema: z.object({
@@ -177,21 +671,26 @@ export function createServer() {
             baudrate: z.number().int().default(115200),
             controller: z.enum(["Grbl", "Marlin", "Smoothie", "TinyG", "g2core"]).default("Grbl"),
         }),
+        _meta: { ui: { resourceUri: MACHINE_URI } },
     }, async ({ port, baudrate, controller }) => {
         try {
             await cncjs.openPort(port, baudrate, controller);
-            return json({ machine: cncjs.snapshot() });
+            return json({ ports: await cncjs.listPorts(), machine: cncjs.snapshot() });
         }
         catch (e) {
             return fail(e.message);
         }
     });
-    server.registerTool("anc_disconnect_machine", {
+    registerAppTool(server, "anc_disconnect_machine", {
         title: "Disconnect machine",
         description: "Close the machine's serial port in CNCjs.",
         inputSchema: z.object({}),
+        _meta: { ui: { visibility: ["model", "app"] } },
     }, async () => {
         try {
+            const busy = cncjs.snapshot().workflow;
+            if (busy !== "idle")
+                return fail(`A job is ${busy}; stop it before disconnecting.`);
             await cncjs.closePort();
             return json({ machine: cncjs.snapshot() });
         }
@@ -220,64 +719,90 @@ export function createServer() {
         }
     });
     registerAppTool(server, "anc_job_control", {
-        title: "Control CNC job",
-        description: "Start, pause, resume or stop the job loaded in CNCjs, or send feed hold, cycle start, unlock ($X), home ($H) or soft reset. " +
-            "This moves the real machine: only start or resume when the user explicitly asks. " +
+        title: "Pause or stop CNC job",
+        description: "Pause, stop, feed hold or soft reset the job running in CNCjs. " +
+            "Starting, resuming, homing and unlocking are only done from the viewer's own buttons, so the person is at the screen when the machine moves. " +
             "Soft reset is not an emergency stop; the physical E-stop is.",
         inputSchema: z.object({
-            action: z.enum(["start", "pause", "resume", "stop", "feedhold", "cyclestart", "unlock", "home", "reset"]),
+            action: z.enum(["pause", "stop", "feedhold", "reset"]),
         }),
         _meta: { ui: { visibility: ["model", "app"] } },
     }, async ({ action }) => {
+        try {
+            const command = { pause: "gcode:pause", stop: "gcode:stop", feedhold: "feedhold", reset: "reset" }[action];
+            if (action === "stop")
+                await cncjs.command(command, { force: true });
+            else
+                await cncjs.command(command);
+            return json({ sent: action, machine: cncjs.snapshot() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    // Everything that sets the machine moving (or lets it move again, after an
+    // alarm) is app-only: the model can't call it, only the viewer's buttons can.
+    // Start also names the program the viewer showed, by content, and is refused
+    // unless that is exactly what CNCjs has loaded.
+    registerAppTool(server, "anc_run_control", {
+        title: "Start, resume or home",
+        description: "Start or resume the job loaded in CNCjs, send cycle start, unlock ($X) or home ($H). Called by the viewer's buttons after the person confirms.",
+        inputSchema: z.object({
+            action: z.enum(["start", "resume", "cyclestart", "unlock", "home"]),
+            hash: z.string().optional().describe("For start: the hash of the job the viewer is showing"),
+        }),
+        _meta: { ui: { visibility: ["app"] } },
+    }, async ({ action, hash }) => {
         try {
             const m = cncjs.snapshot();
+            if (m.link !== "live")
+                return fail(`Not sent: machine status is not live (${m.state}).`);
             if (action === "start") {
                 const job = currentJob();
-                if (m.link !== "live")
-                    return fail(`Not starting: machine status is not live (${m.state}).`);
                 if (m.activeState !== "Idle")
                     return fail(`Not starting: machine is ${m.activeState}, not Idle.`);
                 if (m.workflow !== "idle")
                     return fail(`Not starting: CNCjs workflow is ${m.workflow}.`);
-                if (!m.loadedFile)
+                if (!m.loadedFile || !m.loadedHash)
                     return fail("Not starting: no program is loaded in CNCjs.");
-                if (job && job.name !== m.loadedFile) {
-                    return fail(`Not starting: CNCjs has "${m.loadedFile}" loaded but Agentic Numerical Control is showing "${job.name}".`);
+                if (!job)
+                    return fail("Not starting: no job is shown in the viewer.");
+                if (!hash || hash !== job.hash) {
+                    return fail("Not starting: the job shown has changed since you pressed Start. Check it and press Start again.");
+                }
+                if (m.loadedHash !== job.hash) {
+                    return fail(`Not starting: CNCjs has a different program loaded from the one shown ("${m.loadedFile}"). Load this job into CNCjs first.`);
                 }
             }
-            const command = {
-                start: "gcode:start",
-                pause: "gcode:pause",
-                resume: "gcode:resume",
-                stop: "gcode:stop",
-                feedhold: "feedhold",
-                cyclestart: "cyclestart",
-                unlock: "unlock",
-                home: "homing",
-                reset: "reset",
-            }[action];
-            if (action === "stop")
-                await cncjs.command(command, { force: true });
-            else
-                await cncjs.command(command);
+            if (action === "resume" && m.workflow !== "paused")
+                return fail(`Not resuming: the job is ${m.workflow}, not paused.`);
+            if (action === "cyclestart" && m.activeState !== "Hold")
+                return fail(`Not sent: machine is ${m.activeState}, not on hold.`);
+            if (action === "home" && m.workflow !== "idle")
+                return fail(`Not homing: CNCjs workflow is ${m.workflow}.`);
+            const command = { start: "gcode:start", resume: "gcode:resume", cyclestart: "cyclestart", unlock: "unlock", home: "homing" }[action];
+            await cncjs.command(command);
             return json({ sent: action, machine: cncjs.snapshot() });
         }
         catch (e) {
             return fail(e.message);
         }
     });
-    registerAppResource(server, VIEWER_URI, VIEWER_URI, { mimeType: RESOURCE_MIME_TYPE, description: "Agentic Numerical Control toolpath viewer" }, async () => ({
-        contents: [
-            {
-                uri: VIEWER_URI,
-                mimeType: RESOURCE_MIME_TYPE,
-                text: await fs.readFile(VIEWER_HTML, "utf-8"),
-                // The viewer is self-contained (one bundled file) and only talks to
-                // this server through the host bridge: no outside origins at all.
-                // Hosts default border styling differently, so say what we want.
-                _meta: { ui: { csp: { connectDomains: [], resourceDomains: [] }, prefersBorder: true } },
-            },
-        ],
-    }));
+    for (const widget of WIDGETS) {
+        const uri = widgetUri(widget.name);
+        registerAppResource(server, uri, uri, { mimeType: RESOURCE_MIME_TYPE, description: widget.description }, async () => ({
+            contents: [
+                {
+                    uri,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: await fs.readFile(path.join(ROOT, "dist", `${widget.name}.html`), "utf-8"),
+                    // Widgets are self-contained (one bundled file) and only talk to
+                    // this server through the host bridge: no outside origins at all.
+                    // Hosts default border styling differently, so say what we want.
+                    _meta: { ui: { csp: { connectDomains: [], resourceDomains: [] }, prefersBorder: true } },
+                },
+            ],
+        }));
+    }
     return server;
 }