picocode-core 0.9.119

package/src/tools/edit.js

@@ -0,0 +1,95 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { makeReversibleEdit } from '../reversible-edit.js'
+import { makeDiff } from './diff.js'
+
+const LOOKALIKES = { '‘': "'", '’': "'", '“': '"', '”': '"', '–': '-', '—': '-' }
+
+// matching tolerates cosmetic differences the model routinely gets wrong:
+// trailing whitespace, smart quotes, dashes. the normalized text is only ever
+// used to find the span; offsets map back so the file is spliced at its own
+// bytes and nothing outside the replaced span is rewritten
+function normalize(text) {
+  const chars = []
+  const offsets = []
+  let last = 0
+  const keep = (from, to) => {
+    for (let i = from; i < to; i++) {
+      chars.push(LOOKALIKES[text[i]] || text[i])
+      offsets.push(i)
+    }
+  }
+  for (const match of text.matchAll(/[^\S\n]+$/gm)) {
+    keep(last, match.index)
+    last = match.index + match[0].length
+  }
+  keep(last, text.length)
+  return { text: chars.join(''), offsets }
+}
+
+function locate(content, old, path) {
+  const multiple = () => new Error(`string appears multiple times in ${path}, provide more surrounding context to make it unique`)
+
+  const exact = content.indexOf(old)
+  if (exact !== -1) {
+    if (content.indexOf(old, exact + 1) !== -1) throw multiple()
+    return { start: exact, end: exact + old.length }
+  }
+
+  const normalizedContent = normalize(content)
+  const normalizedOld = normalize(old).text
+  if (!normalizedOld) throw new Error(`string not found in ${path}`)
+  const at = normalizedContent.text.indexOf(normalizedOld)
+  if (at === -1) throw new Error(`string not found in ${path}`)
+  if (normalizedContent.text.indexOf(normalizedOld, at + 1) !== -1) throw multiple()
+
+  return {
+    start: normalizedContent.offsets[at],
+    end: normalizedContent.offsets[at + normalizedOld.length - 1] + 1,
+  }
+}
+
+export function createEdit({ cwd, recorder, tracker }) {
+  return {
+    name: 'edit',
+    description: 'Replace oldText with newText in a file. oldText must appear exactly once unless replaceAll is set.',
+    schema: {
+      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      path: { type: 'string', description: 'file path, relative to the working directory or absolute' },
+      oldText: { type: 'string', description: 'exact text to replace, must be unique in the file' },
+      newText: { type: 'string', description: 'replacement text' },
+      replaceAll: { type: 'boolean', description: 'replace every occurrence', optional: true },
+    },
+    execute: async ({ path, oldText, newText, replaceAll }) => {
+      const full = resolve(cwd, path)
+      recorder.extra({ title: path })
+      const before = await readFile(full, 'utf-8')
+
+      let after
+      let splices
+      if (replaceAll) {
+        if (!oldText) throw new Error('oldText must not be empty when replaceAll is set')
+        if (!before.includes(oldText)) throw new Error(`string not found in ${path}`)
+        splices = []
+        for (let start = before.indexOf(oldText); start !== -1; start = before.indexOf(oldText, start + oldText.length)) {
+          splices.push({ start, oldText, newText })
+        }
+        after = before.split(oldText).join(newText)
+      } else {
+        const { start, end } = locate(before, oldText, path)
+        const actualOldText = before.slice(start, end)
+        splices = [{ start, oldText: actualOldText, newText }]
+        after = before.slice(0, start) + newText + before.slice(end)
+      }
+
+      await writeFile(full, after, 'utf-8')
+      const diff = makeDiff(path, before, after)
+      recorder.extra({ diff, revert: makeReversibleEdit(full, before, after, splices) })
+
+      const result = { ok: true, path, additions: diff.additions, deletions: diff.deletions }
+      const context = tracker.check(full)
+      if (context.length) result.context_from_agents_md = context
+      return result
+    },
+  }
+}

package/src/tools/glob.js

