@davait/aipictury 1.9.2

package/ext/firestore.js

@@ -0,0 +1,131 @@
+'use strict'
+// Firestore over its REST API, for the extension and the CLI: no SDK, no dependency. Documents
+// are plain objects here and Firestore's typed values on the wire. The ID token comes from the
+// caller (account.js), so every request is the signed-in user's — the security rules decide
+// what it may touch. With `emulator` ("127.0.0.1:8299") it talks to the local emulator.
+// No VS Code here.
+
+const BATCH_MAX = 400                    // writes in one commit (Firestore allows 500)
+
+/** A JavaScript value as a Firestore Value. */
+function encode(v) {
+  if (v === null || v === undefined) return { nullValue: null }
+  if (typeof v === 'boolean') return { booleanValue: v }
+  if (typeof v === 'number') return Number.isInteger(v) ? { integerValue: String(v) } : { doubleValue: v }
+  if (typeof v === 'string') return { stringValue: v }
+  if (v instanceof Date) return { timestampValue: v.toISOString() }
+  if (Array.isArray(v)) return { arrayValue: v.length ? { values: v.map(encode) } : {} }
+  if (typeof v === 'object') return { mapValue: { fields: encodeFields(v) } }
+  throw new Error(`cannot store a ${typeof v}`)
+}
+
+function encodeFields(obj) {
+  const out = {}
+  for (const [k, v] of Object.entries(obj)) if (v !== undefined) out[k] = encode(v)
+  return out
+}
+
+/** A Firestore Value as a JavaScript value. */
+function decode(v) {
+  if (!v || 'nullValue' in v) return null
+  if ('booleanValue' in v) return v.booleanValue
+  if ('integerValue' in v) return Number(v.integerValue)
+  if ('doubleValue' in v) return v.doubleValue
+  if ('stringValue' in v) return v.stringValue
+  if ('timestampValue' in v) return v.timestampValue
+  if ('arrayValue' in v) return (v.arrayValue.values || []).map(decode)
+  if ('mapValue' in v) return decodeFields(v.mapValue.fields || {})
+  if ('bytesValue' in v) return v.bytesValue
+  if ('referenceValue' in v) return v.referenceValue
+  if ('geoPointValue' in v) return v.geoPointValue
+  return null
+}
+
+function decodeFields(fields) {
+  const out = {}
+  for (const [k, v] of Object.entries(fields || {})) out[k] = decode(v)
+  return out
+}
+
+class FirestoreError extends Error {
+  constructor(status, message, code) { super(message); this.status = status; this.code = code }
+}
+
+class Firestore {
+  /** { projectId, getToken: async () => idToken, emulator?: "host:port", fetch? } */
+  constructor({ projectId, getToken, emulator = null, fetchImpl = globalThis.fetch, timeoutMs = 30_000 }) {
+    this.projectId = projectId
+    this.getToken = getToken
+    this.fetch = fetchImpl
+    this.timeoutMs = timeoutMs
+    this.root = `projects/${projectId}/databases/(default)/documents`
+    this.base = emulator ? `http://${emulator}/v1` : 'https://firestore.googleapis.com/v1'
+  }
+
+  async request(method, url, body) {
+    const token = await this.getToken()
+    const response = await this.fetch(url, {
+      method, body: body === undefined ? undefined : JSON.stringify(body),
+      headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      signal: AbortSignal.timeout(this.timeoutMs),
+    })
+    const text = await response.text()
+    let data
+    try { data = text ? JSON.parse(text) : null } catch { data = null }
+    if (!response.ok) {
+      const err = Array.isArray(data) ? data[0]?.error : data?.error
+      const said = String(err?.message || '').trim().split('\n')[0] || (response.status === 403 ? 'permission denied' : response.status === 401 ? 'not signed in' : '')
+      throw new FirestoreError(response.status, said || `Firestore answered ${response.status}`, err?.status)
+    }
+    return data
+  }
+
+  url(path) { return `${this.base}/${this.root}/${path.split('/').map(encodeURIComponent).join('/')}` }
+
+  /** The document at `path` ("users/u1/projects/p1"), or null. */
+  async get(path) {
+    try { return decodeFields((await this.request('GET', this.url(path))).fields) } catch (error) {
+      if (error.status === 404) return null
+      throw error
+    }
+  }
+
+  /** Writes the whole document (creates or replaces). */
+  async set(path, data) {
+    await this.request('PATCH', this.url(path), { fields: encodeFields(data) })
+  }
+
+  /** Changes only the given fields. */
+  async update(path, data) {
+    const mask = Object.keys(data).map((k) => `updateMask.fieldPaths=${encodeURIComponent(k)}`).join('&')
+    await this.request('PATCH', `${this.url(path)}?${mask}`, { fields: encodeFields(data) })
+  }
+
+  async delete(path) {
+    try { await this.request('DELETE', this.url(path)) } catch (error) { if (error.status !== 404) throw error }
+  }
+
+  /** Every document of a collection: [{ id, data }]. */
+  async list(collectionPath, { pageSize = 300 } = {}) {
+    const out = []
+    let token = ''
+    do {
+      const data = await this.request('GET', `${this.url(collectionPath)}?pageSize=${pageSize}${token ? `&pageToken=${encodeURIComponent(token)}` : ''}`)
+      for (const d of data?.documents || []) out.push({ id: d.name.split('/').pop(), data: decodeFields(d.fields) })
+      token = data?.nextPageToken || ''
+    } while (token)
+    return out
+  }
+
+  /** Several writes, all or nothing (in commits of up to 400). Each: { set: [path, data] } or { delete: path }. */
+  async batch(writes) {
+    for (let i = 0; i < writes.length; i += BATCH_MAX) {
+      const part = writes.slice(i, i + BATCH_MAX).map((w) => (w.delete
+        ? { delete: `${this.root}/${w.delete}` }
+        : { update: { name: `${this.root}/${w.set[0]}`, fields: encodeFields(w.set[1]) } }))
+      await this.request('POST', `${this.base}/${this.root}:commit`, { writes: part })
+    }
+  }
+}
+
+module.exports = { Firestore, FirestoreError, encode, decode, encodeFields, decodeFields }

