dsh-cad 0.2.0

package/lib/store.js

@@ -0,0 +1,68 @@
+/**
+ * Scene store: viewId → CadScene JSON. Scenes live in memory with an LRU cap
+ * and are spilled to <root>/.dsh-cad/scenes/<viewId>.json so replayed cards
+ * still fetch their geometry after a process restart.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, unlink } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_MEMORY_SCENES = 16;
+export class SceneStore {
+    root;
+    memory = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    get directory() {
+        return path.join(this.root, '.dsh-cad', 'scenes');
+    }
+    /** Persist a scene and return its viewId. */
+    async put(scene) {
+        const viewId = randomUUID();
+        await this.putAt(viewId, scene);
+        return viewId;
+    }
+    /** Persist a scene under a stable viewId (overwrites; used by the modeling
+     *  document so every operation refreshes the same viewer card). */
+    async putAt(viewId, scene) {
+        this.memory.set(viewId, scene);
+        if (this.memory.size > MAX_MEMORY_SCENES) {
+            const oldest = this.memory.keys().next().value;
+            if (oldest !== undefined)
+                this.memory.delete(oldest);
+        }
+        await mkdir(this.directory, { recursive: true });
+        await writeFile(path.join(this.directory, `${viewId}.json`), JSON.stringify(scene));
+    }
+    /** Fetch a scene by viewId, restoring from disk when the memory copy aged out. */
+    async get(viewId) {
+        if (!/^[0-9a-f-]{36}$/i.test(viewId))
+            return null;
+        const memoryHit = this.memory.get(viewId);
+        if (memoryHit !== undefined)
+            return memoryHit;
+        try {
+            const text = await readFile(path.join(this.directory, `${viewId}.json`), 'utf8');
+            const scene = JSON.parse(text);
+            this.memory.set(viewId, scene);
+            return scene;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Best-effort removal (unused for now; kept for completeness of the API). */
+    async delete(viewId) {
+        this.memory.delete(viewId);
+        try {
+            await unlink(path.join(this.directory, `${viewId}.json`));
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    /** ETag for a scene payload (cache helper for the route handler). */
+    etag(scene) {
+        return `"${createHash('sha1').update(JSON.stringify(scene)).digest('hex').slice(0, 16)}"`;
+    }
+}

package/lib/tools/cad-freecad.js

@@ -0,0 +1,160 @@
+/**
+ * cad_freecad: run a feature program on an external FreeCAD executor. The
+ * program uses the same op shapes as the built-in kernel (create_prim /
+ * extrude_profile / boolean / fillet / transform / volume / delete / reset);
+ * meshes flow back into the same embedded viewer via the binary scene store.
+ * Optionally loads an input CAD file (STEP/BREP/STL) first and/or exports
+ * the result (.step/.stl) — the "upload STEP → external-engine pipeline".
+ */
+import { randomUUID } from 'node:crypto';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveWorkspacePath } from './util.js';
+import { findFreeCad, runFreeCadProgram } from '../cad_connector/freecad-executor.js';
+import { isKnownOpKind, normalizeOps } from '../cad_connector/executor.js';
+// Shared executor-contract normalization; historical alias for callers/tests.
+export const normalizeFreeCadSteps = normalizeOps;
+const INPUT_EXTENSIONS = new Set(['step', 'stp', 'brep', 'stl']);
+const EXPORT_EXTENSIONS = new Set(['step', 'stp', 'stl']);
+export function createFreeCadTool(deps) {
+    return defineTool({
+        name: 'cad_freecad',
+        description: 'Run a feature program on an external FreeCAD executor (requires FreeCAD installed locally or FREECAD_BIN set). ' +
+            '`steps` is an array of the same ops the built-in kernel uses: create_prim (box/cylinder/sphere/cone/torus with at/axis), ' +
+            'extrude_profile, boolean (fuse/cut/common), fillet, transform, volume, delete, reset. ' +
+            'Optionally `input` loads a STEP/STP/BREP/STL file as body "input" first, and `exportPath` (.step/.stl) writes the final result. ' +
+            'The rebuilt meshes render in the same viewer card, and by default the program also runs in the FreeCAD GUI — the window ' +
+            'opens with the bodies loaded and stays open, so the user can inspect the model in FreeCAD itself (it doubles as a viewer). ' +
+            'Set `headless: true` only for pure exports/automation where no window is wanted.',
+        parameters: {
+            steps: {
+                type: 'array',
+                required: true,
+                description: 'Ops executed in order. Canonical shapes: ' +
+                    '{kind:"create_prim", bodyId, prim:"box|cylinder|sphere|cone|torus", params:{dx,dy,dz | radius,height | radius1,radius2,height | majorRadius,minorRadius, at:[x,y,z], axis:[x,y,z]}}, ' +
+                    '{kind:"extrude_profile", bodyId, points:[x0,y0,x1,y1,...], height}, ' +
+                    '{kind:"boolean", op:"cut|fuse|common", target, tools:[bodyIds]}, ' +
+                    '{kind:"fillet", target, radius}, ' +
+                    '{kind:"transform", target, translate:[x,y,z], rotate:[rx,ry,rz] deg, mirror:[x,y,z]}, ' +
+                    '{kind:"volume", target}, {kind:"delete", target}, {kind:"reset"}.',
+            },
+            input: { type: 'string', description: 'Optional CAD file to load first (STEP .step/.stp, BREP, STL), absolute or workspace-relative.' },
+            exportPath: { type: 'string', description: 'Optional export destination; extension selects .step or .stl.' },
+            headless: { type: 'boolean', description: 'Run in the console binary without opening the FreeCAD window (pure exports/automation).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    viewId: { type: 'string', required: true, description: 'Viewer scene id.' },
+                    kind: { type: 'string', required: true, description: 'Always "3d".' },
+                    format: { type: 'string', required: true, description: 'Always "freecad".' },
+                    file: { type: 'string', required: true, description: 'Source label (input or exported file).' },
+                    bodies: { type: 'number', required: true, description: 'Bodies produced.' },
+                    triangles: { type: 'number', required: true, description: 'Total triangles.' },
+                    sceneUrl: { type: 'string', description: 'Versioned viewer URL (web compositions).' },
+                    exported: { type: 'string', description: 'Written export path, when requested.' },
+                    volume: { type: 'number', description: 'Volume in mm³ when exactly one volume was measured.' },
+                    opened: { type: 'boolean', description: 'FreeCAD GUI opened with the result.' },
+                },
+            },
+            render: (_args, value) => {
+                const record = value;
+                const lines = [`freecad: ${String(record.bodies)} bodies, ${String(record.triangles)} triangles`];
+                if (record.volume !== undefined)
+                    lines.push(`volume: ${Number(record.volume).toFixed(2)} mm³`);
+                if (record.exported !== undefined)
+                    lines.push(`written: ${String(record.exported)}`);
+                if (record.opened === true)
+                    lines.push('FreeCAD GUI opened — the window stays open for inspection');
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+            presentationMeta: (_args, value) => {
+                const record = value;
+                return {
+                    viewId: String(record.viewId),
+                    kind: '3d',
+                    format: 'freecad',
+                    file: String(record.file),
+                    ...(record.sceneUrl === undefined ? {} : { sceneUrl: String(record.sceneUrl) }),
+                    title: `FreeCAD · ${String(record.bodies)} ${record.bodies === 1 ? 'body' : 'bodies'}`,
+                    stats: { meshes: Number(record.bodies), triangles: Number(record.triangles) },
+                };
+            },
+        },
+        timeoutMs: 300_000,
+        isConcurrencySafe: () => false,
+        async execute(args) {
+            const executable = findFreeCad();
+            if (executable === null) {
+                throw new Error('FreeCAD was not found — install FreeCAD or point FREECAD_BIN at its console binary (freecadcmd)');
+            }
+            if (!Array.isArray(args.steps) || args.steps.length === 0) {
+                throw new Error('steps must be a non-empty array of ops');
+            }
+            const steps = normalizeOps(args.steps);
+            for (const [index, op] of steps.entries()) {
+                if (typeof op !== 'object' || op === null || !isKnownOpKind(op.kind)) {
+                    throw new Error(`steps[${index}] is not an op (missing "kind")`);
+                }
+            }
+            const names = {};
+            for (const op of steps) {
+                if (typeof op.bodyId === 'string' && typeof op.name === 'string')
+                    names[op.bodyId] = op.name;
+            }
+            const program = { ops: steps, names };
+            if (args.input !== undefined) {
+                const resolved = resolveWorkspacePath(args.input, deps.workspaceRoot);
+                const extension = resolved.toLowerCase().split('.').pop() ?? '';
+                if (!INPUT_EXTENSIONS.has(extension))
+                    throw new Error(`input must be one of .step .stp .brep .stl (got .${extension})`);
+                program.input = { format: extension, path: resolved, bodyId: 'input' };
+            }
+            if (args.exportPath !== undefined) {
+                const resolved = resolveWorkspacePath(args.exportPath, deps.workspaceRoot);
+                const extension = resolved.toLowerCase().split('.').pop() ?? '';
+                if (!EXPORT_EXTENSIONS.has(extension))
+                    throw new Error(`exportPath must be .step or .stl (got .${extension})`);
+                program.export = { format: extension, path: resolved };
+            }
+            const gui = args.headless !== true;
+            if (gui)
+                program.display = true;
+            const result = await runFreeCadProgram(program, gui ? { gui: true } : {});
+            if (result.meshes.length === 0) {
+                throw new Error('the FreeCAD program produced no bodies');
+            }
+            const viewId = `freecad-${randomUUID().slice(0, 8)}`;
+            const meshes = result.meshes.map((mesh) => ({
+                name: mesh.name === '' ? mesh.bodyId : mesh.name,
+                positions: mesh.positions,
+                normals: mesh.normals,
+                indices: mesh.indices,
+            }));
+            await deps.store.publish(viewId, meshes);
+            const triangles = meshes.reduce((sum, mesh) => sum + mesh.indices.length / 3, 0);
+            const volumeEntries = Object.entries(result.volumes);
+            const value = {
+                viewId,
+                kind: '3d',
+                format: 'freecad',
+                file: result.exported ?? (args.input !== undefined ? args.input : 'freecad program'),
+                bodies: meshes.length,
+                triangles,
+            };
+            if (volumeEntries.length === 1)
+                value.volume = volumeEntries[0][1];
+            if (result.exported !== undefined)
+                value.exported = result.exported;
+            if (args.headless !== true)
+                value.opened = true;
+            const sceneUrlBase = deps.ensureSceneRoute();
+            if (sceneUrlBase !== null)
+                value.sceneUrl = `${sceneUrlBase.replace('/scene', '/bin')}/${viewId}`;
+            return value;
+        },
+        presentCall: () => ({ card: 'generic', title: 'CAD FreeCAD run', kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD FreeCAD' }),
+    });
+}

package/lib/tools/cad-fusion.js

@@ -0,0 +1,138 @@
+/**
+ * cad_fusion: run a feature program on an external Fusion 360 executor
+ * (GUI bridge — Fusion has no headless mode, so the window opens with the
+ * bodies loaded, doubling as a viewer). Same op shapes as the built-in
+ * kernel and cad_freecad; meshes flow back into the same embedded WebGL
+ * viewer via the binary scene store.
+ */
+import { randomUUID } from 'node:crypto';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveWorkspacePath } from './util.js';
+import { isKnownOpKind, normalizeOps } from '../cad_connector/executor.js';
+import { FUSION360_EXECUTOR } from '../cad_connector/fusion360-executor.js';
+export function createFusionTool(deps) {
+    return defineTool({
+        name: 'cad_fusion',
+        description: 'Run a feature program on an external Fusion 360 executor (requires Fusion installed locally; native on Apple Silicon macOS and Windows). ' +
+            'Fusion has no headless mode, so its window opens with the result loaded — it doubles as a viewer. ' +
+            '`steps` uses the same ops as the built-in kernel and cad_freecad: create_prim (box/cylinder/sphere/cone/torus), extrude_profile, ' +
+            'boolean (fuse/cut/common), transform, volume, delete, reset. `exportPath` (.step/.stl) writes the result. ' +
+            'First use installs the DshCadBridge add-in into the user Fusion API folder and needs Fusion signed in once.',
+        parameters: {
+            steps: {
+                type: 'array',
+                required: true,
+                description: 'Ops executed in order. Canonical shapes: ' +
+                    '{kind:"create_prim", bodyId, prim:"box|cylinder|sphere|cone|torus", params:{dx,dy,dz | radius,height | radius1,radius2,height | majorRadius,minorRadius, at:[x,y,z], axis:[x,y,z]}}, ' +
+                    '{kind:"extrude_profile", bodyId, points:[x0,y0,x1,y1,...], height}, ' +
+                    '{kind:"boolean", op:"cut|fuse|common", target, tools:[bodyIds]}, ' +
+                    '{kind:"transform", target, translate:[x,y,z], rotate:[rx,ry,rz] deg}, ' +
+                    '{kind:"volume", target}, {kind:"delete", target}, {kind:"reset"}.',
+            },
+            exportPath: { type: 'string', description: 'Optional export destination; extension selects .step or .stl.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    viewId: { type: 'string', required: true, description: 'Viewer scene id.' },
+                    kind: { type: 'string', required: true, description: 'Always "3d".' },
+                    format: { type: 'string', required: true, description: 'Always "fusion".' },
+                    file: { type: 'string', required: true, description: 'Source label (exported file or program).' },
+                    bodies: { type: 'number', required: true, description: 'Bodies produced.' },
+                    triangles: { type: 'number', required: true, description: 'Total triangles.' },
+                    sceneUrl: { type: 'string', description: 'Versioned viewer URL (web compositions).' },
+                    exported: { type: 'string', description: 'Written export path, when requested.' },
+                    volume: { type: 'number', description: 'Volume in mm³ when exactly one volume was measured.' },
+                    opened: { type: 'boolean', description: 'Fusion window opened with the result.' },
+                },
+            },
+            render: (_args, value) => {
+                const record = value;
+                const lines = [`fusion360: ${String(record.bodies)} bodies, ${String(record.triangles)} triangles`];
+                if (record.volume !== undefined)
+                    lines.push(`volume: ${Number(record.volume).toFixed(2)} mm³`);
+                if (record.exported !== undefined)
+                    lines.push(`written: ${String(record.exported)}`);
+                lines.push('Fusion window opened — it stays open for inspection');
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+            presentationMeta: (_args, value) => {
+                const record = value;
+                return {
+                    viewId: String(record.viewId),
+                    kind: '3d',
+                    format: 'fusion',
+                    file: String(record.file),
+                    ...(record.sceneUrl === undefined ? {} : { sceneUrl: String(record.sceneUrl) }),
+                    title: `Fusion 360 · ${String(record.bodies)} ${record.bodies === 1 ? 'body' : 'bodies'}`,
+                    stats: { meshes: Number(record.bodies), triangles: Number(record.triangles) },
+                };
+            },
+        },
+        timeoutMs: 300_000,
+        isConcurrencySafe: () => false,
+        async execute(args) {
+            if (!FUSION360_EXECUTOR.available()) {
+                throw new Error(FUSION360_EXECUTOR.unavailableReason?.() ?? 'Fusion 360 is not available on this machine');
+            }
+            if (!Array.isArray(args.steps) || args.steps.length === 0) {
+                throw new Error('steps must be a non-empty array of ops');
+            }
+            const steps = normalizeOps(args.steps);
+            for (const [index, op] of steps.entries()) {
+                if (typeof op !== 'object' || op === null || !isKnownOpKind(op.kind)) {
+                    throw new Error(`steps[${index}] is not an op (missing "kind")`);
+                }
+            }
+            const names = {};
+            for (const op of steps) {
+                if (typeof op.bodyId === 'string' && typeof op.name === 'string')
+                    names[op.bodyId] = op.name;
+            }
+            const program = { ops: steps, names, display: true };
+            if (args.exportPath !== undefined) {
+                const resolved = resolveWorkspacePath(args.exportPath, deps.workspaceRoot);
+                const extension = resolved.toLowerCase().split('.').pop() ?? '';
+                if (extension !== 'step' && extension !== 'stp' && extension !== 'stl') {
+                    throw new Error(`exportPath must be .step or .stl (got .${extension})`);
+                }
+                program.export = { format: extension, path: resolved };
+            }
+            const result = await FUSION360_EXECUTOR.run(program);
+            if (result.meshes.length === 0) {
+                throw new Error('the Fusion program produced no bodies');
+            }
+            const viewId = `fusion-${randomUUID().slice(0, 8)}`;
+            const meshes = result.meshes.map((mesh) => ({
+                name: mesh.name === '' ? mesh.bodyId : mesh.name,
+                positions: mesh.positions,
+                normals: mesh.normals,
+                indices: mesh.indices,
+            }));
+            await deps.store.publish(viewId, meshes);
+            const triangles = meshes.reduce((sum, mesh) => sum + mesh.indices.length / 3, 0);
+            const volumeEntries = Object.entries(result.volumes);
+            const value = {
+                viewId,
+                kind: '3d',
+                format: 'fusion',
+                file: result.exported ?? 'fusion program',
+                bodies: meshes.length,
+                triangles,
+                opened: true,
+            };
+            if (volumeEntries.length === 1)
+                value.volume = volumeEntries[0][1];
+            if (result.exported !== undefined)
+                value.exported = result.exported;
+            const sceneUrlBase = deps.ensureSceneRoute();
+            if (sceneUrlBase !== null)
+                value.sceneUrl = `${sceneUrlBase.replace('/scene', '/bin')}/${viewId}`;
+            return value;
+        },
+        presentCall: () => ({ card: 'generic', title: 'CAD Fusion 360 run', kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD Fusion 360' }),
+    });
+}

package/lib/tools/cad-image.js

@@ -0,0 +1,121 @@
+/**
+ * cad_image_profile: PNG image → 2D contours → extrusion-ready polygon.
+ * Binarizes (Otsu or manual), traces outer contours, simplifies them, and
+ * renders a 2D preview card. The largest contour's points are returned so the
+ * agent can continue the pipeline with cad_extrude_profile (+ cad_boolean
+ * for holes). Never touches the shared modeling worker.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { decodePng } from '../convert/png.js';
+import { extractProfiles } from '../image/profile.js';
+import { loadCadFile, resolveWorkspacePath } from './util.js';
+export function createCadImageTool(deps) {
+    return defineTool({
+        name: 'cad_image_profile',
+        description: 'Extract 2D part contours from a PNG image (sketch, screenshot, or exported drawing): auto-thresholds (Otsu, override with `threshold`; `invert` for light-on-dark), ' +
+            'traces and simplifies outer contours, and renders them in a 2D preview card. Returns the largest contour as flat [x,y,…] points (mm, y-up, `scale` px/mm) ' +
+            'ready for cad_extrude_profile; pass the points on to continue the modeling pipeline.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'Path to the PNG image, absolute or relative to the workspace root.' },
+            threshold: { type: 'number', description: 'Manual binarization threshold 0–255 (default: Otsu auto).' },
+            invert: { type: 'boolean', description: 'Trace light shapes on a dark background.' },
+            tolerance: { type: 'number', description: 'Contour simplification tolerance in pixels (default 1.5).' },
+            scale: { type: 'number', description: 'Pixels per mm (default 1).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    viewId: { type: 'string', required: true, description: 'Viewer scene id.' },
+                    kind: { type: 'string', required: true, description: 'Always "2d".' },
+                    format: { type: 'string', required: true, description: 'Always "image".' },
+                    file: { type: 'string', required: true, description: 'Source image path.' },
+                    entities: { type: 'number', required: true, description: 'Contours extracted.' },
+                    sceneUrl: { type: 'string', description: 'Viewer URL (web compositions).' },
+                    points: { type: 'array', items: { type: 'number' }, description: 'Largest contour, flat [x0,y0,x1,y1,…] mm — feed to cad_extrude_profile.' },
+                },
+            },
+            render: (_args, value) => {
+                const record = value;
+                const count = Array.isArray(record.points) ? record.points.length / 2 : 0;
+                return [{ type: 'text', text: `image profile: ${String(record.entities)} contour(s); largest = ${count} points (mm, y-up) — extrude with cad_extrude_profile` }];
+            },
+            presentationMeta: (_args, value) => {
+                const record = value;
+                return {
+                    viewId: String(record.viewId),
+                    kind: '2d',
+                    format: 'image',
+                    file: String(record.file),
+                    ...(record.sceneUrl === undefined ? {} : { sceneUrl: String(record.sceneUrl) }),
+                    title: `${String(record.file)} · contours`,
+                    stats: { entities: Number(record.entities) },
+                };
+            },
+        },
+        timeoutMs: 120_000,
+        isConcurrencySafe: () => true,
+        async execute(args) {
+            const resolved = resolveWorkspacePath(args.path, deps.workspaceRoot);
+            const buffer = await loadCadFile(resolved);
+            const image = decodePng(buffer);
+            const profiles = extractProfiles(image, {
+                ...(args.threshold === undefined ? {} : { threshold: args.threshold }),
+                ...(args.invert === undefined ? {} : { invert: args.invert }),
+                ...(args.tolerance === undefined ? {} : { tolerance: args.tolerance }),
+                ...(args.scale === undefined ? {} : { scale: args.scale }),
+            });
+            if (profiles.length === 0) {
+                throw new Error('no contours found — try a manual threshold or invert for light-on-dark images');
+            }
+            const top = profiles.slice(0, 8);
+            const scene = {
+                kind: '2d',
+                format: 'image',
+                entities: top.map((profile, index) => ({
+                    type: 'polyline',
+                    points: profile.points,
+                    closed: true,
+                    layer: index === 0 ? 'OUTER' : 'CONTOUR',
+                })),
+                bounds: boundsOf(top.map((profile) => profile.points)),
+                layers: ['OUTER', 'CONTOUR'],
+            };
+            const viewId = await deps.store.put(scene);
+            const value = {
+                viewId,
+                kind: '2d',
+                format: 'image',
+                file: resolved,
+                entities: top.length,
+                points: top[0].points,
+            };
+            const sceneUrlBase = deps.ensureSceneRoute();
+            if (sceneUrlBase !== null)
+                value.sceneUrl = `${sceneUrlBase}/${viewId}`;
+            return value;
+        },
+        presentCall: (args) => ({ card: 'generic', title: `CAD image profile ${String(args.path)}`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD image profile' }),
+    });
+}
+function boundsOf(polygons) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const points of polygons) {
+        for (let i = 0; i < points.length; i += 2) {
+            if (points[i] < minX)
+                minX = points[i];
+            if (points[i + 1] < minY)
+                minY = points[i + 1];
+            if (points[i] > maxX)
+                maxX = points[i];
+            if (points[i + 1] > maxY)
+                maxY = points[i + 1];
+        }
+    }
+    return { min: { x: minX, y: minY }, max: { x: maxX, y: maxY } };
+}

package/lib/tools/cad-info.js

@@ -0,0 +1,92 @@
+/**
+ * The `cad_info` tool: geometry metadata without rendering — format, counts,
+ * bounds, units, and DXF layer names.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { detectFormat } from '../convert/detect.js';
+import { convert } from '../convert/index.js';
+import { sceneStats } from '../types.js';
+import { loadCadFile, resolveWorkspacePath } from './util.js';
+/** Build the cad_info tool definition. */
+export function createCadInfoTool(deps) {
+    return defineTool({
+        name: 'cad_info',
+        description: 'Inspect a CAD file and return geometry metadata only (no viewer): format, part/triangle or entity counts, ' +
+            'axis-aligned bounds, units (STEP/IGES/DCPRT), and layer names (DXF). Cheaper than cad_view when only numbers are needed.',
+        parameters: {
+            path: {
+                type: 'string',
+                required: true,
+                description: 'Path to the CAD file, absolute or relative to the workspace root.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    format: { type: 'string', required: true, description: 'Detected source format.' },
+                    file: { type: 'string', required: true, description: 'Resolved file path.' },
+                    kind: { type: 'string', enum: ['3d', '2d'], required: true },
+                    meshes: { type: 'number', description: 'Part count (3D).' },
+                    triangles: { type: 'number', description: 'Total triangle count (3D).' },
+                    entities: { type: 'number', description: 'Drawing entity count (2D).' },
+                    layers: { type: 'array', items: { type: 'string' }, description: 'Layer names (DXF).' },
+                    units: { type: 'string', description: 'Source units (3D).' },
+                    boundsMin: { type: 'array', items: { type: 'number' }, description: 'Bounds minimum (xyz for 3D, xy for 2D).' },
+                    boundsMax: { type: 'array', items: { type: 'number' }, description: 'Bounds maximum (xyz for 3D, xy for 2D).' },
+                },
+            },
+            render: (_args, value) => {
+                const lines = [`${value.file} — ${value.format.toUpperCase()} (${value.kind.toUpperCase()})`];
+                if (value.kind === '3d') {
+                    lines.push(`parts: ${value.meshes ?? 0}`);
+                    lines.push(`triangles: ${value.triangles ?? 0}`);
+                    if (value.units !== undefined)
+                        lines.push(`units: ${value.units}`);
+                }
+                else {
+                    lines.push(`entities: ${value.entities ?? 0}`);
+                    if ((value.layers ?? []).length > 0)
+                        lines.push(`layers: ${(value.layers ?? []).join(', ')}`);
+                }
+                if (value.boundsMin !== undefined && value.boundsMax !== undefined) {
+                    lines.push(`bounds: [${value.boundsMin.map((v) => v.toFixed(3)).join(', ')}] → [${value.boundsMax.map((v) => v.toFixed(3)).join(', ')}]`);
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        timeoutMs: 180_000,
+        isConcurrencySafe: () => true,
+        async execute(args) {
+            const resolved = resolveWorkspacePath(args.path, deps.workspaceRoot);
+            const name = resolved.split('/').pop() ?? resolved;
+            const format = detectFormat(name);
+            if (format === null) {
+                throw new Error(`unsupported CAD format: ${name} — supported extensions are .stl .obj .step .stp .iges .igs .brep .dcprt .dxf .svg`);
+            }
+            const buffer = await loadCadFile(resolved);
+            const scene = await convert(buffer, format, name);
+            const stats = sceneStats(scene);
+            // Optional fields spread conditionally: an explicit undefined value
+            // would fail the registry's lossless-JSON output validation.
+            return {
+                format: stats.format,
+                file: resolved,
+                kind: scene.kind,
+                ...(stats.meshes === undefined ? {} : { meshes: stats.meshes }),
+                ...(stats.triangles === undefined ? {} : { triangles: stats.triangles }),
+                ...(stats.entities === undefined ? {} : { entities: stats.entities }),
+                ...(stats.layers === undefined ? {} : { layers: stats.layers }),
+                ...(stats.units === undefined ? {} : { units: stats.units }),
+                ...(stats.boundsMin === undefined ? {} : { boundsMin: stats.boundsMin }),
+                ...(stats.boundsMax === undefined ? {} : { boundsMax: stats.boundsMax }),
+            };
+        },
+        presentCall: (args) => ({
+            card: 'generic',
+            title: `CAD info ${args.path}`,
+            kind: 'read',
+        }),
+    });
+}