@@ -0,0 +1,43 @@
+import { execFile } from 'node:child_process'
+import fg from 'fast-glob'
+
+const MAX_RESULTS = 200
+
+function ripgrepGlob(pattern, cwd) {
+  return new Promise((resolve) => {
+    const args = ['--files', '--hidden', '--glob', pattern, '--glob', '!**/node_modules/**', '--glob', '!**/.git/**']
+    execFile('rg', args, { cwd, maxBuffer: 50 * 1024 * 1024 }, (err, stdout) => {
+      if (err && err.code !== 1) resolve(null)
+      else resolve(stdout ? stdout.split('\n').filter(Boolean) : [])
+    })
+  })
+}
+
+export function createGlob({ cwd, recorder }) {
+  return {
+    name: 'glob',
+    description: 'Find files matching a glob pattern, relative to the working directory. Respects .gitignore; use bash to look inside ignored paths.',
+    schema: {
+      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      pattern: { type: 'string', description: 'glob pattern, e.g. src/**/*.js' },
+      maxResults: { type: 'number', description: 'cap on returned paths, default 200', optional: true },
+    },
+    execute: async ({ pattern, maxResults = MAX_RESULTS }) => {
+      recorder.extra({ title: pattern })
+      let files = await ripgrepGlob(pattern, cwd)
+      if (files === null) {
+        files = await fg(pattern, {
+          cwd,
+          dot: true,
+          ignore: ['**/node_modules/**', '**/.git/**'],
+        })
+      }
+      recorder.extra({ fullOutput: files.join('\n') })
+      return {
+        files: files.slice(0, maxResults),
+        totalFound: files.length,
+        truncated: files.length > maxResults,
+      }
+    },
+  }
+}

package/src/tools/grep.js

@@ -0,0 +1,59 @@
+import { execFile } from 'node:child_process'
+import { relative, resolve } from 'node:path'
+
+const MAX_RESULTS = 200
+
+function runRipgrep(args, cwd) {
+  return new Promise((done) => {
+    execFile('rg', args, { cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout) => {
+      done(err && !stdout ? '' : stdout || '')
+    })
+  })
+}
+
+export function createGrep({ cwd, recorder }) {
+  return {
+    name: 'grep',
+    description: 'Search file contents with a regex using ripgrep. mode "content" returns matching lines, "files" returns matching file paths, "count" returns per-file match counts.',
+    schema: {
+      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      pattern: { type: 'string', description: 'regex pattern' },
+      path: { type: 'string', description: 'file or directory to search, defaults to the working directory', optional: true },
+      mode: { type: 'string', enum: ['content', 'files', 'count'], optional: true },
+      glob: { type: 'string', description: 'filter files by glob, e.g. *.js', optional: true },
+      ignoreCase: { type: 'boolean', optional: true },
+      context: { type: 'number', description: 'lines of context around matches', optional: true },
+      multiline: { type: 'boolean', description: 'allow patterns to span lines', optional: true },
+      limit: { type: 'number', description: 'max results, default 200', optional: true },
+    },
+    execute: async ({ pattern, path, mode = 'content', glob, ignoreCase, context, multiline, limit = MAX_RESULTS }) => {
+      if (typeof pattern !== 'string') throw new Error('grep pattern is required')
+      recorder.extra({ title: pattern })
+      const args = ['--no-heading', '--color=never', '--max-columns', '500', '--hidden', '--glob', '!**/.git/**']
+
+      if (mode === 'files') args.push('--files-with-matches')
+      else if (mode === 'count') args.push('--count')
+      else args.push('--line-number')
+
+      if (ignoreCase) args.push('--ignore-case')
+      if (multiline) args.push('--multiline', '--multiline-dotall')
+      if (glob) args.push('--glob', glob)
+      if (mode === 'content' && context) args.push('-C', String(context))
+
+      args.push(pattern.startsWith('-') ? '-e' : '--', pattern)
+      args.push(path ? resolve(cwd, path) : cwd)
+
+      const stdout = await runRipgrep(args, cwd)
+      const lines = stdout.split('\n').filter(Boolean)
+      recorder.extra({ fullOutput: lines.join('\n') })
+
+      const relativize = (line) => {
+        if (mode === 'files') return relative(cwd, line)
+        const m = line.match(/^(\/[^:]+):(.*)$/)
+        return m ? `${relative(cwd, m[1])}:${m[2]}` : line
+      }
+      const results = lines.map(relativize).slice(0, limit)
+      return { results, mode, totalMatches: lines.length, truncated: lines.length > limit }
+    },
+  }
+}

package/src/tools/index.js