package/ext/gpuRun.js

@@ -0,0 +1,77 @@
+'use strict'
+// The GPU, held for one run at a time (the server's gpu.py): an agent run — from the prompt to
+// its last step, helpers and tools included — names itself on every call it makes to the GPU
+// server (X-AIPictury-Client, -Run, -Label: account.js serverFetch adds them), takes the GPU when
+// it starts, keeps it alive while its tools work between model calls, and lets go when it ends.
+// Another app holding the GPU: the run does not start, and says who has it.
+const crypto = require('crypto')
+const { AsyncLocalStorage } = require('async_hooks')
+
+const store = new AsyncLocalStorage()
+const BEAT = 30_000
+
+/** The headers of the run this code is part of (none outside a run). */
+function headers() {
+  const r = store.getStore()
+  if (!r) return {}
+  return { 'X-AIPictury-Client': r.client, 'X-AIPictury-Run': r.run, 'X-AIPictury-Label': encodeURIComponent(r.label || '') }
+}
+
+class GpuBusyError extends Error {
+  constructor(message, gpu) {
+    super(message)
+    this.name = 'GpuBusyError'
+    this.busy = true
+    this.gpu = gpu
+  }
+}
+
+/**
+ * fn() as a run holding the GPU of `server`. `client`: 'vscode' | 'cli'. A GPU held by another
+ * run: GpuBusyError before anything is done. A server without holds (older): fn() as before.
+ */
+async function holding({ server, client, label = '' }, fn) {
+  const run = { client, run: `${client}-${crypto.randomUUID()}`, label: String(label).replace(/\s+/g, ' ').slice(0, 100) }
+  return store.run(run, async () => {
+    const h = headers()
+    let held = false
+    try {
+      const r = await fetch(`${server}/api/gpu/hold`, { method: 'POST', headers: h, signal: AbortSignal.timeout(10_000) })
+      if (r.status === 423) {
+        const body = await r.json().catch(() => ({}))
+        throw new GpuBusyError(body.detail || 'the GPU is in use by another app', body.gpu)
+      }
+      held = r.ok
+    } catch (error) {
+      if (error instanceof GpuBusyError) throw error
+      // No answer about holds (an older server, a moment's network trouble): the work goes on —
+      // its calls still carry the run, so the server holds the GPU for it if it can.
+    }
+    const beat = held ? setInterval(() => {
+      fetch(`${server}/api/gpu/hold`, { method: 'POST', headers: h, signal: AbortSignal.timeout(10_000) }).catch(() => {})
+    }, BEAT) : null
+    try {
+      return await fn()
+    } finally {
+      if (beat) clearInterval(beat)
+      if (held) await fetch(`${server}/api/gpu/hold`, { method: 'DELETE', headers: h, signal: AbortSignal.timeout(10_000) }).catch(() => {})
+    }
+  })
+}
+
+/** Who holds the GPU now: { lanes: [{ hold }] } — null when the server cannot say. */
+async function state(server) {
+  try {
+    const r = await fetch(`${server}/api/gpu`, { signal: AbortSignal.timeout(8000) })
+    return r.ok ? await r.json() : null
+  } catch { return null }
+}
+
+/** The hold of another run on every GPU (all busy), or null (one is free, or it is this run's). */
+function busyFor(gpu, mine = null) {
+  const lanes = gpu?.lanes || []
+  if (!lanes.length || lanes.some((l) => !l.hold || l.hold.run === mine)) return null
+  return lanes[0].hold
+}
+
+module.exports = { holding, headers, state, busyFor, GpuBusyError, store }

