@davait/aipictury 1.9.2

package/ext/feedback.js

@@ -0,0 +1,55 @@
+'use strict'
+// A problem report: what AIPictury needs to understand a problem — versions, settings, the
+// last lines of its log, your description — with keys, tokens and passwords taken out, saved
+// on this machine (~/.aipictury/feedback/). Sent to your AIPictury server only when you say so
+// (/bug, /feedback, or AIPictury: Report a Problem).
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { home } = require('./sessions')
+
+// Anything that looks like a secret. Checked by test/feedback-check.mjs.
+const SECRETS = [
+  /tvly-(?:dev|prod)-[\w-]{8,}/g, /hf_[A-Za-z0-9]{16,}/g, /sk-[A-Za-z0-9_-]{16,}/g, /gh[pousr]_[A-Za-z0-9]{20,}/g,
+  /xox[abprs]-[\w-]{10,}/g, /AKIA[0-9A-Z]{16}/g, /eyJ[\w-]{10,}\.[\w-]{10,}\.[\w-]{10,}/g,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+]
+// The token after "Bearer", then the value of a field named like a secret — never the word
+// "Bearer" itself, which would leave the token behind it.
+const BEARER = /(Bearer\s+)(?!\[redacted\])[^\s"',}]{4,}/gi
+const NAMED = /((?:api[_-]?key|access[_-]?token|auth[_-]?token|token|secret|password|passwd|authorization)["']?\s*[:=]\s*["']?)(?!Bearer\b|\[redacted\])([^\s"',}]{4,})/gi
+
+function redact(text) {
+  let out = String(text ?? '')
+  for (const re of SECRETS) out = out.replace(re, '[redacted]')
+  out = out.replace(BEARER, (_, key) => `${key}[redacted]`)
+  return out.replace(NAMED, (_, key) => `${key}[redacted]`)
+}
+
+function redactDeep(value) {
+  if (typeof value === 'string') return redact(value)
+  if (Array.isArray(value)) return value.map(redactDeep)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => (
+      /key|token|secret|password|authorization|headers|env/i.test(k) && typeof v !== 'boolean' ? [k, '[redacted]'] : [k, redactDeep(v)])))
+  }
+  return value
+}
+
+const dir = () => path.join(home(), 'feedback')
+
+/** Writes a report: kind "bug" or "feedback". */
+function save({ kind = 'report', description = '', versions = {}, settings = {}, log = [], extra = {} }) {
+  fs.mkdirSync(dir(), { recursive: true })
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const file = path.join(dir(), `${stamp}-${kind}.json`)
+  const body = redactDeep({
+    kind, created: new Date().toISOString(), description,
+    versions: { ...versions, platform: `${os.platform()} ${os.release()}`, node: process.version },
+    settings, log, ...extra,
+  })
+  fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 })
+  return { file, body }
+}
+
+module.exports = { redact, redactDeep, save, dir }

package/ext/files.js