@@ -0,0 +1,296 @@
+import { createRecorder, recorded } from './recorder.js'
+import { createRead } from './read.js'
+import { createWrite } from './write.js'
+import { createEdit } from './edit.js'
+import { createBash } from './bash.js'
+import { createGlob } from './glob.js'
+import { createGrep } from './grep.js'
+import { createWebTools } from './web.js'
+
+export function createToolset({ cwd, env, tracker, skills, shells, sessionId, sessionFile, wakeups, memory, agents, deliberations, onAgentsCollected, askUser, dredge, mcpTools = [], userTools = [], signal, maxToolCalls, maxAgentStarts, requireAgentPlan = false, allowNames, onToolUpdate }) {
+  const recorder = createRecorder(onToolUpdate)
+  let agentStarts = 0
+  let plannedAgentStarts = requireAgentPlan ? null : maxAgentStarts
+  const deps = { cwd, env, recorder, tracker, signal, shells, sessionId, sessionFile }
+
+  const local = [
+    createRead(deps),
+    createWrite(deps),
+    createEdit(deps),
+    createBash(deps),
+    createGlob(deps),
+    createGrep(deps),
+  ]
+
+  if (dredge) {
+    local.push(...createWebTools({ dredge, recorder, signal }))
+  }
+
+  if (shells) {
+    local.push(
+      {
+        name: 'shell_output',
+        description: 'Read recent output from a background shell started with bash background: true. Use only when intermediate output is needed to diagnose a suspected problem or make a decision before the shell exits. Do not use for routine progress polling; completion is delivered automatically, so if no independent work remains, end your turn and wait.',
+        schema: {
+          id: { type: 'string', description: 'the shell id' },
+          tail: { type: 'number', description: 'how many trailing lines to return, default 100', optional: true },
+        },
+        execute: ({ id, tail = 100 }) => {
+          const result = shells.output(id, { tail: Math.min(tail, 500) })
+          if (result.status === 'exited') {
+            result.note = 'This shell has exited and its output is complete. Do not call shell_output again for this shell.'
+          }
+          return result
+        },
+      },
+      {
+        name: 'shell_kill',
+        description: 'Stop a background shell by id.',
+        schema: {
+          id: { type: 'string', description: 'the shell id' },
+        },
+        execute: ({ id }) => shells.kill(id, 'model'),
+      },
+    )
+  }
+
+  if (wakeups) {
+    local.push(
+      {
+        name: 'schedule_wakeup',
+        description: 'Schedule a one-time wake-up: after the delay you receive a system notification carrying your note and can act on it. For a recurring loop, schedule the next wake-up at the end of each one. Do not use this to poll a background shell; its exit already notifies you. Wake-ups are lost if pico exits.',
+        schema: {
+          description: { type: 'string', description: 'briefly explain why this wake-up is needed, shown to the human watching' },
+          delaySeconds: { type: 'number', description: 'seconds from now, minimum 5' },
+          note: { type: 'string', description: 'what to do when you wake up; written to your future self' },
+        },
+        execute: ({ delaySeconds, note }) => {
+          const { id, at, seconds } = wakeups.schedule(delaySeconds, note)
+          return { wakeupId: id, firesAt: new Date(at).toString(), inSeconds: seconds }
+        },
+      },
+      {
+        name: 'cancel_wakeup',
+        description: 'Cancel a pending wake-up by id.',
+        schema: {
+          id: { type: 'string', description: 'the wake-up id' },
+        },
+        execute: ({ id }) => wakeups.cancel(id),
+      },
+      {
+        name: 'list_wakeups',
+        description: 'List your pending scheduled wake-ups: id, when each fires, and its note.',
+        schema: {},
+        execute: () => ({
+          wakeups: wakeups.list().map((w) => ({
+            id: w.id,
+            firesAt: new Date(w.at).toString(),
+            inSeconds: Math.max(0, Math.round((w.at - Date.now()) / 1000)),
+            note: w.note,
+          })),
+        }),
+      },
+    )
+  }
+
+  if (askUser) {
+    local.push({
+      name: 'ask_user',
+      description: 'Ask the user one or more focused questions when their answers are genuinely needed to continue. Supports free text, one choice, or multiple choices. Do not ask questions you can answer from available context.',
+      schema: {
+        questions: {
+          type: 'array',
+          description: 'questions to present, in order',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'short unique identifier' },
+              question: { type: 'string', description: 'clear question shown to the user' },
+              description: { type: 'string', description: 'brief context explaining why this matters', optional: true },
+              type: { type: 'string', enum: ['single', 'multi', 'text'], description: 'answer control' },
+              options: {
+                type: 'array', optional: true, description: 'choices for single or multi questions',
+                items: {
+                  type: 'object',
+                  properties: {
+                    label: { type: 'string' },
+                    description: { type: 'string', optional: true },
+                  },
+                  required: ['label'],
+                },
+              },
+              allowOther: { type: 'boolean', optional: true, description: 'allow a custom answer; defaults to true for choice questions' },
+            },
+            required: ['id', 'question', 'type'],
+          },
+        },
+      },
+      execute: ({ questions }) => {
+        if (!Array.isArray(questions) || questions.length === 0 || questions.length > 10) throw new Error('ask_user requires 1-10 questions')
+        const ids = new Set()
+        for (const question of questions) {
+          if (!question.id?.trim() || ids.has(question.id)) throw new Error('each question needs a unique non-empty id')
+          if (!question.question?.trim()) throw new Error(`question ${question.id} has no prompt`)
+          if (!['single', 'multi', 'text'].includes(question.type)) throw new Error(`question ${question.id} has an invalid type`)
+          if (question.type !== 'text' && (!Array.isArray(question.options) || question.options.length === 0)) throw new Error(`question ${question.id} needs at least one option`)
+          ids.add(question.id)
+        }
+        return askUser(questions)
+      },
+    })
+  }
+
+  if (agents) {
+    local.push(
+      {
+        name: 'agent_plan',
+        description: 'Declare the background worker budget for the current assistant turn before starting any workers. The main agent is excluded. Set count to the number of workers you intend to start this turn; collecting a worker does not restore budget. Interpret any user-requested count semantically; otherwise use the configured default.',
+        schema: {
+          count: { type: 'integer', description: `background workers permitted this turn, excluding the main agent (1-${maxAgentStarts || 100})` },
+          reason: { type: 'string', description: 'brief explanation of how the count follows the user request or research scope' },
+        },
+        execute: ({ count, reason }) => {
+          const ceiling = maxAgentStarts || 100
+          if (!Number.isInteger(count) || count < 1 || count > ceiling) throw new Error(`agent budget must be between 1 and ${ceiling}`)
+          if (agentStarts > 0) throw new Error('agent budget must be declared before starting agents')
+          plannedAgentStarts = count
+          return { agentLimit: count, reason }
+        },
+      },
+      {
+        name: 'agent_start',
+        description: 'Start one background worker, consuming one unit of the current turn\'s agent_plan budget. Workers do not receive the parent conversation, only the supplied prompt and their available project context and tools. Make the prompt self-contained by including all conversation-specific terms, goals, constraints, and decisions the worker cannot discover itself. Collected or completed workers do not restore budget within that turn. Continue only independent work until you collect its result with agent_collect.',
+        schema: {
+          prompt: { type: 'string', description: 'complete, self-contained task and desired output, including necessary context from the parent conversation' },
+          description: { type: 'string', description: 'short label shown to the user' },
+          tools: { type: 'array', items: { type: 'string' }, description: 'tool names to allow; omit for the configured worker tools', optional: true },
+        },
+        execute: ({ prompt, description, tools }) => {
+          if (plannedAgentStarts == null) throw new Error('call agent_plan before starting research agents')
+          if (agentStarts >= plannedAgentStarts) throw new Error(`agent limit reached for this turn (${plannedAgentStarts}); completed or collected workers do not restore budget within the turn`)
+          const agent = agents.start({ prompt, description, tools, sessionId, sessionFile })
+          agentStarts++
+          return { agentId: agent.id, status: agent.status, model: agent.model }
+        },
+      },
+      {
+        name: 'agent_list',
+        description: 'List background agents and their current status.',
+        schema: {},
+        execute: () => ({ agents: agents.list().map(({ id, description, model, status }) => ({ id, description, model, status })) }),
+      },
+      {
+        name: 'agent_collect',
+        description: 'Collect background agent results. Waits for any selected agents that are still running.',
+        schema: { ids: { type: 'array', items: { type: 'string' }, description: 'agent ids whose results to collect' } },
+        execute: async ({ ids }) => {
+          const requested = (ids || []).map(String)
+          const collected = await agents.collect(requested)
+          onAgentsCollected?.(collected.map((agent) => agent.id))
+          const found = new Set(collected.map((agent) => String(agent.id)))
+          return {
+            agents: [
+              ...collected.map(({ id, status, result, error }) => ({ id, status, result, error })),
+              ...requested.filter((id) => !found.has(id)).map((id) => ({
+                id,
+                status: 'unknown',
+                error: `no agent with id ${id}; it was never started, or was dismissed. Check agent_list rather than retrying.`,
+              })),
+            ],
+          }
+        },
+      },
+      {
+        name: 'agent_cancel',
+        description: 'Cancel a queued or running background agent.',
+        schema: { id: { type: 'string', description: 'agent id' } },
+        execute: ({ id }) => ({ cancelled: agents.cancel(id) }),
+      },
+    )
+  }
+
+  if (deliberations) {
+    local.push({
+      name: 'deliberate',
+      description: 'Evaluate competing approaches, challenge a proposal, or reach a consequential decision under genuine uncertainty through a bounded, evidence-seeking exchange between two full tool-using agents. When the user requests deliberation, call this tool immediately with a self-contained brief: do not research first or approximate deliberation with multiple ordinary agents. Its participants own all supporting research. Use ordinary agents when independent work can be divided and collected. Do not deliberate routine implementation or questions answerable through direct research.',
+      schema: {
+        brief: { type: 'string', description: 'self-contained decision, relevant context, constraints, and desired outcome' },
+        rounds: { type: 'integer', description: 'number of proposer-reviewer exchanges (1-5, default 3)', optional: true },
+      },
+      execute: ({ brief, rounds }) => deliberations.run({ brief, rounds, sessionId, sessionFile, signal }),
+    })
+  }
+
+  if (memory) {
+    local.push(
+      {
+        name: 'remember',
+        description: 'Save a durable memory for future sessions. Use for corrections, preferences, and non-obvious facts worth keeping: a flaky test, a build quirk, something the user asked you to remember. Do not save what the code or git history already records, or details that only matter this session. Never duplicate what a skill or AGENTS.md already covers: those are already in your context every session, and a memory copy goes stale the moment they are edited. If asked to learn something a skill covers, say the skill already covers it instead of saving. Choose scope by applicability: if the fact would hold in a different project, use global; if it is tied to this codebase or how the user works here, use project. Always state the chosen scope in your reply so the user can correct it, and if applicability is genuinely unclear, ask before saving.',
+        schema: {
+          name: { type: 'string', description: 'short kebab-case identifier' },
+          description: { type: 'string', description: 'one line used to decide when to recall this; write it as a hook, not a summary' },
+          content: { type: 'string', description: 'the memory itself' },
+          scope: { type: 'string', enum: ['project', 'global'], optional: true },
+        },
+        execute: async ({ name, description, content, scope }) => {
+          const saved = await memory.remember({ name, description, content, scope })
+          recorder.extra({ title: `${saved.name} (${saved.scope})` })
+          return saved
+        },
+      },
+      {
+        name: 'recall',
+        description: 'Load the full content of a saved memory by name. Your memory index is in the system prompt.',
+        schema: {
+          name: { type: 'string', description: 'the memory name from the index' },
+        },
+        execute: async ({ name }) => {
+          const found = await memory.recall(name)
+          recorder.extra({ title: found.name })
+          return found
+        },
+      },
+    )
+  }
+
+  if (skills?.list().length) {
+    local.push({
+      name: 'skill',
+      description: `Load a skill by name and follow its instructions. Available skills:\n${skills
+        .list()
+        .map((s) => `- ${s.name}: ${s.description}`)
+        .join('\n')}`,
+      schema: {
+        name: { type: 'string', description: 'skill name' },
+      },
+      execute: async ({ name }) => {
+        recorder.extra({ title: name })
+        const body = await skills.load(name)
+        if (!body) throw new Error(`no skill named ${name}`)
+        return { instructions: body }
+      },
+    })
+  }
+
+  const describedToolNames = new Set(['read', 'write', 'edit', 'bash', 'glob', 'grep', 'web_search', 'schedule_wakeup'])
+  const describedTools = new Set(local.filter((tool) => describedToolNames.has(tool.name)).map((tool) => tool.name))
+  const byName = new Map()
+  for (const tool of [...local, ...userTools, ...mcpTools]) {
+    if (allowNames && !allowNames.includes(tool.name)) continue
+    if (!byName.has(tool.name)) byName.set(tool.name, tool)
+  }
+  const tools = [...byName.values()].map((tool) => ({
+    ...tool,
+    execute: recorded(recorder, tool.name, async (args) => {
+      if (describedTools.has(tool.name) && !args.description?.trim()) {
+        throw new Error('description is required; retry with a brief explanation of why this call is needed')
+      }
+      if (maxToolCalls && recorder.entries.length >= maxToolCalls) {
+        throw new Error('tool call limit reached for this run; do not call more tools, summarize what you have and finish')
+      }
+      return tool.execute(args)
+    }),
+  }))
+
+  return { tools, recorder }
+}