package/ext/gpuServer.js

@@ -0,0 +1,76 @@
+'use strict'
+// Where the work goes: the GPU server — one rule for every part of the extension and the CLI.
+//   1. the address set here (`aipictury.server`: a user or workspace setting, the CLI's --server
+//      or AIPICTURY_URL) when there is one — this machine's own choice;
+//   2. else the one chosen with the AIPictury account (aipictury.com keeps it in the account's
+//      preferences as `gpuServer`: a LAN and a WAN address, and which to prefer) — the LAN one
+//      when it answers, as the web app does;
+//   3. else none: the panel says where to choose it.
+const vscode = require('vscode')
+
+let chosen = null          // the account's { lan, wan, prefer }
+let active = ''            // the address picked from it
+const listeners = new Set()
+
+const clean = (u) => String(u || '').trim().replace(/\/+$/, '')
+
+/** The address set on this machine, or ''. */
+function explicit() {
+  return clean(vscode.workspace.getConfiguration('aipictury').get('server', ''))
+}
+
+/** The GPU server's address, or '' when none is set anywhere. */
+function url() {
+  return explicit() || active
+}
+
+/** Which of the account's addresses is in use: 'lan' | 'wan' | null. */
+function route() {
+  if (explicit() || !chosen || !active) return null
+  return active === chosen.lan ? 'lan' : 'wan'
+}
+
+/** Where the address came from: 'setting' | 'account' | null. */
+function source() {
+  return explicit() ? 'setting' : active ? 'account' : null
+}
+
+async function answers(base, ms) {
+  try {
+    const r = await fetch(`${base}/api/health`, { signal: AbortSignal.timeout(ms) })
+    return r.ok && (await r.json()).app === 'AIPictury'
+  } catch { return false }
+}
+
+/** Picks from the account's choice: the preferred route that answers; else the WAN address (so
+ *  what goes wrong is said about it), else the LAN one. */
+async function resolve() {
+  const before = active
+  if (!chosen) active = ''
+  else {
+    const order = chosen.prefer === 'wan' ? ['wan', 'lan'] : ['lan', 'wan']
+    let picked = ''
+    for (const route of order) {
+      if (chosen[route] && await answers(chosen[route], route === 'lan' ? 1500 : 5000)) { picked = chosen[route]; break }
+    }
+    active = picked || chosen.wan || chosen.lan || ''
+  }
+  if (active !== before) for (const fn of listeners) { try { fn(url()) } catch { /* a listener's own problem */ } }
+  return url()
+}
+
+/** The account's choice (or null: signed out, none kept), then the address resolved from it. */
+async function adopt(choice) {
+  const lan = clean(choice?.lan)
+  const wan = clean(choice?.wan)
+  chosen = lan || wan ? { lan, wan, prefer: ['lan', 'wan'].includes(choice?.prefer) ? choice.prefer : 'auto' } : null
+  return resolve()
+}
+
+/** fn(url) when the account's address changes (a setting changed is VS Code's own event). */
+function onChange(fn) {
+  listeners.add(fn)
+  return { dispose: () => listeners.delete(fn) }
+}
+
+module.exports = { url, explicit, source, route, adopt, resolve, onChange }

