scanruler-mcp 0.2.0 → 0.4.0

package/src/tools.js

@@ -6,10 +6,11 @@
 // it to the page; a command that hands a file back takes an optional path,
 // and this server writes the file there. The agent never sees the bytes —
 // but for a picture (a command marked returnsImage), which it is shown as an
-// image, and which is written to a file only when it gives a path.
+// image, and which is written to a file only when it gives a path — or, in
+// a batch, where it cannot be shown, always.
 
-import { readFile, stat, writeFile, mkdir } from 'node:fs/promises'
-import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import { readdir, readFile, stat, writeFile, mkdir } from 'node:fs/promises'
+import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path'
 
 export const toolName = (command) => command.name.replace(/\./g, '_')
 
@@ -31,10 +32,27 @@ const outPath = (outDir) => ({
   description: `Where to write the file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it goes into ${outDir}.`,
 })
 
-const imagePath = {
+const imagePath = (outDir) => ({
   type: 'string',
   minLength: 1,
-  description: 'Also write the picture to a file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it is only shown.',
+  description: `Also write the picture to a file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it is only shown — but in scanruler_batch, which shows no picture, it is written into ${outDir} under a new name.`,
+})
+
+/** The `saveTo` a command that replaces the session takes — one with
+ *  `discard`: the session saved as a project file first (mcp.js). */
+const saveToIn = {
+  type: 'string',
+  minLength: 1,
+  description: 'Save the session as a .scanruler project file here first — a file path, or a folder to save it into under its own name — then go on as with discard: true. If the save fails nothing is replaced. The answer says where it went (savedTo).',
+}
+
+/** Whether a command replaces the session, refusing to over work unless
+ *  told `discard` — what `saveTo` is offered on. */
+export const replacesSession = (command) => command.input?.properties?.discard?.type === 'boolean'
+
+const inlineIn = {
+  type: 'boolean',
+  description: 'false, with path: the picture is written to the file and not shown — the answer says where. A picture costs far more context than its text; save the ones you only deliver.',
 }
 
 /** How many significant digits a number keeps in an answer, and the finest
@@ -60,6 +78,21 @@ export const agentJson = (value, exact = false) =>
   exact ? JSON.stringify(value) : JSON.stringify(value, (_key, v) => (typeof v === 'number' && Number.isFinite(v) && !Number.isInteger(v) ? tidy(v) : v))
 
 /** A command as the MCP tool an agent sees. */
+/** The `wait` a tool that changes the session takes, and a long read
+ *  (Command.long): the server runs every such call as a job (mcp.js), and
+ *  false answers with the job at once. */
+export const waitIn = {
+  type: 'boolean',
+  description: 'false: answer at once with { queued: true, job } while the call runs on; scanruler_wait { for: "job", job } gives its answer. true (the default): answer once it is done — or, still running at the server’s answer limit (scanruler_status: server.answerWithin, seconds), with { queued: true, job, after } all the same.',
+}
+
+/** The `timings` a tool that changes the session takes: the server keeps
+ *  what the page's answer carries of the build's steps (mcp.js). */
+export const timingsIn = {
+  type: 'boolean',
+  description: 'true: the answer adds ms (the call, start to answer) and, where the change built, steps.played — each step the build played with its ms (steps.restored counts those taken up from a kept state, not played).',
+}
+
 export function toolFor(command, { outDir }) {
   const input = structuredClone(command.input ?? { type: 'object' })
   input.properties = { ...(input.properties ?? {}) }
@@ -68,7 +101,8 @@ export function toolFor(command, { outDir }) {
   let description = command.description
   if (bytesKey) {
     delete input.properties[bytesKey]
-    input.properties.path = inPath
+    const pick = FOLDER_PICKS[command.name]
+    input.properties.path = pick ? { ...inPath, description: `${inPath.description} A folder opens the one ${pick.what} file in it (${pick.kinds.join(', ')}); with more than one, the answer lists them.` } : inPath
     required = required.filter((key) => key !== bytesKey && key !== 'name')
     if (!required.includes('path')) required.unshift('path')
     if (input.properties.name) {
@@ -77,12 +111,24 @@ export function toolFor(command, { outDir }) {
     description += ' The file is read from `path` on this computer and streamed to the page.'
   }
   if (command.returnsImage) {
-    input.properties.path = imagePath
-    description += ' The picture comes back as an image; with `path` it is written to a file too.'
+    input.properties.path = imagePath(outDir)
+    input.properties.inline = inlineIn
+    description += ' The picture comes back as an image; with `path` it is written to a file too, and with `inline: false` only there.'
   } else if (command.returnsFile) {
     input.properties.path = outPath(outDir)
     description += ' The file is written to `path`; the result says where and how large it is, not its bytes.'
   }
+  if (replacesSession(command)) {
+    input.properties.saveTo = saveToIn
+    description += ' With `saveTo`, the session is saved as a project file there first (as project_save does), then replaced as with discard: true — one call to keep what a page holds and start anew.'
+  }
+  if (!command.readOnly) {
+    input.properties.wait = waitIn
+    input.properties.timings = timingsIn
+  } else if (command.long) {
+    // A long read runs as a job too (mcp.js), so it takes wait.
+    input.properties.wait = waitIn
+  }
   if (required.length) input.required = required
   else delete input.required
   return {
@@ -97,41 +143,188 @@ export function toolFor(command, { outDir }) {
 /** A path as the agent gave it, made absolute against `base`. */
 export const absolute = (path, base) => (isAbsolute(path) ? path : resolve(base, path))
 
+/** What a folder given in place of a file opens, by command: the one file
+ *  of its kind in it. Other commands take a file only. */
+const FOLDER_PICKS = {
+  'scan.open': { what: 'mesh', kinds: ['.stl', '.ply', '.obj'] },
+  'project.load': { what: 'project', kinds: ['.scanruler'] },
+}
+
+/** The file a path names: itself, or — for a folder, where the command
+ *  takes one (FOLDER_PICKS) — the only file of the command's kind in it.
+ *  Refused with the folder's files listed otherwise. */
+async function fileAt(command, file) {
+  const found = await stat(file).catch(() => null)
+  if (!found?.isDirectory()) return file
+  const names = (await readdir(file, { withFileTypes: true })).filter((d) => d.isFile()).map((d) => d.name)
+  const listed = (list) => (list.length > 20 ? `${list.slice(0, 20).join(', ')} and ${list.length - 20} more` : list.join(', '))
+  const pick = FOLDER_PICKS[command.name]
+  if (!pick) throw { code: 'invalid_input', message: `path: ${file} is a folder — give a file${names.length ? ` in it: ${listed(names)}` : ''}.` }
+  const matches = names.filter((n) => pick.kinds.includes(extname(n).toLowerCase()))
+  if (matches.length === 1) return join(file, matches[0])
+  if (matches.length === 0) {
+    throw { code: 'invalid_input', message: `path: ${file} is a folder with no ${pick.what} file in it (${pick.kinds.join(', ')})${names.length ? ` — it holds ${listed(names)}` : ' — it is empty'}. Give the file’s path.` }
+  }
+  throw { code: 'invalid_input', message: `path: ${file} is a folder with ${matches.length} ${pick.what} files — give one of them by its path: ${listed(matches)}.` }
+}
+
+/** How many near names a missing path's refusal lists at most, and how many
+ *  letters off a near name may be. */
+const NEAR_LISTED = 5
+const NEAR_LETTERS = 2
+
+/** A name as nearNames compares it: case ignored, and "-", "_" and a
+ *  space taken alike. */
+const nearForm = (name) => name.toLowerCase().replace(/[-_ ]/g, '_')
+
+/** How many letters `a` and `b` are apart — added, taken out or changed —
+ *  or `most + 1` once past `most`. */
+function lettersApart(a, b, most) {
+  if (Math.abs(a.length - b.length) > most) return most + 1
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i]
+    for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    if (Math.min(...next) > most) return most + 1
+    row = next
+  }
+  return row[b.length]
+}
+
+/** Where a path that is not there may have been meant: the first folder up
+ *  from it that is there, the name in the path missing from it, and up to
+ *  NEAR_LISTED names in that folder at most NEAR_LETTERS letters off it — a typed
+ *  path's slip, "10_scooter_head" for "10_scooterHead". A near folder is
+ *  given with the rest of the path when that is in it. */
+export async function nearNames(path) {
+  let missing = resolve(path)
+  let folder = dirname(missing)
+  let rest = []
+  for (;;) {
+    if ((await stat(folder).catch(() => null))?.isDirectory()) break
+    if (dirname(folder) === folder) return { folder: null, missing: null, near: [] }
+    rest = [basename(missing), ...rest]
+    missing = folder
+    folder = dirname(folder)
+  }
+  const want = nearForm(basename(missing))
+  const names = await readdir(folder).catch(() => [])
+  const near = names
+    .map((name) => ({ name, apart: lettersApart(nearForm(name), want, NEAR_LETTERS) }))
+    .filter((n) => n.apart <= NEAR_LETTERS)
+    .sort((a, b) => a.apart - b.apart || a.name.localeCompare(b.name))
+    .slice(0, NEAR_LISTED)
+  const paths = []
+  for (const { name } of near) {
+    const whole = join(folder, name, ...rest)
+    paths.push(rest.length && (await stat(whole).catch(() => null)) ? whole : join(folder, name))
+  }
+  return { folder, missing: basename(missing), near: paths }
+}
+
+/** nearNames as a refusal's last sentence. */
+async function nearNote(path) {
+  const { folder, missing, near } = await nearNames(path)
+  if (!folder) return ''
+  if (near.length) return ` Near it: ${near.join(', ')}.`
+  return ` ${folder} is there, with nothing in it named like ${missing}.`
+}
+
 /** The tool call's arguments as the command's input: a path read into the
- *  bytes it names. Returns the input and the input field the bytes go in. */
+ *  bytes it names. Returns the input, the input field the bytes go in, and
+ *  the file read — a folder's one file, when the path named a folder. */
 export async function inputFor(command, args, { cwd }) {
   const input = { ...(args ?? {}) }
+  delete input.saveTo
   const bytesKey = bytesProperty(command)
   if (bytesKey) {
-    const file = absolute(String(input.path ?? ''), cwd)
+    const file = await fileAt(command, absolute(String(input.path ?? ''), cwd))
     delete input.path
     let bytes
     try {
       bytes = new Uint8Array(await readFile(file))
     } catch (e) {
-      throw { code: 'invalid_input', message: `Could not read ${file}: ${e.code === 'ENOENT' ? 'there is no such file' : e.message}.` }
+      if (e.code !== 'ENOENT') throw { code: 'invalid_input', message: `Could not read ${file}: ${e.message}.` }
+      throw { code: 'invalid_input', message: `Could not read ${file}: there is no such file.${await nearNote(file)}` }
     }
     input[bytesKey] = bytes
     if (command.input?.properties?.name && input.name === undefined) input.name = basename(file)
-    return { input, binaryKey: bytesKey }
+    return { input, binaryKey: bytesKey, file }
   }
   if (command.returnsFile || command.returnsImage) delete input.path
-  return { input, binaryKey: null }
+  if (command.returnsImage) delete input.inline
+  return { input, binaryKey: null, file: null }
+}
+
+/** Arguments with every `{ "$file": path }` in them — an object of that one
+ *  key, at any depth — replaced by the JSON the file holds: a long list of
+ *  stations a script wrote need not pass through the conversation. A
+ *  relative path is taken from `cwd`. What a file holds is not looked
+ *  into again. */
+export async function withFiles(value, cwd) {
+  if (Array.isArray(value)) return Promise.all(value.map((v) => withFiles(v, cwd)))
+  if (!value || typeof value !== 'object' || value instanceof Uint8Array) return value
+  const keys = Object.keys(value)
+  if (keys.length === 1 && keys[0] === '$file') {
+    if (typeof value.$file !== 'string' || !value.$file) throw { code: 'invalid_input', message: '$file: give the path of a JSON file.' }
+    const path = absolute(value.$file, cwd)
+    try {
+      return JSON.parse(await readFile(path, 'utf8'))
+    } catch (e) {
+      throw { code: 'invalid_input', message: `$file: ${path} could not be read as JSON (${e?.code === 'ENOENT' ? 'there is no such file' : e instanceof Error ? e.message : String(e)}).` }
+    }
+  }
+  const out = {}
+  for (const key of keys) out[key] = await withFiles(value[key], cwd)
+  return out
+}
+
+/** A file's kind by its extension, as scanruler_files lists it. */
+const KINDS = {
+  mesh: ['.stl', '.ply', '.obj', '.3mf', '.off'],
+  project: ['.scanruler'],
+  step: ['.step', '.stp'],
+  picture: ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'],
+  drawing: ['.dxf', '.svg', '.pdf'],
+  text: ['.md', '.txt', '.csv', '.json', '.jsonl'],
+}
+export const fileKind = (name) => {
+  const ext = extname(name).toLowerCase()
+  return Object.keys(KINDS).find((kind) => KINDS[kind].includes(ext)) ?? 'other'
 }
 
 /** A picture a command handed back, as MCP content: the image, and the rest
  *  of the result as text — where the picture was written, if the call gave
- *  a path, in place of its bytes. Null for a result with no picture in it. */
+ *  a path, in place of its bytes; written and not shown with `inline:
+ *  false`. Null for a result with no picture in it. */
 export async function imageContent(result, args, { cwd, outDir }) {
   const file = result?.file
   if (!file || !(file.bytes instanceof Uint8Array) || !String(file.mimeType ?? '').startsWith('image/')) return null
   const saved = args?.path ? await saveFileResult(result, args, { cwd, outDir }) : { ...result, file: { name: file.name, mimeType: file.mimeType, size: file.bytes.byteLength } }
+  if (args?.path && args?.inline === false) return [{ type: 'text', text: agentJson(saved) }]
   return [
     { type: 'text', text: agentJson(saved) },
     { type: 'image', data: Buffer.from(file.bytes.buffer, file.bytes.byteOffset, file.bytes.byteLength).toString('base64'), mimeType: file.mimeType },
   ]
 }
 
+/** A picture a batched call handed back, which a batch cannot show:
+ *  written where the call asked, or into `outDir` under the name ScanRuler
+ *  gave it — numbered past one already there, so a batch of renders, or a
+ *  render from an earlier batch, is not written over. The result says
+ *  where, in place of the bytes. A result with no picture in it is as
+ *  saveFileResult leaves it. */
+export async function batchedPicture(result, args, { cwd, outDir }) {
+  const file = result?.file
+  if (args?.path || !file || !(file.bytes instanceof Uint8Array)) return saveFileResult(result, args, { cwd, outDir })
+  const name = String(file.name ?? 'picture.png')
+  const dot = name.lastIndexOf('.')
+  const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, '']
+  let target = join(outDir, name)
+  for (let n = 2; await stat(target).catch(() => null); n++) target = join(outDir, `${stem}-${n}${ext}`)
+  return saveFileResult(result, { path: target }, { cwd, outDir })
+}
+
 /** Write a returned file where the call asked, or into `outDir`; the result
  *  then says where, in place of the bytes. */
 export async function saveFileResult(result, args, { cwd, outDir }) {

package/src/trace.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The call trace: one JSON line per tool call into a file of the session's
+// own, for measuring a run afterwards — how long each call took, how much
+// went each way, what was refused, and whether the tab was hidden. Off
+// unless asked for (--trace <dir>, SCANRULER_MCP_TRACE); local only; an
+// argument's contents are written only with --trace-args, its size always.
+// scripts/trace-summary.mjs reads the files.
+
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Bytes of a value as JSON, UTF-8. */
+export const jsonBytes = (value) => (value === undefined ? 0 : Buffer.byteLength(JSON.stringify(value), 'utf8'))
+
+/** What an MCP reply weighs: its text in UTF-8 bytes, a picture by its
+ *  base64 — what the client is handed — and the error code of a refusal. */
+export function replyMeasure(reply) {
+  let out = 0
+  let images = 0
+  for (const c of reply?.content ?? []) {
+    if (c.type === 'text') out += Buffer.byteLength(c.text ?? '', 'utf8')
+    else if (c.type === 'image') {
+      out += (c.data ?? '').length
+      images++
+    }
+  }
+  const text = reply?.content?.find((c) => c.type === 'text')?.text ?? ''
+  const error = reply?.isError ? (/^([a-z_]+): /.exec(text)?.[1] ?? 'failed') : null
+  return { out, error, ...(images ? { images } : {}) }
+}
+
+/** A trace into a new file in `dir`, or null when `dir` is empty. Each
+ *  line is a JSON object with `ev`: "start" (the server), "list" (the tool
+ *  list handed out), "call" (a tool call answered), "entry" (one call of a
+ *  batch), "job" (a change started with wait: false, finished) and
+ *  "visibility" (the tab hidden or shown). Times are ms since the epoch
+ *  (`t`, the start) and durations ms. */
+export function createTrace(dir, { args = false, now = () => Date.now(), pid = process.pid } = {}) {
+  if (!dir) return null
+  mkdirSync(dir, { recursive: true })
+  const stamp = new Date(now()).toISOString().replace(/[:.]/g, '-').replace(/Z$/, '')
+  const file = join(dir, `scanruler-mcp-${stamp}-${pid}.jsonl`)
+  let broken = false
+  const write = (line) => {
+    if (broken) return
+    try {
+      appendFileSync(file, `${JSON.stringify(line)}\n`)
+    } catch (e) {
+      // A trace that cannot be written is not a reason to fail the call.
+      broken = true
+      process.stderr.write(`[scanruler-mcp] The trace stopped: ${e?.message ?? e}\n`)
+    }
+  }
+  return { file, args, now, write }
+}