@@ -0,0 +1,565 @@
+'use strict'
+// The file tools, shaped after Claude Code's Read, Write, Edit, Grep, Glob and NotebookEdit.
+//
+// What they guard against, each learnt the hard way somewhere:
+// - The user's unsaved typing. A file open in the editor with changes not yet saved is
+//   saved before the agent reads or writes it, so the agent never works from a stale copy
+//   and never writes over what the user just typed.
+// - Editing blind. A file must be read before it is changed, and if it changed on disk
+//   since (the user, a formatter, a command), the edit is refused until it is read again.
+// - Whitespace. Local models retype tabs as spaces and drop \r: an edit that matches
+//   only once indentation and line endings are set aside is applied in the file's own
+//   style rather than refused, and one that does not match at all is answered with the
+//   closest passage, so the next try lands.
+
+const vscode = require('vscode')
+const fs = require('fs')
+const path = require('path')
+const { execFile } = require('child_process')
+const { resolve, root, rel } = require('./paths')
+const { safeSlice } = require('./text')
+
+// ignoreBOM: keep a byte-order mark in the text, so an edit can put it back (the default
+// decoder drops it silently, and every edited file lost its BOM).
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+const encoder = new TextEncoder()
+
+const PAGE_LINES = 2000            // lines per read, as Claude Code
+const MAX_LINE = 2000              // characters per line shown
+const MAX_READ_CHARS = 120_000     // one page never more than this
+const GLOB_CAP = 100
+const GREP_OUTPUT_CAP = 30_000
+
+// ---- the editor's own copy ----
+
+/** The open document for a file, if any. */
+function openDocument(uri) {
+  return vscode.workspace.textDocuments.find((d) => d.uri.toString() === uri.toString())
+}
+
+/** Saves the user's unsaved changes to a file before the agent touches it. With the
+ *  autosave setting off, the unsaved text is read instead and writes are refused. */
+const SAVE_LIMIT = 15_000
+
+async function settle(uri) {
+  const doc = openDocument(uri)
+  if (!doc || !doc.isDirty) return { dirty: false }
+  const autosave = vscode.workspace.getConfiguration('aipictury').get('autosave', true)
+  // Saving runs format-on-save and other participants; one that hangs must not hold the
+  // agent: past SAVE_LIMIT the editor's own text is used, as with autosave off.
+  if (autosave) {
+    let timer
+    const late = new Promise((resolve) => { timer = setTimeout(() => resolve(false), SAVE_LIMIT) })
+    const saved = await Promise.race([Promise.resolve(doc.save()).catch(() => false), late])
+    clearTimeout(timer)
+    if (saved) return { dirty: false, saved: true }
+  }
+  return { dirty: true, text: doc.getText() }
+}
+
+async function stat(uri) {
+  try { return await vscode.workspace.fs.stat(uri) } catch { return null }
+}
+
+// What the agent last saw of each file, per conversation: its modification time and
+// size. An edit is allowed only against what was seen.
+function remember(session, uri, info) {
+  if (!session) return
+  session.seen ||= new Map()
+  session.seen.set(uri.toString(), { mtime: info.mtime, size: info.size })
+}
+
+async function checkFresh(session, uri, relPath) {
+  if (!session) return
+  const seen = session.seen?.get(uri.toString())
+  if (!seen) {
+    throw new Error(`${relPath} has not been read in this conversation — read it with read_file first, `
+      + 'so the change is made against what the file really holds')
+  }
+  const now = await stat(uri)
+  if (now && (now.mtime !== seen.mtime || now.size !== seen.size)) {
+    throw new Error(`${relPath} changed since you read it (the user, a formatter or a command edited it) — `
+      + 'read it again before changing it')
+  }
+}
+
+const BOM = String.fromCharCode(0xfeff)
+/** A file's text with what must be kept aside: a byte-order mark and CRLF line endings. */
+function parseText(raw) {
+  const bom = raw.startsWith(BOM)
+  let text = bom ? raw.slice(1) : raw
+  const crlf = /\r\n/.test(text) && !/(^|[^\r])\n/.test(text.replace(/\r\n/g, ''))
+  if (/\r\n/.test(text)) text = text.replace(/\r\n/g, '\n')
+  return { text, bom, crlf }
+}
+const unparse = ({ bom, crlf }, text) => (bom ? BOM : '') + (crlf ? text.replace(/\n/g, '\r\n') : text)
+
+const looksBinary = (bytes) => bytes.subarray(0, 8000).includes(0)
+
+// ---- read ----
+
+async function readFile(args, ctx = {}) {
+  const uri = resolve(args.path)
+  const info = await stat(uri)
+  if (!info) throw new Error(`${args.path} does not exist — use glob or list_files to find the right path`)
+  if (info.type & vscode.FileType.Directory) throw new Error(`${args.path} is a directory — use list_files or glob`)
+  const ext = path.extname(uri.fsPath).toLowerCase()
+  if (ext === '.ipynb') return readNotebook(uri, args, ctx, info)
+  if (ctx.readSpecial && ['.pdf', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'].includes(ext)) {
+    remember(ctx.session, uri, info)
+    return ctx.readSpecial(uri, args)
+  }
+  const unsaved = await settle(uri)
+  const bytes = unsaved.dirty ? encoder.encode(unsaved.text) : await vscode.workspace.fs.readFile(uri)
+  remember(ctx.session, uri, await stat(uri) || info)
+  if (looksBinary(bytes)) return `${args.path} is a binary file (${bytes.length} bytes) — it cannot be read as text`
+  const { text } = parseText(decoder.decode(bytes))
+  if (!text.length) return `${args.path} exists but is empty`
+  const lines = text.split('\n')
+  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop()
+  const offset = Math.max(1, Math.floor(Number(args.offset) || 1))
+  if (offset > lines.length) return `${args.path} has only ${lines.length} lines — offset ${offset} is past the end`
+  const limit = Math.max(1, Math.floor(Number(args.limit) || PAGE_LINES))
+  const out = []
+  let chars = 0
+  let last = offset - 1
+  for (let i = offset - 1; i < Math.min(lines.length, offset - 1 + limit); i += 1) {
+    let line = lines[i]
+    if (line.length > MAX_LINE) line = `${safeSlice(line, 0, MAX_LINE)} … [line cut at ${MAX_LINE} characters]`
+    const row = `${i + 1}\t${line}`
+    if (chars + row.length > MAX_READ_CHARS && out.length) break
+    out.push(row); chars += row.length + 1; last = i + 1
+  }
+  let note = ''
+  if (last < lines.length) {
+    note = `\n\n[showing lines ${offset}–${last} of ${lines.length}. Call read_file with offset=${last + 1} for more, `
+      + 'or grep for the part you need.]'
+  }
+  return (unsaved.dirty ? '[the editor holds unsaved changes to this file; this is the unsaved text]\n' : '')
+    + out.join('\n') + note
+}
+
+async function readNotebook(uri, args, ctx, info) {
+  const nb = JSON.parse(decoder.decode(await vscode.workspace.fs.readFile(uri)))
+  remember(ctx.session, uri, info)
+  const cells = (nb.cells || []).map((c, i) => {
+    const src = Array.isArray(c.source) ? c.source.join('') : String(c.source || '')
+    const outputs = (c.outputs || []).map((o) => {
+      const t = o.text || o.data?.['text/plain'] || (o.ename ? `${o.ename}: ${o.evalue}` : '')
+      const s = Array.isArray(t) ? t.join('') : String(t || '')
+      return o.data?.['image/png'] ? '[image output]' : safeSlice(s, 0, 2000)
+    }).filter(Boolean)
+    return `<cell index=${i} id=${c.id || i} type=${c.cell_type}>\n${src}\n</cell>`
+      + (outputs.length ? `\n<outputs>\n${outputs.join('\n')}\n</outputs>` : '')
+  })
+  return `${args.path}: ${cells.length} cells (edit them with notebook_edit)\n\n${cells.join('\n\n')}`
+}
+
+// ---- write ----
+
+async function writeFile(args, ctx = {}) {
+  const uri = resolve(args.path)
+  const content = String(args.content ?? '')
+  const existing = await stat(uri)
+  let style = { bom: false, crlf: false }
+  if (existing) {
+    const unsaved = await settle(uri)
+    if (unsaved.dirty) throw new Error(`${args.path} has unsaved changes in the editor — ask the user to save or discard them`)
+    await checkFresh(ctx.session, uri, args.path)
+    style = parseText(decoder.decode(await vscode.workspace.fs.readFile(uri)))
+  }
+  await vscode.workspace.fs.createDirectory(vscode.Uri.joinPath(uri, '..'))
+  await vscode.workspace.fs.writeFile(uri, encoder.encode(unparse(style, content.replace(/\r\n/g, '\n'))))
+  remember(ctx.session, uri, await stat(uri))
+  const lines = content ? content.split('\n').length : 0
+  return `${existing ? 'rewrote' : 'created'} ${args.path} (${lines} lines)`
+}
+
+// ---- edit ----
+
+const lead = (line) => line.match(/^[ \t]*/)[0]
+
+/** Every place `needle` occurs in `hay`, as offsets. */
+function occurrences(hay, needle) {
+  const found = []
+  for (let i = hay.indexOf(needle); i !== -1; i = hay.indexOf(needle, i + Math.max(1, needle.length))) found.push(i)
+  return found
+}
+
+const lineOf = (text, offset) => text.slice(0, offset).split('\n').length
+
+/** A match that ignores indentation and trailing spaces, line by line. Returns the line
+ *  ranges in the file whose trimmed lines equal the needle's trimmed lines. */
+function looseMatches(fileLines, needleLines) {
+  const want = needleLines.map((l) => l.trim())
+  while (want.length && !want[0]) want.shift()
+  while (want.length && !want[want.length - 1]) want.pop()
+  if (!want.length) return []
+  const hits = []
+  for (let i = 0; i + want.length <= fileLines.length; i += 1) {
+    let ok = true
+    for (let k = 0; k < want.length && ok; k += 1) ok = fileLines[i + k].trim() === want[k]
+    if (ok) hits.push({ start: i, end: i + want.length })
+  }
+  return hits
+}
+
+/** Re-indents the model's replacement in the file's style: the model's indentation of its
+ *  first line is mapped onto the file's, and tabs or spaces follow the file. */
+function reindent(newText, modelFirst, fileFirst) {
+  const from = lead(modelFirst)
+  const to = lead(fileFirst)
+  const tabs = to.includes('\t') && !from.includes('\t')
+  const unit = tabs && to.length ? Math.max(1, Math.round(from.length / to.length)) || 4 : 0
+  return newText.split('\n').map((line) => {
+    if (!line.trim()) return line
+    let l = lead(line)
+    let body = line.slice(l.length)
+    if (tabs) {
+      const spaces = l.replace(/\t/g, ' '.repeat(unit)).length
+      return '\t'.repeat(Math.floor(spaces / unit)) + ' '.repeat(spaces % unit) + body
+    }
+    if (l.startsWith(from)) return to + l.slice(from.length) + body
+    return line
+  }).join('\n')
+}
+
+/** The passage of the file most like the one asked for, to show the model on a miss. */
+function closest(fileLines, needleLines) {
+  const want = needleLines.map((l) => l.trim()).filter(Boolean)
+  if (!want.length) return null
+  let best = null
+  for (let i = 0; i < fileLines.length; i += 1) {
+    let score = 0
+    for (let k = 0; k < want.length && i + k < fileLines.length; k += 1) {
+      const a = fileLines[i + k].trim()
+      if (a === want[k]) score += 1
+      else if (a && want[k] && (a.includes(want[k]) || want[k].includes(a))) score += 0.5
+    }
+    if (!best || score > best.score) best = { i, score }
+  }
+  if (!best || best.score === 0) return null
+  const from = Math.max(0, best.i - 1)
+  const to = Math.min(fileLines.length, best.i + want.length + 1)
+  return { from: from + 1, to, text: fileLines.slice(from, to).map((l, k) => `${from + k + 1}\t${l}`).join('\n') }
+}
+
+/** Applies one replacement to `text`. Throws with guidance when it cannot. */
+function replaceOnce(text, oldText, newText, replaceAll, where) {
+  const oldN = String(oldText ?? '').replace(/\r\n/g, '\n')
+  const newN = String(newText ?? '').replace(/\r\n/g, '\n')
+  if (!oldN) throw new Error(`${where}old_text is empty — to create a file use write_file`)
+  if (oldN === newN) throw new Error(`${where}old_text and new_text are the same — nothing would change`)
+  const exact = occurrences(text, oldN)
+  if (exact.length === 1 || (exact.length > 1 && replaceAll)) {
+    return { text: replaceAll ? text.split(oldN).join(newN) : text.slice(0, exact[0]) + newN + text.slice(exact[0] + oldN.length),
+      count: replaceAll ? exact.length : 1, loose: false }
+  }
+  if (exact.length > 1) {
+    throw new Error(`${where}old_text appears ${exact.length} times (lines ${exact.map((o) => lineOf(text, o)).join(', ')}). `
+      + 'Include more surrounding lines to make it unique, or set replace_all to change every one')
+  }
+  // Not there as typed: try again setting indentation and trailing spaces aside.
+  const lines = text.split('\n')
+  const needle = oldN.split('\n')
+  const loose = looseMatches(lines, needle)
+  if (loose.length === 1 || (loose.length > 1 && replaceAll)) {
+    const firstModel = needle.find((l) => l.trim()) || ''
+    let out = lines
+    let shift = 0
+    for (const hit of loose) {
+      const replacement = reindent(newN, firstModel, out[hit.start + shift]).split('\n')
+      out = [...out.slice(0, hit.start + shift), ...replacement, ...out.slice(hit.end + shift)]
+      shift += replacement.length - (hit.end - hit.start)
+      if (!replaceAll) break
+    }
+    return { text: out.join('\n'), count: replaceAll ? loose.length : 1, loose: true }
+  }
+  if (loose.length > 1) {
+    throw new Error(`${where}old_text matches ${loose.length} places once indentation is ignored (lines `
+      + `${loose.map((h) => h.start + 1).join(', ')}). Include more surrounding lines to make it unique`)
+  }
+  const near = closest(lines, needle)
+  throw new Error(`${where}old_text was not found in the file`
+    + (near ? `. The closest passage is lines ${near.from}–${near.to}:\n${near.text}\nCopy old_text exactly from it `
+      + '(without the line numbers) and try again' : ' — read the file again and copy the passage exactly'))
+}
+
+async function editFile(args, ctx = {}) {
+  const uri = resolve(args.path)
+  if (!(await stat(uri))) throw new Error(`${args.path} does not exist — create it with write_file`)
+  const unsaved = await settle(uri)
+  if (unsaved.dirty) throw new Error(`${args.path} has unsaved changes in the editor — ask the user to save or discard them`)
+  await checkFresh(ctx.session, uri, args.path)
+  const raw = decoder.decode(await vscode.workspace.fs.readFile(uri))
+  const style = parseText(raw)
+  const edits = Array.isArray(args.edits) && args.edits.length
+    ? args.edits : [{ old_text: args.old_text, new_text: args.new_text, replace_all: args.replace_all }]
+  let text = style.text
+  let count = 0
+  let loose = false
+  edits.forEach((e, i) => {
+    const r = replaceOnce(text, e.old_text, e.new_text, !!e.replace_all, edits.length > 1 ? `edit ${i + 1}: ` : '')
+    text = r.text; count += r.count; loose ||= r.loose
+  })
+  await vscode.workspace.fs.writeFile(uri, encoder.encode(unparse(style, text)))
+  remember(ctx.session, uri, await stat(uri))
+  return `edited ${args.path}: ${count} replacement${count === 1 ? '' : 's'}`
+    + (loose ? ' (matched ignoring indentation; the new text was indented the way the file is)' : '')
+}
+
+// ---- after a change: what the editor now reports ----
+
+/** Errors the language tools report for a file shortly after it changed — the way Claude
+ *  Code reports type errors after each edit. Waits up to `ms` for fresh diagnostics. */
+async function diagnosticsAfter(uri, ms = 2500) {
+  try {
+    const doc = await vscode.workspace.openTextDocument(uri)   // wakes the language server for it
+    if (!doc) return ''
+  } catch { return '' }
+  await new Promise((done) => {
+    const timer = setTimeout(finish, ms)
+    const sub = vscode.languages.onDidChangeDiagnostics((e) => {
+      if (e.uris.some((u) => u.toString() === uri.toString())) { clearTimeout(timer); setTimeout(finish, 300) }
+    })
+    function finish() { sub.dispose(); done() }
+  })
+  const errors = vscode.languages.getDiagnostics(uri).filter((d) => d.severity === vscode.DiagnosticSeverity.Error)
+  if (!errors.length) return ''
+  return `\n\nThe editor now reports ${errors.length} error${errors.length === 1 ? '' : 's'} in this file:\n`
+    + errors.slice(0, 10).map((d) => `  line ${d.range.start.line + 1}: ${d.message.split('\n')[0]}`).join('\n')
+    + (errors.length > 10 ? `\n  … ${errors.length - 10} more` : '')
+}
+
+// ---- search: ripgrep, the one VS Code ships ----
+
+let rgPath
+function ripgrep() {
+  if (rgPath !== undefined) return rgPath
+  const app = vscode.env.appRoot
+  const arch = `${process.platform}-${process.arch}`
+  const candidates = [
+    path.join(app, 'node_modules.asar.unpacked', '@vscode', 'ripgrep-universal', 'bin', arch, 'rg'),
+    path.join(app, 'node_modules.asar.unpacked', '@vscode', 'ripgrep', 'bin', 'rg'),
+    path.join(app, 'node_modules', '@vscode', 'ripgrep', 'bin', 'rg'),
+  ].map((p) => (process.platform === 'win32' ? `${p}.exe` : p))
+  // In the terminal (cli/) without VS Code installed: a ripgrep on the PATH.
+  const onPath = String(process.env.PATH || '').split(path.delimiter).filter(Boolean)
+    .map((dir) => path.join(dir, process.platform === 'win32' ? 'rg.exe' : 'rg'))
+  rgPath = [...candidates, ...onPath].find((p) => { try { return fs.statSync(p).isFile() } catch { return false } }) || null
+  return rgPath
+}
+
+function rg(args, cwd, signal) {
+  return new Promise((done, fail) => {
+    execFile(ripgrep(), args, { cwd, maxBuffer: 20 * 1024 * 1024, timeout: 30_000, signal },
+      (error, stdout, stderr) => {
+        // Exit 1 is ripgrep's "nothing matched"; 2 is an error (a bad pattern, usually).
+        if (error && error.code !== 1) {
+          if (error.name === 'AbortError') return fail(error)
+          return fail(new Error((stderr || error.message).trim().split('\n').slice(0, 4).join('\n')))
+        }
+        done(stdout)
+      })
+  })
+}
+
+const SKIP = ['!.git', '!node_modules', '!.venv', '!__pycache__']
+
+/** The files ripgrep would search under `dir`: .gitignore respected unless `ignored`. */
+async function listAll(dir, ignored, signal) {
+  const flags = ['--files', '--hidden', ...SKIP.flatMap((g) => ['-g', g])]
+  if (ignored) flags.push('--no-ignore')
+  flags.push('--', dir)
+  return (await rg(flags, root().fsPath, signal)).replace(/\r/g, '').split('\n').filter(Boolean).map((l) => l.replace(/^\.\//, ''))
+}
+
+/** A glob as a test on paths: ** any folders, * and ? within a name, {a,b} alternatives,
+ *  [abc] classes. A pattern without a slash matches the file name anywhere (as in
+ *  .gitignore); one with a slash matches the path from the root or from `base`. */
+function globRegExp(glob) {
+  let re = ''
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') {
+      if (glob[i + 2] === '/') { re += '(?:.*/)?'; i += 2 } else { re += '.*'; i += 1 }
+    } else if (c === '*') re += '[^/]*'
+    else if (c === '?') re += '[^/]'
+    else if (c === '{') {
+      const end = glob.indexOf('}', i)
+      if (end === -1) { re += '\\{'; continue }
+      re += `(?:${glob.slice(i + 1, end).split(',').map((alt) => globRegExp(alt).source.slice(1, -1)).join('|')})`
+      i = end
+    } else if (c === '[') {
+      const end = glob.indexOf(']', i)
+      if (end === -1) { re += '\\['; continue }
+      re += glob.slice(i, end + 1).replace(/^\[!/, '[^')
+      i = end
+    } else re += /[.+^$()|\\]/.test(c) ? `\\${c}` : c
+  }
+  return new RegExp(`^${re}$`)
+}
+
+function matcher(pattern, base) {
+  const re = globRegExp(pattern.replace(/^\.\//, ''))
+  const bare = !pattern.includes('/')
+  const prefix = base && base !== '.' ? `${base.replace(/\/$/, '')}/` : ''
+  return (file) => (bare ? re.test(path.posix.basename(file))
+    : re.test(file) || (prefix && file.startsWith(prefix) && re.test(file.slice(prefix.length))))
+}
+
+/** The directory or file a search starts from, relative to the root, and whether it is a file. */
+async function scope(given) {
+  const uri = resolve(given || '.')
+  const info = await stat(uri)
+  if (!info) throw new Error(`${given} does not exist`)
+  return { uri, rel: path.relative(root().fsPath, uri.fsPath) || '.', file: !(info.type & vscode.FileType.Directory) }
+}
+
+async function grep(args, ctx = {}) {
+  const pattern = String(args.pattern ?? args.query ?? '')
+  if (!pattern) throw new Error('pattern is required')
+  const where = await scope(args.path)
+  const mode = ['content', 'count', 'files_with_matches'].includes(args.output_mode) ? args.output_mode
+    : (args.query !== undefined && args.output_mode === undefined ? 'content' : 'files_with_matches')
+  if (!ripgrep()) return grepFallback(pattern, where, args, mode)
+  const flags = ['--color', 'never', '--hidden', '--max-columns', '400', '--max-columns-preview']
+  for (const g of SKIP) flags.push('-g', g)
+  if (args.case_insensitive || args['-i']) flags.push('-i')
+  if (args.fixed_strings || args.query !== undefined) flags.push('-F')
+  if (args.multiline) flags.push('-U', '--multiline-dotall')
+  // rg's -g overrides .gitignore; the glob is applied to what it would search instead.
+  let allowed = null
+  if (args.glob) {
+    const keep = matcher(String(args.glob), where.file ? '' : where.rel)
+    const list = where.file ? [where.rel] : (await listAll(where.rel, false, ctx.signal)).filter(keep)
+    if (!list.length) return `no files match ${args.glob}${where.rel !== '.' ? ` in ${where.rel}` : ''}`
+    allowed = list
+  }
+  if (args.type) flags.push('-t', String(args.type))
+  if (mode === 'files_with_matches') flags.push('-l', '--sortr', 'modified')
+  else if (mode === 'count') flags.push('-c')
+  else {
+    flags.push('-n', '--no-heading')
+    const c = (k) => Math.min(20, Math.max(0, Number(args[k]) || 0))
+    if (c('context')) flags.push('-C', String(c('context')))
+    if (c('before')) flags.push('-B', String(c('before')))
+    if (c('after')) flags.push('-A', String(c('after')))
+  }
+  flags.push('-e', pattern, '--', ...(allowed ? allowed.slice(0, 4000) : [where.rel]))
+  const out = (await rg(flags, root().fsPath, ctx.signal)).replace(/\r/g, '')
+  let rows = out.split('\n').filter(Boolean).map((l) => l.replace(/^\.\//, ''))
+  if (!rows.length) return `no match for ${JSON.stringify(pattern)}${where.rel !== '.' ? ` in ${where.rel}` : ''}`
+  const total = rows.length
+  const offset = Math.max(0, Number(args.offset) || 0)
+  const limit = Math.max(1, Number(args.head_limit) || (mode === 'content' ? 250 : 100))
+  rows = rows.slice(offset, offset + limit)
+  if (!rows.length) return `no entries at offset ${offset} (there are ${total})`
+  let text = rows.join('\n')
+  if (text.length > GREP_OUTPUT_CAP) text = `${safeSlice(text, 0, GREP_OUTPUT_CAP)}\n…`
+  const more = total - offset - rows.length
+  const head = mode === 'files_with_matches' ? `${total} file${total === 1 ? '' : 's'} (newest first)`
+    : mode === 'count' ? `${total} file${total === 1 ? '' : 's'} with matches` : `${total} line${total === 1 ? '' : 's'}`
+  return `${head}:\n${text}${more > 0 ? `\n\n[${more} more — call again with offset=${offset + rows.length}, or narrow with path/glob]` : ''}`
+}
+
+/** Without ripgrep (it should always be there): a plain scan, regex supported. */
+async function grepFallback(pattern, where, args, mode) {
+  let re
+  try { re = new RegExp(pattern, args.case_insensitive ? 'i' : '') } catch (e) { throw new Error(`bad pattern: ${e.message}`, { cause: e }) }
+  const files = where.file ? [where.uri]
+    : await vscode.workspace.findFiles(new vscode.RelativePattern(where.uri, args.glob || '**/*'),
+      '**/{node_modules,.git,.venv,__pycache__}/**', 5000)
+  const rows = []
+  for (const file of files) {
+    let text
+    try { const b = await vscode.workspace.fs.readFile(file); if (looksBinary(b)) continue; text = decoder.decode(b) } catch { continue }
+    const lines = text.split('\n')
+    const hits = lines.map((l, i) => (re.test(l) ? i : -1)).filter((i) => i >= 0)
+    if (!hits.length) continue
+    const r = rel(file)
+    if (mode === 'files_with_matches') rows.push(r)
+    else if (mode === 'count') rows.push(`${r}:${hits.length}`)
+    else hits.forEach((i) => rows.push(`${r}:${i + 1}:${lines[i].slice(0, 400)}`))
+    if (rows.length > 2000) break
+  }
+  return rows.length ? rows.slice(0, 250).join('\n') : `no match for ${JSON.stringify(pattern)}`
+}
+
+async function glob(args, ctx = {}) {
+  const pattern = String(args.pattern || '')
+  if (!pattern) throw new Error('pattern is required, e.g. **/*.ts or src/**/*.test.js')
+  const where = await scope(args.path)
+  if (where.file) throw new Error(`${args.path} is a file; glob searches a directory`)
+  let files
+  if (ripgrep()) {
+    // Every file ripgrep would search (so .gitignore applies), then the pattern — rg's own
+    // -g would override .gitignore and list ignored files too.
+    files = (await listAll(where.rel, !!args.include_ignored, ctx.signal)).filter(matcher(pattern, where.rel))
+  } else {
+    files = (await vscode.workspace.findFiles(new vscode.RelativePattern(where.uri, pattern), '**/{node_modules,.git}/**', 5000)).map(rel)
+  }
+  if (!files.length) return `no files match ${pattern}${where.rel !== '.' ? ` in ${where.rel}` : ''}`
+  const dated = files.map((f) => {
+    let m = 0
+    try { m = fs.statSync(path.join(root().fsPath, f)).mtimeMs } catch { /* gone */ }
+    return { f, m }
+  }).sort((a, b) => b.m - a.m)
+  const shown = dated.slice(0, GLOB_CAP).map((d) => d.f)
+  return shown.join('\n') + (files.length > GLOB_CAP
+    ? `\n\n[${files.length} files match; the ${GLOB_CAP} most recently changed are shown — narrow the pattern or path]` : '')
+}
+
+async function listFiles(args) {
+  const dir = resolve(args.path || '.')
+  const entries = await vscode.workspace.fs.readDirectory(dir)
+  const lines = entries
+    .filter(([name]) => !['.git', 'node_modules', '.DS_Store'].includes(name))
+    .map(([name, kind]) => (kind & vscode.FileType.Directory ? `${name}/` : name))
+    .sort()
+  if (!lines.length) return '(empty directory)'
+  return lines.slice(0, 600).join('\n') + (lines.length > 600 ? `\n… ${lines.length - 600} more` : '')
+}
+
+// ---- notebooks ----
+
+async function notebookEdit(args, ctx = {}) {
+  const uri = resolve(args.path)
+  if (!uri.fsPath.endsWith('.ipynb')) throw new Error('notebook_edit is for .ipynb files; use edit_file for others')
+  await checkFresh(ctx.session, uri, args.path)
+  const mode = ['replace', 'insert', 'delete'].includes(args.edit_mode) ? args.edit_mode : 'replace'
+  const nb = JSON.parse(decoder.decode(await vscode.workspace.fs.readFile(uri)))
+  nb.cells ||= []
+  const find = () => {
+    if (args.cell_id !== undefined && args.cell_id !== null && args.cell_id !== '') {
+      const byId = nb.cells.findIndex((c) => String(c.id) === String(args.cell_id))
+      if (byId !== -1) return byId
+      const n = Number(args.cell_id)
+      if (Number.isInteger(n) && n >= 0 && n < nb.cells.length) return n
+      throw new Error(`no cell with id ${args.cell_id} — read the notebook to see the cell ids`)
+    }
+    return mode === 'insert' ? -1 : (() => { throw new Error('cell_id is required') })()
+  }
+  const at = find()
+  const source = String(args.new_source ?? '').split(/(?<=\n)/)
+  const type = args.cell_type === 'markdown' ? 'markdown' : 'code'
+  if (mode === 'delete') nb.cells.splice(at, 1)
+  else if (mode === 'insert') {
+    const cell = { cell_type: type, metadata: {}, source, id: Math.random().toString(36).slice(2, 10) }
+    if (type === 'code') Object.assign(cell, { outputs: [], execution_count: null })
+    nb.cells.splice(at + 1, 0, cell)
+  } else {
+    const cell = nb.cells[at]
+    cell.source = source
+    if (args.cell_type) cell.cell_type = type
+    if (cell.cell_type === 'code') { cell.outputs = []; cell.execution_count = null }
+  }
+  const indent = /\n( +)"/.exec(decoder.decode(await vscode.workspace.fs.readFile(uri)))?.[1]?.length || 1
+  await vscode.workspace.fs.writeFile(uri, encoder.encode(`${JSON.stringify(nb, null, indent)}\n`))
+  remember(ctx.session, uri, await stat(uri))
+  return `${mode === 'delete' ? 'deleted' : mode === 'insert' ? 'inserted' : 'replaced'} a cell in ${args.path} `
+    + `(${nb.cells.length} cells now)`
+}
+
+module.exports = { globRegExp, matcher, readFile, writeFile, editFile, grep, glob, listFiles, notebookEdit, diagnosticsAfter,
+  replaceOnce, parseText, settle, checkFresh, remember, stat, ripgrep, reindent, looseMatches }