package/ext/hooks.js

@@ -0,0 +1,153 @@
+'use strict'
+// Hooks: your commands, run at moments of the agent's work — in Claude Code's format, from
+// the same settings files (Claude Code's own included), so hooks written for it work here:
+//
+//   "hooks": { "PreToolUse": [ { "matcher": "Bash|Edit", "hooks": [ { "type": "command",
+//              "command": "~/bin/check.sh", "timeout": 30 } ] } ] }
+//
+// A hook gets the event as JSON on stdin (session_id, cwd, hook_event_name, tool_name,
+// tool_input, tool_response, prompt…) and CLAUDE_PROJECT_DIR / AIPICTURY_PROJECT_DIR. It
+// answers with its exit code — 2 blocks, and what it wrote to stderr is the reason — or with
+// JSON on stdout: decision "block", hookSpecificOutput.permissionDecision (allow, deny, ask),
+// additionalContext, continue: false with a stopReason. Any other failure is reported and the
+// work goes on. No VS Code here: tests run it directly, and so will the CLI.
+const { spawn } = require('child_process')
+const crypto = require('crypto')
+const path = require('path')
+const prefs = require('./prefs')
+
+const EVENTS = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Stop', 'SubagentStop', 'SessionStart',
+  'SessionEnd', 'Notification', 'PreCompact']
+const DEFAULT_TIMEOUT = 60
+const OUTPUT_CAP = 100_000
+
+// Claude Code's names for our tools, so a matcher like "Bash|Edit|Write" matches ours.
+const CLAUDE_NAME = {
+  run_command: 'Bash', monitor: 'Monitor', powershell: 'PowerShell', read_file: 'Read', write_file: 'Write', edit_file: 'Edit', notebook_edit: 'NotebookEdit',
+  grep: 'Grep', glob: 'Glob', list_files: 'LS', fetch_url: 'WebFetch', web_search: 'WebSearch', task: 'Task',
+  todo_write: 'TodoWrite', exit_plan_mode: 'ExitPlanMode', enter_plan_mode: 'EnterPlanMode', ask_user: 'AskUserQuestion',
+  tool_search: 'ToolSearch', list_mcp_resources: 'ListMcpResourcesTool', read_mcp_resource: 'ReadMcpResourceTool',
+}
+const claudeName = (name) => CLAUDE_NAME[name] || name
+
+/** A call's arguments as Claude Code's tools take them (absolute file_path, old_string…),
+ *  with ours kept beside them. */
+function toolInput(name, args = {}, root) {
+  const abs = (p) => (p ? path.resolve(root || '/', p) : undefined)
+  const extra = {}
+  if (args.path && ['read_file', 'write_file', 'edit_file', 'notebook_edit'].includes(name)) extra.file_path = abs(args.path)
+  if (name === 'edit_file') {
+    if (args.old_text !== undefined) extra.old_string = args.old_text
+    if (args.new_text !== undefined) extra.new_string = args.new_text
+  }
+  if (name === 'notebook_edit') extra.notebook_path = abs(args.path)
+  if (name === 'fetch_url') extra.prompt = args.query
+  return { ...args, ...extra }
+}
+
+/** The hook groups for an event whose matcher covers this tool (or every group, for events
+ *  without tools). A matcher is a regular expression; empty or "*" is everything. */
+function matching(configured, event, subject) {
+  return (configured[event] || []).filter((group) => {
+    const m = String(group.matcher ?? '').trim()
+    if (!m || m === '*' || subject === undefined) return true
+    try { return new RegExp(`^(?:${m})$`).test(subject) } catch { return m === subject }
+  })
+}
+
+/** Runs one command hook: resolves to { code, stdout, stderr, timedOut, error }. */
+function runOne(command, input, { cwd, env, timeout = DEFAULT_TIMEOUT, signal } = {}) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(process.platform === 'win32' ? 'cmd' : '/bin/sh', process.platform === 'win32' ? ['/c', command] : ['-c', command],
+        { cwd, env, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] })
+    } catch (error) { resolve({ code: null, stdout: '', stderr: '', error: error.message }); return }
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+    const kill = () => { try { process.kill(-child.pid, 'SIGKILL') } catch { try { child.kill('SIGKILL') } catch { /* gone */ } } }
+    const timer = setTimeout(() => { timedOut = true; kill() }, Math.max(1, Number(timeout) || DEFAULT_TIMEOUT) * 1000)
+    const onAbort = () => kill()
+    signal?.addEventListener('abort', onAbort, { once: true })
+    child.stdout.on('data', (c) => { if (stdout.length < OUTPUT_CAP) stdout += c })
+    child.stderr.on('data', (c) => { if (stderr.length < OUTPUT_CAP) stderr += c })
+    child.on('error', (error) => { clearTimeout(timer); resolve({ code: null, stdout, stderr, error: error.message }) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+      resolve({ code: timedOut ? null : code, stdout, stderr, timedOut })
+    })
+    child.stdin.on('error', () => { /* a hook that does not read its input */ })
+    child.stdin.end(JSON.stringify(input))
+  })
+}
+
+/** What the hooks of one event decided, all of them together. */
+function combine(event, results) {
+  const out = { block: false, reasons: [], context: [], permission: null, permissionReasons: [], stop: false,
+    stopReason: '', errors: [], ran: results.length }
+  const order = { deny: 3, ask: 2, allow: 1 }
+  for (const { hook, r } of results) {
+    const where = `${hook.command.slice(0, 60)}`
+    if (r.error || r.timedOut) { out.errors.push(`${where}: ${r.timedOut ? `no answer in ${hook.timeout || DEFAULT_TIMEOUT} s` : r.error}`); continue }
+    let json = null
+    if (r.code === 0 && r.stdout.trim().startsWith('{')) { try { json = JSON.parse(r.stdout) } catch { json = null } }
+    if (r.code === 2) {
+      out.block = true
+      out.reasons.push(r.stderr.trim() || `blocked by ${where}`)
+      continue
+    }
+    if (r.code !== 0) { out.errors.push(`${where}: exit ${r.code}${r.stderr.trim() ? ` — ${r.stderr.trim().slice(0, 300)}` : ''}`); continue }
+    if (!json) {
+      // Plain output: for these two events it is context the model is given.
+      if (['UserPromptSubmit', 'SessionStart'].includes(event) && r.stdout.trim()) out.context.push(r.stdout.trim())
+      continue
+    }
+    if (json.continue === false) { out.stop = true; out.stopReason = json.stopReason || out.stopReason }
+    if (json.decision === 'block') { out.block = true; out.reasons.push(json.reason || `blocked by ${where}`) }
+    const specific = json.hookSpecificOutput || {}
+    const decision = specific.permissionDecision || (json.decision === 'approve' ? 'allow' : null)
+    if (decision && order[decision] > (order[out.permission] || 0)) out.permission = decision
+    if (decision) out.permissionReasons.push(specific.permissionDecisionReason || json.reason || '')
+    if (specific.additionalContext) out.context.push(String(specific.additionalContext))
+  }
+  return out
+}
+
+/** A fingerprint of the project's own hooks: trust given to them is for these exactly. */
+function fingerprint(groups) {
+  return crypto.createHash('sha256').update(JSON.stringify(groups.map((g) => ({ file: g.file, matcher: g.matcher, hooks: g.hooks })))).digest('hex').slice(0, 16)
+}
+
+/**
+ * Runs the hooks of `event`. `trust(groups)` is asked before hooks from the project's own files
+ * run (yours, at the user level, always run); `subject` is the tool name for tool events.
+ * Resolves to what they decided together (combine).
+ */
+async function fire(event, payload, { folder, subject, sessionId = '', trust = async () => true, signal, log } = {}) {
+  const configured = { ...(prefs.load(folder).merged.hooks || {}) }
+  // The plugins' hooks (hooks/hooks.json): installed by the user, so trusted like theirs.
+  try {
+    for (const [ev, groups] of Object.entries(require('./plugins').hooks(folder))) configured[ev] = [...(configured[ev] || []), ...groups.map((g) => ({ ...g, level: 'user' }))]
+  } catch { /* no plugins */ }
+  const groups = matching(configured, event, subject === undefined ? undefined : claudeName(subject))
+  if (!groups.length) return combine(event, [])
+  const fromProject = groups.filter((g) => g.level !== 'user')
+  const trusted = !fromProject.length || await trust(fromProject, fingerprint(fromProject))
+  const usable = trusted ? groups : groups.filter((g) => g.level === 'user')
+  // The same command twice (Claude Code's file and ours) runs once.
+  const seen = new Set()
+  const hooks = usable.flatMap((g) => (g.hooks || []).filter((h) => h.type === 'command' && h.command))
+    .filter((h) => !seen.has(h.command) && seen.add(h.command))
+  const env = { ...process.env, CLAUDE_PROJECT_DIR: folder || '', AIPICTURY_PROJECT_DIR: folder || '' }
+  const input = { session_id: sessionId, cwd: folder || process.cwd(), hook_event_name: event, ...payload }
+  const results = await Promise.all(hooks.map(async (hook) => ({ hook, r: await runOne(hook.command, input,
+    { cwd: folder || process.cwd(), env, timeout: hook.timeout, signal }) })))
+  const out = combine(event, results)
+  if (!trusted) out.errors.push('hooks from this project were not run: not trusted')
+  for (const e of out.errors) log?.(`${event} hook: ${e}`)
+  return out
+}
+
+module.exports = { fire, runOne, combine, matching, toolInput, claudeName, fingerprint, EVENTS }