package/src/tools/read.js

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+const MAX_LINES = 2000
+const MAX_LINE_LENGTH = 2000
+
+function isBinary(buffer) {
+  const len = Math.min(buffer.length, 8000)
+  for (let i = 0; i < len; i++) {
+    if (buffer[i] === 0) return true
+  }
+  return false
+}
+
+export function createRead({ cwd, recorder, tracker }) {
+  return {
+    name: 'read',
+    description: 'Read a file. Returns line-numbered content. Use offset/limit for large files.',
+    schema: {
+      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      path: { type: 'string', description: 'file path, relative to the working directory or absolute' },
+      offset: { type: 'number', description: '1-indexed line to start from', optional: true },
+      limit: { type: 'number', description: 'max lines to return', optional: true },
+    },
+    execute: async ({ path, offset = 1, limit = MAX_LINES }) => {
+      const full = resolve(cwd, path)
+      recorder.extra({ title: path })
+      const buf = await readFile(full)
+      if (isBinary(buf)) throw new Error(`${path} is a binary file`)
+      const lines = buf.toString('utf-8').split('\n')
+
+      const start = Math.max(0, offset - 1)
+      const count = Math.min(limit, MAX_LINES)
+      const sliced = lines.slice(start, start + count)
+      const numbered = sliced
+        .map((line, i) => `${start + i + 1}\t${line.length > MAX_LINE_LENGTH ? line.slice(0, MAX_LINE_LENGTH) + '…' : line}`)
+        .join('\n')
+
+      recorder.extra({ fullOutput: sliced.join('\n') })
+      const result = { content: numbered, totalLines: lines.length }
+      if (start + count < lines.length) {
+        result.note = `showing lines ${start + 1}-${start + sliced.length} of ${lines.length}`
+      }
+      const context = tracker.check(full)
+      if (context.length) result.context_from_agents_md = context
+      return result
+    },
+  }
+}

