@davait/aipictury 1.9.2

package/ext/tools.js

@@ -0,0 +1,781 @@
+'use strict'
+// What the agent is allowed to do to the workspace, and the guards around it.
+//
+// Everything here runs in the editor, never on the server: file access belongs where
+// the user's trust already is. Each tool states its shape for the model and returns a
+// string, because that is what goes back into the conversation.
+
+const vscode = require('vscode')
+const gpuServer = require('./gpuServer')
+const { resolve, root, rel } = require('./paths')
+const files = require('./files')
+const { codeIntel, OPS } = require('./lsp')
+const shell = require('./shell')
+const browser = require('./browser')
+const context = require('./context')
+
+const MAX_MATCHES = 80
+const decoder = new TextDecoder()
+const encoder = new TextEncoder()
+
+async function listOpen() {
+  const open = vscode.window.visibleTextEditors.map((e) => vscode.workspace.asRelativePath(e.document.uri))
+  const active = vscode.window.activeTextEditor
+  const selection = active && !active.selection.isEmpty
+    ? active.document.getText(active.selection).slice(0, 8000) : ''
+  return JSON.stringify({
+    open,
+    active: active ? vscode.workspace.asRelativePath(active.document.uri) : null,
+    selection,
+    selectionLines: active && !active.selection.isEmpty ? [active.selection.start.line + 1, active.selection.end.line + 1] : null,
+  }, null, 1)
+}
+
+/** Diagnostics are what the editor already knows is wrong — the agent should use it. */
+async function problems(args) {
+  const all = vscode.languages.getDiagnostics()
+  const wanted = args.path ? resolve(args.path).fsPath : null
+  const lines = []
+  for (const [uri, list] of all) {
+    if (wanted && uri.fsPath !== wanted) continue
+    for (const d of list) {
+      if (lines.length >= MAX_MATCHES) break
+      const severity = ['error', 'warning', 'info', 'hint'][d.severity] || 'info'
+      lines.push(`${vscode.workspace.asRelativePath(uri)}:${d.range.start.line + 1}: ${severity}: ${d.message}`)
+    }
+  }
+  return lines.length ? lines.join('\n') : 'no problems reported'
+}
+
+// ---- the web ----
+// Research online, the way Claude Code does: search for pages, then read one. Both are
+// read-only (they touch nothing in the workspace), so they need no approval and are
+// available even in Plan mode. Network calls are bounded, and a failure is returned as
+// text for the model to reason about rather than thrown.
+
+const https = require('https')
+
+/** A bounded GET that follows a couple of redirects and returns the body as text. */
+function getUrl(url, { timeout = 15000, maxBytes = 2_000_000, redirects = 3 } = {}) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) '
+          + 'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36',
+        'Accept': 'text/html,application/xhtml+xml',
+      },
+    }, (res) => {
+      if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && redirects > 0) {
+        res.resume()
+        const next = new URL(res.headers.location, url).href
+        resolve(getUrl(next, { timeout, maxBytes, redirects: redirects - 1 }))
+        return
+      }
+      let data = ''
+      res.on('data', (chunk) => {
+        data += chunk
+        if (data.length > maxBytes) { data = data.slice(0, maxBytes); request.destroy() }
+      })
+      res.on('end', () => resolve({ status: res.statusCode, body: data,
+        type: res.headers['content-type'] || '' }))
+    })
+    request.on('error', reject)
+    request.setTimeout(timeout, () => request.destroy(new Error(`timed out after ${timeout} ms`)))
+  })
+}
+
+const unentity = (t) => t
+  .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+  .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+  .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ')
+
+// Search results are cached briefly, so the same query in the same minute — a retry, a
+// test, the model looking twice — does not hit the engine again and risk a rate-limit.
+const searchCache = new Map()
+const CACHE_MS = 5 * 60 * 1000
+
+const CHALLENGE = /captcha|unfortunately, bots|confirm this search was made by a human/i
+
+/** DuckDuckGo's HTML endpoint. Fast and detailed, but it challenges heavy use. */
+function parseDuckDuckGo(bodyText) {
+  if (CHALLENGE.test(bodyText)) return { blocked: true, results: [] }
+  const links = [...bodyText.matchAll(/result__a[^>]*href="([^"]+)"[^>]*>(.*?)<\/a>/gs)]
+  const snippets = [...bodyText.matchAll(/result__snippet[^>]*>(.*?)<\/a>/gs)].map((m) => m[1])
+  const results = links.map((m, i) => {
+    let href = m[1]
+    const wrapped = href.match(/[?&]uddg=([^&]+)/)
+    if (wrapped) href = decodeURIComponent(wrapped[1])
+    else if (href.startsWith('//')) href = `https:${href}`
+    return { url: href, title: unentity(m[2].replace(/<[^>]+>/g, '')).trim(),
+             snippet: unentity((snippets[i] || '').replace(/<[^>]+>/g, '')).trim() }
+  })
+  return { blocked: false, results }
+}
+
+/** Bing's HTML, as a fallback. Its result links are base64 redirects. */
+function parseBing(bodyText) {
+  if (CHALLENGE.test(bodyText)) return { blocked: true, results: [] }
+  const results = []
+  for (const block of bodyText.split(/<li class="b_algo"/).slice(1)) {
+    const link = block.match(/<h2[^>]*>\s*<a[^>]*href="([^"]+)"/)
+    if (!link) continue
+    let url = unentity(link[1])
+    const u = url.match(/[?&]u=a1([A-Za-z0-9_-]+)/)   // the real url, base64url after "a1"
+    if (u) {
+      try { url = Buffer.from(u[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8') } catch { /* keep redirect */ }
+    }
+    const title = block.match(/<h2[^>]*>\s*<a[^>]*>(.*?)<\/a>/s)
+    const snip = block.match(/<p[^>]*>(.*?)<\/p>/s)
+    results.push({ url,
+      title: title ? unentity(title[1].replace(/<[^>]+>/g, '')).trim() : url,
+      snippet: snip ? unentity(snip[1].replace(/<[^>]+>/g, '')).trim() : '' })
+  }
+  return { blocked: false, results }
+}
+
+const ENGINES = [
+  { name: 'DuckDuckGo', url: (q) => `https://html.duckduckgo.com/html/?q=${encodeURIComponent(q)}`, parse: parseDuckDuckGo },
+  { name: 'Bing', url: (q) => `https://www.bing.com/search?q=${encodeURIComponent(q)}`, parse: parseBing },
+]
+
+// ---- web search and page reading through the server (Tavily) ----
+// The server holds the Tavily key; the extension never does. Its answers are shaped to
+// keep the model's context small: ranked results with only their relevant passage, and a
+// page read against a question returning only the passages that answer it.
+const serverUrl = () => gpuServer.url()
+const list = (v) => (Array.isArray(v) ? v : String(v || '').split(',')).map((d) => String(d).trim()).filter(Boolean).slice(0, 10)
+
+async function viaServer(path, body) {
+  const server = serverUrl()
+  if (!server) throw new Error('no AIPictury server configured')
+  const response = await fetch(`${server}/api${path}`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+    signal: AbortSignal.timeout(60_000) })
+  if (!response.ok) {
+    let detail = response.statusText
+    try { detail = (await response.json()).detail || detail } catch { /* not JSON */ }
+    throw new Error(`${response.status} ${detail}`)
+  }
+  return response.json()
+}
+
+/** What the model reads from a search: compact, and pointing at the next step. */
+function resultsForModel(query, answer, results, weak = false) {
+  // Each result as the link to cite it with: a numbered list invites "[1]" footnotes.
+  const lines = results.map((r) =>
+    `- [${linkText(r.title)}](${r.url})${r.published ? ` (${String(r.published).slice(0, 10)})` : ''}`
+    + `${r.snippet ? `\n  ${r.snippet.slice(0, 400)}` : ''}`)
+  return `Results for ${JSON.stringify(query)}:\n\n${weak ? '(only weak matches — consider other words or a wider time range)\n\n' : ''}`
+    + `${answer ? `In short: ${answer}\n\n` : ''}${lines.join('\n\n')}\n\n`
+    + 'To read a result, call fetch_url with its url and a query saying what you need from it. '
+    + 'Cite what you use with these links, inline.'
+}
+
+/** A page title that stays one Markdown link text. */
+function linkText(title) {
+  return String(title || 'page').replace(/\[/g, '(').replace(/\]/g, ')').replace(/\s+/g, ' ').trim().slice(0, 160)
+}
+
+async function webSearch(args) {
+  const query = String(args.query || '').trim()
+  if (!query) throw new Error('query is required')
+  try {
+    const data = await viaServer('/search', {
+      query, max_results: Math.min(8, Number(args.max_results) || 5),
+      topic: args.topic === 'news' ? 'news' : 'general', depth: args.depth === 'advanced' ? 'advanced' : 'basic',
+      time_range: ['day', 'week', 'month', 'year'].includes(args.time_range) ? args.time_range : undefined,
+      include_domains: list(args.include_domains), exclude_domains: list(args.exclude_domains) })
+    const text = data.results.length || data.answer
+      ? resultsForModel(query, data.answer, data.results, data.weak)
+      : `no results for ${JSON.stringify(query)} — try other words, or a wider time range`
+    return { text, web: { engine: data.cached ? 'Tavily (cached)' : 'Tavily', seconds: data.seconds,
+      answer: data.answer, results: data.results.map(({ title, url, score }) => ({ title, url, score })) } }
+  } catch (error) {
+    // No key on the server, Tavily down or out of credits: search the web from here.
+    const text = await searchDirectly(query)
+    return { text, web: { engine: 'DuckDuckGo/Bing (Tavily unavailable)', note: error.message, results: [] } }
+  }
+}
+
+async function searchDirectly(query) {
+  const cached = searchCache.get(query)
+  if (cached && Date.now() - cached.at < CACHE_MS) return cached.text
+
+  let blocked = false
+  let results = []
+  for (const engine of ENGINES) {
+    try {
+      const page = await getUrl(engine.url(query))
+      const parsed = engine.parse(page.body)
+      blocked = blocked || parsed.blocked
+      if (parsed.results.length) { results = parsed.results; break }
+    } catch { /* try the next engine */ }
+  }
+  if (!results.length) {
+    return blocked
+      ? `the search engines are rate-limiting automated queries right now for ${JSON.stringify(query)}; `
+        + 'try again in a few minutes, or open the page yourself'
+      : `no results for ${JSON.stringify(query)}`
+  }
+
+  const out = results.slice(0, 8).map((r) =>
+    `- [${linkText(r.title)}](${r.url})\n  ${r.snippet.slice(0, 300)}`)
+  const text = `Results for ${JSON.stringify(query)}:\n\n${out.join('\n\n')}\n\n`
+    + 'Use fetch_url on the most relevant link to read it in full. Cite what you use with these links, inline.'
+  searchCache.set(query, { at: Date.now(), text })
+  return text
+}
+
+/** A web page for the model: with a query, only the passages that answer it; without
+ *  one, the page as Markdown. Through Tavily on the server, else fetched from here. */
+async function fetchUrl(args) {
+  let target = String(args.url || '').trim()
+  if (!target) throw new Error('url is required')
+  if (!/^https?:\/\//i.test(target)) target = `https://${target}`
+  const query = String(args.query || '').trim()
+  try {
+    const data = await viaServer('/extract', { url: target, query: query || undefined, chunks: 3 })
+    const body = data.content || '(the page has no readable text)'
+    const text = query
+      ? `From ${data.url}, the passages about ${JSON.stringify(query)}:\n\n${body}`
+      : `${data.url}\n\n${body}${data.truncated ? '\n\n… page truncated; call again with a query to get the part you need' : ''}`
+    return { text, web: { engine: data.cached ? 'Tavily (cached)' : 'Tavily', seconds: data.seconds, url: data.url,
+      focused: data.focused, chars: data.chars, sent: body.length, preview: body.slice(0, 1500) } }
+  } catch (error) {
+    // Tavily could not read it (or is not there): fetch it from here — and when a query was
+    // given, keep to it here too, so the model still gets passages, not a whole page.
+    const page = await fetchDirectly(target)
+    const text = query ? passages(page, query, target) : page
+    return { text, web: { engine: 'direct (Tavily unavailable)', note: error.message, url: target,
+      focused: !!query && text !== page, chars: page.length, sent: text.length, preview: text.slice(0, 1500) } }
+  }
+}
+
+// Words that say nothing about what is being looked for (English and Spanish).
+const STOP = new Set(('the and for are was were has have had how what which who why when where does did '
+  + 'can could would should will with from into about this that these those its their there than then '
+  + 'much many more most some any all not but you your our they them his her el la los las un una unos '
+  + 'que qué como cómo cual cuál del por para con sin sobre este esta estos estas ese esa hay tiene '
+  + 'tienen es son fue ser muy más menos').split(' '))
+
+/** The paragraphs of a page that best match a query — by the query's words they contain —
+ *  in page order, up to ~1.8k characters: what Tavily's reranking does, done plainly. */
+function passages(page, query, url, limit = 1800) {
+  const words = [...new Set(String(query).toLowerCase().match(/[\p{L}\p{N}]{2,}/gu) || [])].filter((w) => !STOP.has(w))
+  const parts = String(page).split(/\n\s*\n/).map((p) => p.trim()).filter((p) => p.length > 40)
+  if (!words.length || !parts.length) return page.slice(0, limit)
+  const scored = parts.map((text, i) => {
+    const lower = text.toLowerCase()
+    const hits = words.reduce((n, w) => n + (lower.includes(w) ? 1 : 0), 0)
+    return { i, text: text.slice(0, 700), score: hits / words.length }
+  }).filter((p) => p.score > 0).sort((a, b) => b.score - a.score)
+  // Only paragraphs about as relevant as the best: a single shared word is not a match.
+  const best = scored[0]?.score || 0
+  scored.splice(0, scored.length, ...scored.filter((p) => p.score >= best * 0.5))
+  let used = 0
+  const chosen = []
+  for (const p of scored) {
+    if (used + p.text.length > limit) break
+    chosen.push(p); used += p.text.length
+  }
+  if (!chosen.length) return `From ${url}: nothing on the page matched ${JSON.stringify(query)}.\n\n${page.slice(0, 600)}`
+  return `From ${url}, the passages about ${JSON.stringify(query)}:\n\n`
+    + chosen.sort((a, b) => a.i - b.i).map((p) => p.text).join('\n\n')
+}
+
+/** A web page reduced to readable text: scripts, styles and tags removed. */
+async function fetchDirectly(target) {
+  let page
+  try {
+    page = await getUrl(target)
+  } catch (err) {
+    return `could not fetch ${target} (${err.message})`
+  }
+  if (page.status && page.status >= 400) return `${target} returned HTTP ${page.status}`
+  if (!/html|text|xml|json/i.test(page.type)) {
+    return `${target} is ${page.type || 'not text'}; nothing to read`
+  }
+  const text = unentity(page.body
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<\/(p|div|h[1-6]|li|tr|section|article|br)>/gi, '\n')
+    .replace(/<[^>]+>/g, ' '))
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n\s*\n\s*\n+/g, '\n\n')
+    .trim()
+  const title = (page.body.match(/<title[^>]*>(.*?)<\/title>/is) || [])[1]
+  const head = title ? `# ${unentity(title.replace(/<[^>]+>/g, '')).trim()}\n\n` : ''
+  const capped = text.slice(0, 12_000)
+  return head + capped + (text.length > capped.length ? '\n\n… page truncated' : '')
+}
+
+/** The shapes the model is told about. Kept beside the implementations on purpose.
+ *  [name, description, properties, required]; a property is [type, hint] or a full schema. */
+const SCHEMA = [
+  ['read_file', 'Read a file. Lines come numbered (number, tab, line) so you can quote locations; do not '
+    + 'copy the numbers into edit_file. Long files come a page (2000 lines) at a time — use offset and limit '
+    + 'for the part you need. Also reads Jupyter notebooks (with their cells and outputs), PDFs (by pages) and pictures. '
+    + 'Read a file before you change it.',
+   { path: ['string', 'file path relative to the workspace root'],
+     offset: ['integer', 'optional: the line to start from (1-based)'],
+     limit: ['integer', 'optional: how many lines to read'],
+     pages: ['string', 'optional, PDFs only: which pages — "3", "1-10", or "12-" to the end (40 at a time)'] }, ['path']],
+  ['write_file', 'Create a file, or replace one completely. For a change to an existing file prefer '
+    + 'edit_file. An existing file must have been read first.',
+   { path: ['string', 'file path relative to the workspace root'],
+     content: ['string', 'the complete new contents'] }, ['path', 'content']],
+  ['edit_file', 'Replace text in a file you have read: old_text must appear exactly once (include enough '
+    + 'surrounding lines to make it unique), or set replace_all to change every occurrence. Copy old_text '
+    + 'from the file exactly, indentation included, without line numbers. For several changes to one '
+    + 'file, pass them together in edits.',
+   { path: ['string', 'file path relative to the workspace root'],
+     old_text: ['string', 'the exact text to replace'],
+     new_text: ['string', 'what to put in its place'],
+     replace_all: ['boolean', 'optional: replace every occurrence of old_text (e.g. renaming a variable)'],
+     edits: { type: 'array', description: 'optional: several replacements applied in order, all or none',
+       items: { type: 'object', properties: { old_text: { type: 'string' }, new_text: { type: 'string' },
+         replace_all: { type: 'boolean' } }, required: ['old_text', 'new_text'] } } }, ['path']],
+  ['grep', 'Search file contents with a regular expression (ripgrep syntax), respecting .gitignore. '
+    + 'Use it instead of grep or rg in run_command. output_mode: "files_with_matches" (default, newest '
+    + 'first), "content" (matching lines with numbers; add context for surrounding lines) or "count".',
+   { pattern: ['string', 'the regular expression, e.g. "function\\s+handle\\w+" or "TODO"'],
+     path: ['string', 'optional: a directory or file to search (default: the whole workspace)'],
+     glob: ['string', 'optional: only files matching this glob, e.g. "*.ts" or "src/**/*.{js,jsx}"'],
+     type: ['string', 'optional: a file type, e.g. "py", "js", "rust"'],
+     output_mode: ['string', '"files_with_matches", "content" or "count"'],
+     case_insensitive: ['boolean', 'optional: ignore case'],
+     context: ['integer', 'optional, content mode: lines before and after each match'],
+     multiline: ['boolean', 'optional: let the pattern span lines (. matches newlines)'],
+     head_limit: ['integer', 'optional: at most this many results'],
+     offset: ['integer', 'optional: skip this many results (for paging)'] }, ['pattern']],
+  ['glob', 'Find files by name pattern, newest first (at most 100), e.g. "**/*.test.js" or '
+    + '"src/components/**/*.tsx". Respects .gitignore.',
+   { pattern: ['string', 'the glob pattern'],
+     path: ['string', 'optional: the directory to search in (default: the workspace root)'],
+     include_ignored: ['boolean', 'optional: include files .gitignore excludes'] }, ['pattern']],
+  ['list_files', 'List the files and folders in one directory of the workspace.',
+   { path: ['string', 'directory, relative to the workspace root; defaults to the root'] }, []],
+  ['code_intel', 'Ask the language server: where a symbol is defined, every reference to it, its type '
+    + 'and docs (hover), what a file declares, symbols across the workspace, implementations, and who calls '
+    + 'or is called by a function. Faster and more precise than searching text for code questions. Give the '
+    + 'line and the symbol\'s name on it.',
+   { operation: ['string', OPS.join(' | ')],
+     path: ['string', 'the file (not needed for workspace_symbols)'],
+     line: ['integer', 'the line the symbol is on (1-based)'],
+     symbol: ['string', 'the symbol\'s name on that line'],
+     query: ['string', 'for workspace_symbols: the name to look for'] }, ['operation']],
+  ['editor_state', 'What the user is looking at: open files, the active file, and the current selection.',
+   {}, []],
+  ['problems', 'Errors and warnings the editor has already reported.',
+   { path: ['string', 'optional file to limit the report to'] }, []],
+  ['run_command', 'Run a bash command in the workspace and return its output and exit code. The directory '
+    + 'a cd leaves you in carries over to the next command. Default timeout 120 s (at most 600); a command '
+    + 'still running then is left running in the background. Use run_in_background for servers and '
+    + 'watchers, then bash_output to read them. Do not use it to read, search or edit files — read_file, '
+    + 'grep, glob and edit_file do that better.',
+   { command: ['string', 'the command line to run'],
+     timeout: ['integer', 'optional: seconds to wait, up to 600'],
+     run_in_background: ['boolean', 'optional: start it and return at once (dev servers, watchers, long builds)'],
+     description: ['string', 'optional: what it does, in 5-10 words'],
+     outside_sandbox: ['boolean', 'optional: run it outside the sandbox — only when the sandbox stopped it and it '
+       + 'really needs to write outside the workspace or reach the network; the user is asked first'] }, ['command']],
+  ['powershell', 'Run a PowerShell command in the workspace and return its output (Windows, or wherever PowerShell 7 '
+    + 'is installed). The same rules as run_command: asked first, a timeout, run_in_background.',
+   { command: ['string', 'the PowerShell command'], timeout: ['integer', 'optional: seconds to wait, up to 600'],
+     run_in_background: ['boolean', 'optional: start it and return at once'], description: ['string', 'optional: what it does, in 5-10 words'] }, ['command']],
+  ['monitor', 'Start a command that keeps running — a log being written, a dev server, a watcher — and be told '
+    + 'of each new output line: the lines reach you as events, between your steps, or as a new turn once you have '
+    + 'finished. For waiting on something to happen ("tell me when the build fails"). Stop it with kill_shell.',
+   { command: ['string', 'the command, e.g. "tail -f logs/app.log" or "npm run dev"'],
+     description: ['string', 'what you are watching for, in a few words'],
+     timeout_minutes: ['integer', 'optional: stop it after this many minutes (default 30, at most 120)'] }, ['command']],
+  ['notebook_run_cell', 'Run a code cell of a Jupyter notebook with the kernel the user chose for it, and read its '
+    + 'outputs (text, results, errors). The user is asked first. Write or change the cell with notebook_edit, then run it.',
+   { path: ['string', 'the .ipynb notebook'], cell_id: ['string', 'the cell\'s id, or its position (0 is the first)'],
+     timeout: ['integer', 'optional: seconds to wait, 5 to 600 (default 120)'] }, ['path', 'cell_id']],
+  ['browser', 'Use a web browser (the user\'s Chrome or Edge, in a profile of its own, in a window they can watch): open pages, '
+    + 'read them, click, type, take screenshots, read the console — to test a web app on localhost, check a page, or do '
+    + 'something on a site. Every page comes back as a snapshot whose elements have refs ("[ref=e12]"): act on an '
+    + 'element by giving its ref. Acting on a site other than localhost is asked once per site. Never type passwords or '
+    + 'payment details: ask the user to do that in the window.',
+   { action: ['string', 'navigate (url), back, snapshot, click (ref), type (ref, text, submit?), press (key), select (ref, values), '
+       + 'hover (ref), wait (text or seconds), screenshot (ref? full_page?), console, evaluate (script), tabs (index? to switch), '
+       + 'new_tab (url?), close_tab, close'],
+     url: ['string', 'for navigate and new_tab: the whole address, e.g. http://localhost:5173'],
+     ref: ['string', 'the element\'s ref from the latest snapshot, e.g. "e12"'],
+     element: ['string', 'what the element is, in a few words (e.g. "the Sign up button") — shown to the user'],
+     text: ['string', 'for type: the text; for wait: text to wait for'],
+     submit: ['boolean', 'for type: press Enter after typing'],
+     key: ['string', 'for press: a key or chord, e.g. "Enter", "PageDown", "Control+A"'],
+     values: { type: 'array', items: { type: 'string' }, description: 'for select: the option(s) to choose' },
+     seconds: ['number', 'for wait: how long (at most 30), or the time limit when waiting for text'],
+     full_page: ['boolean', 'for screenshot: the whole page, not just what the window shows'],
+     script: ['string', 'for evaluate: a JavaScript expression run in the page, e.g. "document.title"'],
+     index: ['number', 'for tabs: the tab to switch to'] }, ['action']],
+  ['publish_page', 'Publish a page for the user — a report, a summary, a small HTML app — on their AIPictury server, '
+    + 'at a private address (only those given the link can open it). Give Markdown, or a whole HTML page. Say the '
+    + 'link in your reply.',
+   { title: ['string', 'the page\'s title'], markdown: ['string', 'its content as Markdown (or give html)'],
+     html: ['string', 'optional: a whole HTML page instead — it is served sandboxed'] }, ['title']],
+  ['send_user_file', 'Give the user a file from the workspace as a card in the conversation, to open, save a copy of, '
+    + 'or show in its folder — a report you wrote, an export, a picture.',
+   { path: ['string', 'the file, relative to the workspace'], message: ['string', 'optional: one line about it'] }, ['path']],
+  ['enter_worktree', 'Work in a git worktree: a checkout of its own on a new branch (inside the workspace, at '
+    + '.aipictury/worktrees/<name>), so your changes do not touch the user\'s checkout until they want them. From '
+    + 'then on, paths are relative to the worktree and commands run in it. Leave it with exit_worktree.',
+   { name: ['string', 'optional: a short name, e.g. "fix-login" (the branch is aipictury/<name>)'] }, []],
+  ['exit_worktree', 'Leave the worktree: "keep" leaves its folder and branch for the user (say where), "remove" '
+    + 'deletes them — refused if it holds work unless discard_changes is true.',
+   { action: ['string', '"keep" or "remove"'], discard_changes: ['boolean', 'optional: remove even with commits or changes in it'] }, ['action']],
+  ['cron_create', 'Schedule a prompt in this conversation: at a cron time ("0 9 * * 1-5") or every interval ("30m", '
+    + '"2h"), recurring or once. When it is due it arrives as a new message to you. For "every morning…", "check this '
+    + 'every hour".',
+   { schedule: ['string', 'a 5-field cron expression (local time) or an interval like "15m", "2h", "1d" (at least a minute)'],
+     prompt: ['string', 'what to do then, as you would be asked it'],
+     recurring: ['boolean', 'optional: false for once (default true)'] }, ['schedule', 'prompt']],
+  ['cron_list', 'The prompts scheduled in this conversation, with when each comes next.', {}, []],
+  ['cron_delete', 'Remove a scheduled prompt.', { id: ['string', 'its id, e.g. "job_1"'] }, ['id']],
+  ['schedule_wakeup', 'Come back to this later: after `delay_minutes` you are given `prompt` as a new message. For '
+    + 'waiting on something outside (a build, a deploy): choose the delay from how long it takes.',
+   { delay_minutes: ['integer', '1 to 1440'], prompt: ['string', 'what to do then'],
+     reason: ['string', 'why that delay, in a few words'] }, ['delay_minutes', 'prompt']],
+  ['bash_output', 'Read the new output of a command running in the background, and whether it has finished.',
+   { bash_id: ['string', 'the id it was given, e.g. "bash_1"'],
+     filter: ['string', 'optional: a regular expression; only matching lines are returned'] }, ['bash_id']],
+  ['kill_shell', 'Stop a command running in the background.',
+   { shell_id: ['string', 'its id, e.g. "bash_1"'] }, ['shell_id']],
+  ['todo_write', 'Keep a to-do list for a task of three or more steps, shown to the user as you work. '
+    + 'Send the whole list each time. Exactly one item is in_progress while you work on it; mark it '
+    + 'completed as soon as it is done, not in a batch at the end. Skip it for small, one-step tasks.',
+   { todos: { type: 'array', description: 'the whole list, in order',
+     items: { type: 'object', properties: {
+       content: { type: 'string', description: 'what to do, imperative: "Add the login route"' },
+       status: { type: 'string', description: '"pending", "in_progress" or "completed"' },
+       activeForm: { type: 'string', description: 'while doing it: "Adding the login route"' } },
+     required: ['content', 'status'] } } }, ['todos']],
+  ['task_create', 'Add a task to your task list (the same list as todo_write, shown to the user). Give the '
+    + 'tasks it waits for in blockedBy: it cannot start until they are completed. Use it for work with steps '
+    + 'that depend on each other; todo_write stays the quick way to set a simple list at once.',
+   { subject: ['string', 'what to do, imperative: "Add the orders table"'],
+     description: ['string', 'optional: details, what done means'],
+     activeForm: ['string', 'optional: while doing it: "Adding the orders table"'],
+     blockedBy: { type: 'array', items: { type: 'string' }, description: 'optional: ids of the tasks it waits for, e.g. ["1"]' } }, ['subject']],
+  ['task_update', 'Change a task: its status (pending, in_progress, completed, or deleted), subject, description, '
+    + 'what it waits for (addBlockedBy) or what waits for it (addBlocks). A task waiting for unfinished ones cannot '
+    + 'be set in_progress. Mark a task completed as soon as it is done: the reply says which tasks it freed.',
+   { taskId: ['string', 'the task\'s id, e.g. "2"'], status: ['string', 'optional: pending, in_progress, completed or deleted'],
+     subject: ['string', 'optional'], description: ['string', 'optional'], activeForm: ['string', 'optional'],
+     addBlockedBy: { type: 'array', items: { type: 'string' }, description: 'optional: ids it now also waits for' },
+     addBlocks: { type: 'array', items: { type: 'string' }, description: 'optional: ids that now wait for it' } }, ['taskId']],
+  ['task_list', 'Your task list: each task\'s id, status and what it still waits for.', {}, []],
+  ['task_get', 'One task in full: its description, what it waits for and what waits for it.',
+   { taskId: ['string', 'the task\'s id'] }, ['taskId']],
+  ['task', 'Hand a self-contained piece of work to a helper agent with a fresh context: it works on its '
+    + 'own and returns only its final report, which keeps your context small. subagent_type "explore" '
+    + '(read-only: find where things are, how something works, answer a question about the code — the '
+    + 'most common use) or "general" (may also change files and run commands). Say exactly what to find '
+    + 'or do and what to report back.',
+   { description: ['string', 'a 3-5 word summary, e.g. "Find the auth middleware"'],
+     prompt: ['string', 'the full task: what to do, where to look, what to return'],
+     subagent_type: ['string', '"explore" or "general"'],
+     isolation: ['string', 'optional: "worktree" — the helper works in a git worktree of its own; its changes are left there for you'],
+     name: ['string', 'optional: a name, to send_message to it later (it keeps its context)'],
+     run_in_background: ['boolean', 'optional: start it and carry on; its report reaches you as an event when it is done'] }, ['description', 'prompt']],
+  ['workflow', 'Run a piece of work as a workflow: steps carried out by helpers, in the order their dependencies give '
+    + '(one at a time), each told what the steps it depends on found; you get one report of all of them. For substantial '
+    + 'work in parts — research, then changes, then checks.',
+   { goal: ['string', 'what the whole workflow is for'],
+     steps: { type: 'array', description: 'the steps, 1 to 12', items: { type: 'object', properties: {
+       name: { type: 'string', description: 'a short name, e.g. "find callers"' },
+       prompt: { type: 'string', description: 'what this step does and what it reports' },
+       after: { type: 'array', items: { type: 'string' }, description: 'optional: names of the steps it needs first' },
+       subagent_type: { type: 'string', description: 'optional: "explore" (read-only) or "general" (default)' } }, required: ['name', 'prompt'] } } }, ['steps']],
+  ['send_message', 'Send a message to a helper you started (by its name or id): while it works it reads it before its '
+    + 'next step; once it has reported, it carries on from where it was, with all it knows, and reports again.',
+   { to: ['string', 'its name or id, e.g. "researcher" or "agent_2"'], message: ['string', 'what to tell or ask it'] }, ['to', 'message']],
+  ['list_agents', 'The helpers of this conversation: their status, steps, tokens and time.', {}, []],
+  ['task_stop', 'Stop a helper running in the background, or a background command.', { id: ['string', 'the helper\'s name or id, or a command\'s id (bash_1)'] }, ['id']],
+  ['notebook_edit', 'Change a Jupyter notebook cell: replace its source, insert a new cell after it, or '
+    + 'delete it. Read the notebook first to see the cell ids.',
+   { path: ['string', 'the .ipynb file'],
+     cell_id: ['string', 'the cell to change, or to insert after (omit to insert at the start)'],
+     new_source: ['string', 'the cell\'s new source'],
+     cell_type: ['string', '"code" or "markdown"'],
+     edit_mode: ['string', '"replace" (default), "insert" or "delete"'] }, ['path']],
+  ['remember', 'Save a lasting rule or preference the user has stated, so it applies in every '
+    + 'later turn and conversation. Use it when the user says remember, rule, always, never, from '
+    + 'now on (recordá, regla, siempre, nunca, de ahora en más), or states a convention to keep.',
+   { rule: ['string', 'the rule in one clear, self-contained sentence'],
+     scope: ['string', '"project" for this codebase, "user" for a personal preference that applies everywhere'] },
+   ['rule']],
+  ['generate_media', 'Make a picture or a short video on the AIPictury GPU and save it into '
+    + 'the project. Use it whenever the user wants an image, photo, illustration, icon, background '
+    + 'or clip — to add one, or to replace one the code already uses. To replace, set save_to to '
+    + 'the existing file: the new one gets its size and format. To change an existing picture '
+    + '(recolour, restyle, remove a background), pass it as source and describe the change. '
+    + 'kind=video with a source animates that picture.',
+   { kind: ['string', '"image" or "video"'],
+     prompt: ['string', 'a full visual description: subject, setting, light, style, composition, '
+       + 'colours — or, with a source, the change to make'],
+     save_to: ['string', 'the workspace path to write, e.g. public/images/hero.jpg; its extension '
+       + 'sets the format. Omit to only show it to the user'],
+     source: ['string', 'optional: a picture in the workspace to edit, or to animate into a video'],
+     aspect: ['string', '"landscape", "portrait" or "square", when there is no file to match'],
+     width: ['integer', 'optional exact width in pixels (default: the replaced file\'s)'],
+     height: ['integer', 'optional exact height in pixels'],
+     seconds: ['number', 'video length, 2 to 10'] },
+   ['kind', 'prompt']],
+  ['web_search', 'Search the web: ranked results, each with its most relevant passage, and a '
+    + 'short answer drawn from them. Use it when the task needs current or external facts. One '
+    + `topic per query (split a complex question into several searches); today is ${new Date().toISOString().slice(0, 10)}, `
+    + 'so put the year in queries about recent things. Then read only the one or two best results '
+    + 'with fetch_url, giving it a query.',
+   { query: ['string', 'what to search for, specific and short (under 400 characters)'],
+     time_range: ['string', 'optional: "day", "week", "month" or "year" for recent results'],
+     topic: ['string', 'optional: "news" for current events'],
+     depth: ['string', 'optional: "advanced" for niche or hard questions (slower); default basic'],
+     include_domains: ['string', 'optional: comma-separated domains to search only, e.g. "nodejs.org,github.com"'],
+     exclude_domains: ['string', 'optional: comma-separated domains to leave out'] }, ['query']],
+  ['fetch_url', 'Read a web page. With a query, returns only the passages of the page that answer '
+    + 'it — use this almost always, it keeps your context small. Without a query, returns the whole '
+    + 'page as Markdown (long; only when you truly need all of it).',
+   { url: ['string', 'the page to read'],
+     query: ['string', 'what you need from the page, e.g. "the latest LTS version and its end-of-life date"'] }, ['url']],
+  ['push_notification', 'Tell the user something needs them when they may not be watching: a long task '
+    + 'finished, or you are blocked on something only they can do. Shown as a system notification when '
+    + 'VS Code is not in front, and not sent when they are already looking. Use it rarely — once at the '
+    + 'end of long work, never for progress.',
+   { message: ['string', 'one short line: what is done or what you need'],
+     title: ['string', 'optional: a few words, e.g. "Tests fixed"'] }, ['message']],
+]
+
+// Only in Plan mode: how a plan is handed to the user for approval.
+const EXIT_PLAN = ['exit_plan_mode', 'When your plan is ready, present it with this for the user to approve. '
+  + 'Write it in Markdown: the goal, the files you will change and how, and anything uncertain. Only after '
+  + 'they approve can you make changes; if they ask for changes, revise the plan and call this again.',
+{ plan: ['string', 'the plan, in Markdown'] }, ['plan']]
+
+// Outside Plan mode: the agent may ask to switch to it, for work worth agreeing on first.
+const ENTER_PLAN = ['enter_plan_mode', 'Ask the user to switch to Plan mode before starting work that '
+  + 'is large, risky or ambiguous — many files, a design choice, anything costly to undo. In Plan mode '
+  + 'you investigate read-only and present a plan for approval with exit_plan_mode. Not for small or '
+  + 'clear tasks: do those directly.',
+{ reason: ['string', 'one line: why this is worth planning first'] }, ['reason']]
+
+function skillSchema() {
+  // Each skill as /skills shows it: with its description, by its name only, or not at all.
+  const list = context.visibleSkills()
+  if (!list.length) return null
+  return ['skill', 'Use a skill: a set of instructions (and files) the project provides for a kind of task. '
+    + 'When a task matches one, call this first and follow what it says. Available:\n'
+    + list.map((s) => (s.visibility === 'name' ? `- ${s.name}` : `- ${s.name}: ${s.description}`)).join('\n'),
+  { name: ['string', 'the skill\'s name'], arguments: ['string', 'optional: what to use it on'] }, ['name']]
+}
+
+// Asking the user to decide, as Claude Code's AskUserQuestion does: the model states the
+// choice and its options, the panel shows them in place of the input, and the answers
+// come back as this tool's result. Its parameters nest, so it is written out in full.
+const ASK_USER = {
+  type: 'function',
+  function: {
+    name: 'ask_user',
+    description: 'Ask the user to decide something that is theirs to decide, instead of choosing '
+      + 'yourself: which library or stack, the scope, naming or structure they will live with, a '
+      + 'trade-off between real options, anything costly to undo. Give 2 to 4 concrete options, your '
+      + 'recommended one first. The user can always write their own answer instead. Up to 4 related '
+      + 'questions in one call. Do not ask what you can find out by reading the code.',
+    parameters: {
+      type: 'object',
+      properties: {
+        questions: {
+          type: 'array',
+          description: '1 to 4 decisions, asked together',
+          items: {
+            type: 'object',
+            properties: {
+              header: { type: 'string', description: 'a very short tab label, at most 12 characters, e.g. "Database"' },
+              question: { type: 'string', description: 'the full question, ending with a question mark' },
+              options: {
+                type: 'array',
+                description: '2 to 4 choices, your recommended one first',
+                items: {
+                  type: 'object',
+                  properties: {
+                    label: { type: 'string', description: '1 to 5 words' },
+                    description: { type: 'string', description: 'what choosing it means: its trade-off, in one line' },
+                  },
+                  required: ['label'],
+                },
+              },
+              multiSelect: { type: 'boolean', description: 'true when several options can be chosen together' },
+            },
+            required: ['header', 'question', 'options'],
+          },
+        },
+        important: { type: 'boolean', description: 'true when the decision is costly to undo. In Auto mode only '
+          + 'important questions stop and wait; others take your recommended option and the user can change it at the end.' },
+      },
+      required: ['questions'],
+    },
+  },
+}
+
+// Findings of a review, as Claude Code's ReportFindings: a list the panel shows as a card, each
+// finding opening its file at its line.
+const REPORT_FINDINGS = {
+  type: 'function',
+  function: {
+    name: 'report_findings',
+    description: 'Report the findings of a review or an investigation (bugs, risks, problems found in '
+      + 'code) as a list the user can click through: each opens its file at its line. Most severe first. '
+      + 'Use it when you were asked to review, audit or look for problems; then summarize in a sentence.',
+    parameters: {
+      type: 'object',
+      properties: {
+        findings: {
+          type: 'array',
+          description: 'what you found, most severe first (an empty list when nothing was found)',
+          items: {
+            type: 'object',
+            properties: {
+              file: { type: 'string', description: 'the file, relative to the workspace' },
+              line: { type: 'integer', description: 'the line it is at (1-based) — always give it: the user opens the file there' },
+              summary: { type: 'string', description: 'the problem, in one sentence' },
+              severity: { type: 'string', enum: ['high', 'medium', 'low'], description: 'how much it matters' },
+              category: { type: 'string', description: 'optional: a short kind, e.g. "correctness", "security"' },
+              detail: { type: 'string', description: 'optional: how it fails — the inputs and what goes wrong' },
+            },
+            required: ['file', 'line', 'summary'],
+          },
+        },
+      },
+      required: ['findings'],
+    },
+  },
+}
+
+const SEVERITIES = ['high', 'medium', 'low']
+
+/** What the model reported, made safe to show: at most 50 findings, each with a file and a
+ *  summary, a line when it is a number, a known severity. */
+function normalizeFindings(args) {
+  let list = args?.findings
+  if (typeof list === 'string') { try { list = JSON.parse(list) } catch { list = [] } }
+  if (list && !Array.isArray(list)) list = [list]
+  return (list || []).map((f) => ({
+    file: String(f?.file || f?.path || '').trim().replace(/^\.\//, ''),
+    line: Number.isInteger(Number(f?.line)) && Number(f.line) > 0 ? Number(f.line) : undefined,
+    summary: String(f?.summary || '').trim().slice(0, 400),
+    severity: SEVERITIES.includes(String(f?.severity).toLowerCase()) ? String(f.severity).toLowerCase() : 'medium',
+    category: String(f?.category || '').trim().slice(0, 40) || undefined,
+    detail: String(f?.detail || '').trim().slice(0, 1200) || undefined,
+  })).filter((f) => f.file && f.summary)
+    .sort((a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity))
+    .slice(0, 50)
+}
+
+const toProps = (props) => Object.fromEntries(Object.entries(props)
+  .map(([key, v]) => [key, Array.isArray(v) ? { type: v[0], description: v[1] } : v]))
+
+const shape = ([name, description, props, required]) => ({
+  type: 'function', function: { name, description, parameters: { type: 'object', properties: toProps(props), required } } })
+
+/** The tools offered to the model. In Plan mode only those that look (and a command only
+ *  when it is read-only, checked when it runs), plus exit_plan_mode; outside it,
+ *  enter_plan_mode. A helper agent gets no ask_user, no task of its own, and nothing that
+ *  speaks to the user (a notification, findings): its report goes to the agent that asked.
+ *  With autoMemory off there is no remember. */
+function toolSchema({ readOnly = false, helper = false, extra = [], autoMemory = true } = {}) {
+  const skill = skillSchema()
+  const roles = context.agents()
+  const schemaList = roles.length ? SCHEMA.map((entry) => (entry[0] !== 'task' ? entry : [entry[0],
+    `${entry[1]} Or one of these helpers with a role (give its name as subagent_type):\n${roles.map((a) => `- ${a.name}: ${a.description}`).join('\n')}`.slice(0, 6000),
+    entry[2], entry[3]])) : SCHEMA
+  const list = [...schemaList, ...(skill ? [skill] : []), ...(helper ? [] : readOnly ? [EXIT_PLAN] : [ENTER_PLAN])]
+    .filter(([name]) => !readOnly || READ_ONLY.has(name) || name === 'run_command' || name === 'exit_plan_mode')
+    .filter(([name]) => !helper || !['task', 'todo_write', 'exit_plan_mode', 'remember', 'push_notification', 'task_create', 'task_update', 'task_list', 'task_get', 'cron_create', 'cron_list', 'cron_delete', 'schedule_wakeup', 'enter_worktree', 'exit_worktree', 'send_message', 'list_agents', 'task_stop', 'publish_page', 'send_user_file', 'workflow'].includes(name))
+    .filter(([name]) => autoMemory || name !== 'remember')
+    .filter(([name]) => name !== 'powershell' || shell.powershellPath())   // only where there is PowerShell
+    .filter(([name]) => name !== 'browser' || (vscode.workspace.getConfiguration('aipictury').get('browser.enabled', true) && browser.available()))
+    .filter(([name]) => !vscode.cli || !EDITOR_ONLY.has(name))           // the terminal (cli/) has no editor
+  // Asking and reporting change nothing: every mode has them.
+  return [...list.map(shape), ...extra, ...(helper ? [] : [ASK_USER, REPORT_FINDINGS])]
+}
+
+// Words a question starts with that say nothing about its subject.
+const FILLER = new Set(('which what how should do does would could can you we i the a an to for of '
+  + 'want like use prefer is are will be it this that your our my in on with there any '
+  + 'qué que cuál cual cuáles cómo como querés quieres preferís prefieres usamos usar el la los las un una de del para con en se te tu vos lo le hay').split(' '))
+
+/** A tab label when the model gave none: the question's first word that is not filler —
+ *  "Which database should store the orders?" → "Database". */
+function keyWord(question) {
+  const word = String(question).toLowerCase().match(/[\p{L}\p{N}-]+/gu)?.find((w) => !FILLER.has(w))
+  return word ? word[0].toUpperCase() + word.slice(1) : 'Question'
+}
+
+/** What the model asked, made safe to show: 1 to 4 questions of 2 to 4 options, each
+ *  with a short header. A model sends options as strings, headers too long, a question
+ *  as a lone object — all of it is accepted and shaped. Throws when nothing usable is left. */
+function normalizeQuestions(args) {
+  let list = args?.questions
+  if (typeof list === 'string') { try { list = JSON.parse(list) } catch { list = [] } }
+  if (list && !Array.isArray(list)) list = [list]
+  const questions = (list || []).slice(0, 4).map((q) => {
+    const question = String(q?.question || '').trim()
+    const options = (Array.isArray(q?.options) ? q.options : []).map((o) => (
+      typeof o === 'string' ? { label: o.trim(), description: '' }
+        : { label: String(o?.label || '').trim(), description: String(o?.description || '').trim() }))
+      .filter((o) => o.label)
+      .filter((o, i, all) => all.findIndex((x) => x.label.toLowerCase() === o.label.toLowerCase()) === i)
+      .filter((o) => !/^other\b/i.test(o.label))          // "Other" is always offered by the panel
+      .slice(0, 4)
+    const header = (String(q?.header || '').trim() || keyWord(question)).slice(0, 12)
+    return { header: header || 'Question', question, options, multiSelect: !!q?.multiSelect }
+  }).filter((q) => q.question && q.options.length >= 2)
+  if (!questions.length) {
+    throw new Error('ask_user needs 1 to 4 questions, each with a question and 2 to 4 options')
+  }
+  return questions
+}
+
+// Which tools change something. These are the ones that need a yes.
+const WRITES = new Set(['write_file', 'edit_file', 'notebook_edit'])
+const RUNS = new Set(['run_command', 'monitor', 'powershell'])
+// The tools that only look. Plan mode is given these (and run_command, which then runs only
+// read-only commands), so it can investigate thoroughly but cannot touch the workspace.
+// What only an editor can do: not offered in the terminal (cli/).
+const EDITOR_ONLY = new Set(['code_intel', 'editor_state', 'problems', 'notebook_run_cell'])
+const READ_ONLY = new Set(['list_files', 'read_file', 'grep', 'glob', 'search', 'editor_state', 'problems',
+  'code_intel', 'web_search', 'fetch_url', 'remember', 'bash_output', 'task', 'skill', 'todo_write',
+  'push_notification', 'report_findings', 'tool_search', 'list_mcp_resources', 'read_mcp_resource',
+  'task_create', 'task_update', 'task_list', 'task_get', 'cron_list', 'list_agents', 'send_user_file', 'workflow', 'browser'])
+
+// search: the old name, kept for conversations saved before grep existed.
+const search = (args, ctx) => files.grep({ ...args, pattern: args.query ?? args.pattern, fixed_strings: true,
+  output_mode: 'content' }, ctx)
+
+const IMPLEMENTATIONS = {
+  list_files: files.listFiles,
+  read_file: files.readFile,
+  write_file: files.writeFile,
+  edit_file: files.editFile,
+  notebook_edit: files.notebookEdit,
+  grep: files.grep,
+  glob: files.glob,
+  search,
+  code_intel: codeIntel,
+  editor_state: listOpen,
+  problems,
+  bash_output: shell.bashOutput,
+  kill_shell: shell.killShell,
+  skill: context.useSkill,
+  web_search: webSearch,
+  fetch_url: fetchUrl,
+  browser: (args) => browser.run(args, { headless: vscode.workspace.getConfiguration('aipictury').get('browser.headless', false),
+    prefer: vscode.workspace.getConfiguration('aipictury').get('browser.channel', 'auto') }),
+}
+
+module.exports = { passages, toolSchema, normalizeQuestions, normalizeFindings, IMPLEMENTATIONS, WRITES, RUNS, READ_ONLY, resolve, root, rel, decoder, encoder, SCHEMA }