package/ext/log.js

@@ -0,0 +1,29 @@
+'use strict'
+// The extension's log: View → Output → "AIPictury", or the "AIPictury: Show Logs" command.
+// What is worth reading after something went wrong — a turn, a failure, a stall, a setting
+// that could not be written — never the conversation itself.
+const vscode = require('vscode')
+
+let channel = null
+function out() {
+  if (!channel) {
+    try { channel = vscode.window.createOutputChannel('AIPictury', { log: true }) } catch { channel = null }
+  }
+  return channel
+}
+
+// The last lines, kept here too: VS Code offers no way to read an output channel back, and a
+// problem report needs them.
+const recent = []
+const KEEP = 400
+
+const write = (level) => (...parts) => {
+  const text = parts.map((p) => (p instanceof Error ? p.stack || p.message : typeof p === 'string' ? p : JSON.stringify(p))).join(' ')
+  recent.push(`${new Date().toISOString()} [${level}] ${text}`)
+  if (recent.length > KEEP) recent.splice(0, recent.length - KEEP)
+  const c = out()
+  if (c && typeof c[level] === 'function') c[level](text)
+  else if (c) c.appendLine(`[${level}] ${text}`)
+}
+
+module.exports = { tail: () => [...recent], info: write('info'), warn: write('warn'), error: write('error'), show: () => out()?.show(true), channel: out }

