scanruler-mcp 0.1.0 → 0.3.0

package/src/tools.js

@@ -37,7 +37,43 @@ const imagePath = {
   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.',
 }
 
+/** How many significant digits a number keeps in an answer, and the finest
+ *  step it is given to: six digits is a micrometre on a part under a metre
+ *  and a millionth of a unit vector; past them the page's doubles are
+ *  noise the agent pays for — 0.9483828176573491 in place of 0.948383. */
+const DIGITS = 6
+const STEP = 1e6
+
+const tidy = (v) => {
+  const r = Number(v.toPrecision(DIGITS))
+  return Math.abs(r) < 9e9 ? Math.round(r * STEP) / STEP || 0 : r
+}
+
+/** An answer as the agent reads it: JSON, every number that is not whole
+ *  kept to DIGITS significant digits and no finer than a millionth — 1e-17,
+ *  a zero's rounding error, is 0. Whole numbers — ids, indices, counts —
+ *  are as they were. An `exact` answer is one whose numbers are handed
+ *  back as inputs — a plane's frame, say — and keeps every digit:
+ *  shortened, what is built on them is a hair off what it was meant to
+ *  meet. */
+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: 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 change runs on; scanruler_wait { for: "job", job } gives its answer. true (the default): answer once it is done.',
+}
+
+/** 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 ?? {}) }
@@ -61,6 +97,10 @@ export function toolFor(command, { outDir }) {
     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 (!command.readOnly) {
+    input.properties.wait = waitIn
+    input.properties.timings = timingsIn
+  }
   if (required.length) input.required = required
   else delete input.required
   return {
@@ -105,7 +145,7 @@ export async function imageContent(result, args, { cwd, outDir }) {
   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 } }
   return [
-    { type: 'text', text: JSON.stringify(saved) },
+    { type: 'text', text: agentJson(saved) },
     { type: 'image', data: Buffer.from(file.bytes.buffer, file.bytes.byteOffset, file.bytes.byteLength).toString('base64'), mimeType: file.mimeType },
   ]
 }

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 }
+}