package/src/tools/recorder.js

@@ -0,0 +1,74 @@
+import { homedir } from 'node:os'
+
+function collapseHomePath(value) {
+  const home = homedir()
+  if (value === home) return '~'
+  if (value.startsWith(`${home}/`) || value.startsWith(`${home}\\`)) return `~${value.slice(home.length)}`
+  return value
+}
+
+export function defaultTitle(name, args = {}) {
+  const candidate = args.path || args.command || args.pattern || args.url || args.name
+  if (typeof candidate === 'string' && candidate) return collapseHomePath(candidate)
+  const raw = JSON.stringify(args)
+  if (!raw || raw === '{}') return name
+  return raw.length > 60 ? raw.slice(0, 60) + '…' : raw
+}
+
+export function createRecorder(onChange) {
+  return {
+    currentCall: null,
+    entries: [],
+    pending: null,
+    begin(name, args) {
+      this.pending = {
+        callId: this.currentCall?.id ?? null,
+        name,
+        title: defaultTitle(name, args),
+        description: args.description,
+        status: 'done',
+        startedAt: Date.now(),
+      }
+      onChange?.(this.pending)
+    },
+    extra(fields) {
+      if (!this.pending) return
+      const normalized = typeof fields.title === 'string'
+        ? { ...fields, title: collapseHomePath(fields.title) }
+        : fields
+      Object.assign(this.pending, normalized)
+      onChange?.(this.pending)
+    },
+    done(fields = {}) {
+      if (!this.pending) return
+      Object.assign(this.pending, fields, {
+        durationMs: Date.now() - this.pending.startedAt,
+      })
+      delete this.pending.startedAt
+      if (this.pending.fullOutput?.length > 200000) {
+        this.pending.fullOutput = this.pending.fullOutput.slice(0, 200000) + '\n[truncated]'
+      }
+      this.entries.push(this.pending)
+      this.pending = null
+    },
+  }
+}
+
+export function recorded(recorder, name, fn) {
+  return async (args) => {
+    recorder.begin(name, args)
+    try {
+      const result = await fn(args)
+      if (!recorder.pending?.fullOutput && result !== undefined) {
+        recorder.extra({
+          fullOutput: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+        })
+      }
+      recorder.done()
+      return result
+    } catch (err) {
+      recorder.done({ status: 'error', error: String(err.message || err) })
+      throw err
+    }
+  }
+}