package/ext/lsp.js

@@ -0,0 +1,122 @@
+'use strict'
+// Code intelligence from the language servers VS Code already runs — Claude Code's LSP
+// tool, without installing anything: where a symbol is defined, who uses it, its type,
+// what a file declares, who calls a function. A model finds a column badly, so a
+// position may be given as a line and the symbol's name on it.
+
+const vscode = require('vscode')
+const { resolve, rel } = require('./paths')
+
+const OPS = ['definition', 'references', 'hover', 'type_definition', 'implementations',
+  'document_symbols', 'workspace_symbols', 'incoming_calls', 'outgoing_calls']
+const CAP = 60
+
+const KIND = Object.fromEntries(Object.entries(vscode.SymbolKind || {}).map(([k, v]) => [v, k.toLowerCase()]))
+
+async function lineText(uri, line) {
+  try { return (await vscode.workspace.openTextDocument(uri)).lineAt(line).text.trim() } catch { return '' }
+}
+
+async function where(loc) {
+  const uri = loc.targetUri || loc.uri
+  const range = loc.targetSelectionRange || loc.targetRange || loc.range
+  const line = range.start.line
+  let p
+  try { p = rel(uri) } catch { p = uri.fsPath }
+  return `${p}:${line + 1}:${range.start.character + 1}  ${(await lineText(uri, line)).slice(0, 200)}`
+}
+
+/** The position asked for: line (1-based) and either a column or the symbol's name. */
+async function position(doc, args) {
+  const line = Math.max(0, Math.min(doc.lineCount - 1, (Number(args.line) || 1) - 1))
+  const text = doc.lineAt(line).text
+  if (args.symbol) {
+    const name = String(args.symbol)
+    const escaped = name.replace(/[.*+?^$()|[\]\\{}]/g, (c) => `\\${c}`)
+    const re = new RegExp(`(^|[^\\w$])(${escaped})(?![\\w$])`)
+    const m = re.exec(text)
+    if (m) return new vscode.Position(line, m.index + m[1].length)
+    // Not on that line: the nearest line that has it, a few either way.
+    for (let d = 1; d <= 5; d += 1) {
+      for (const l of [line - d, line + d]) {
+        if (l < 0 || l >= doc.lineCount) continue
+        const mm = re.exec(doc.lineAt(l).text)
+        if (mm) return new vscode.Position(l, mm.index + mm[1].length)
+      }
+    }
+    throw new Error(`${name} is not on line ${line + 1} (or near it) — read the file for the right line`)
+  }
+  const col = Math.max(0, (Number(args.character) || (text.search(/\S/) + 1) || 1) - 1)
+  return new vscode.Position(line, Math.min(col, text.length))
+}
+
+function flatSymbols(list, depth = 0, out = []) {
+  for (const s of list || []) {
+    const range = s.selectionRange || s.location?.range
+    out.push(`${'  '.repeat(depth)}${KIND[s.kind] || 'symbol'} ${s.name}${range ? `  (line ${range.start.line + 1})` : ''}`)
+    if (s.children?.length) flatSymbols(s.children, depth + 1, out)
+  }
+  return out
+}
+
+// A language server that is busy (indexing) or wedged answers late or never; the agent is
+// told so, rather than waiting on it for ever.
+const LSP_LIMIT = 20_000
+
+function bounded(promise, what, ms = LSP_LIMIT) {
+  let timer
+  const late = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`the language server did not answer ${what.replace('vscode.execute', '').replace('Provider', '')} `
+      + `within ${ms / 1000}s — it may still be indexing; try grep instead`)), ms)
+  })
+  return Promise.race([Promise.resolve(promise), late]).finally(() => clearTimeout(timer))
+}
+
+async function codeIntel(args) {
+  const op = String(args.operation || '')
+  if (!OPS.includes(op)) throw new Error(`operation must be one of: ${OPS.join(', ')}`)
+  const run = (cmd, ...a) => bounded(vscode.commands.executeCommand(cmd, ...a), cmd)
+  if (op === 'workspace_symbols') {
+    const found = await run('vscode.executeWorkspaceSymbolProvider', String(args.query || args.symbol || ''))
+    if (!found?.length) return `no symbol matches ${JSON.stringify(args.query || args.symbol || '')}`
+    const lines = await Promise.all(found.slice(0, CAP).map(async (s) => `${KIND[s.kind] || 'symbol'} ${s.name} — ${await where(s.location)}`))
+    return lines.join('\n') + (found.length > CAP ? `\n… ${found.length - CAP} more` : '')
+  }
+  if (!args.path) throw new Error('path is required')
+  const uri = resolve(args.path)
+  const doc = await vscode.workspace.openTextDocument(uri)
+  if (op === 'document_symbols') {
+    const symbols = await run('vscode.executeDocumentSymbolProvider', uri)
+    if (!symbols?.length) return `no symbols reported for ${args.path} (is a language extension for it installed?)`
+    return flatSymbols(symbols).slice(0, 300).join('\n')
+  }
+  const pos = await position(doc, args)
+  const at = `${args.path}:${pos.line + 1}:${pos.character + 1}`
+  if (op === 'hover') {
+    const hovers = await run('vscode.executeHoverProvider', uri, pos)
+    const text = (hovers || []).flatMap((h) => h.contents.map((c) => (typeof c === 'string' ? c : c.value || ''))).join('\n\n').trim()
+    return text ? `${at}\n${text.slice(0, 4000)}` : `nothing known about ${at}`
+  }
+  if (op === 'incoming_calls' || op === 'outgoing_calls') {
+    const items = await run('vscode.prepareCallHierarchy', uri, pos)
+    if (!items?.length) return `no call hierarchy at ${at}`
+    const calls = await run(op === 'incoming_calls' ? 'vscode.provideIncomingCalls' : 'vscode.provideOutgoingCalls', items[0])
+    if (!calls?.length) return `no ${op === 'incoming_calls' ? 'callers of' : 'calls from'} ${items[0].name}`
+    const lines = await Promise.all(calls.slice(0, CAP).map(async (c) => {
+      const item = c.from || c.to
+      return `${KIND[item.kind] || ''} ${item.name} — ${await where({ uri: item.uri, range: item.selectionRange })}`
+    }))
+    return `${op === 'incoming_calls' ? 'Called by' : 'Calls'} (${items[0].name}):\n${lines.join('\n')}`
+  }
+  const command = { definition: 'vscode.executeDefinitionProvider', references: 'vscode.executeReferenceProvider',
+    type_definition: 'vscode.executeTypeDefinitionProvider', implementations: 'vscode.executeImplementationProvider' }[op]
+  const found = await run(command, uri, pos)
+  const noun = { definition: ['definition', 'definitions'], references: ['reference', 'references'],
+    type_definition: ['type definition', 'type definitions'], implementations: ['implementation', 'implementations'] }[op]
+  if (!found?.length) return `no ${noun[1]} found for ${at} (is a language extension for this file installed?)`
+  const lines = await Promise.all(found.slice(0, CAP).map(where))
+  return `${found.length} ${noun[found.length === 1 ? 0 : 1]} for ${at}:\n${lines.join('\n')}`
+    + (found.length > CAP ? `\n… ${found.length - CAP} more` : '')
+}
+
+module.exports = { bounded, LSP_LIMIT, codeIntel, OPS }