@davait/aipictury 1.9.2

package/ext/shell.js

@@ -0,0 +1,357 @@
+'use strict'
+// Shell commands, as Claude Code's Bash tool runs them:
+// - bash, in the workspace, with the directory a `cd` left carried over to the next command;
+// - a timeout the model can set (2 minutes by default, 10 at most). A command still going
+//   when it runs out is not killed but left running in the background, as Claude Code does;
+// - `run_in_background` for what never ends — a dev server, a watcher — whose output is
+//   read later with bash_output and which is stopped with kill_shell;
+// - a server that says it is listening and goes quiet is noticed and left running;
+// - exit 1 from grep, diff, test and the like is an answer ("no match"), not a failure;
+// - output kept whole when short, its start and end when long.
+// Every command gets its own process group, so Stop kills it and all it started at once.
+
+const { spawn } = require('child_process')
+const sandboxing = require('./sandbox')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { root, extraRoots } = require('./paths')
+const { safeSlice, wellFormed } = require('./text')
+
+// Colour is noise to the model, and worse: a shell that exports GREP_OPTIONS=--color=always
+// made every grep come back with escape codes inside the matches, and the model, unable to
+// read them, ran the same search again and again. Commands get an environment that asks for
+// no colour, and what comes out anyway is cleaned.
+const ESC = String.fromCharCode(27)
+const BEL = String.fromCharCode(7)
+const ANSI = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]|${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)|${ESC}[()][A-Za-z0-9]`, 'g')
+const plain = (text) => wellFormed(String(text).replace(ANSI, '').replace(/\r(?!\n)/g, '\n'))
+
+// What the user asked to add to every command: the workspace's Python environment (the one
+// the Python extension selected), the `env` of the settings files, and the
+// aipictury.environmentVariables setting — later ones win. Set by the extension.
+let extra = { python: null, files: {}, setting: {} }
+function setExtraEnv(part, value) { extra = { ...extra, [part]: value } }
+
+function commandEnv() {
+  const env = { ...process.env, GIT_PAGER: 'cat', PAGER: 'cat', CI: '1', GIT_TERMINAL_PROMPT: '0',
+                FORCE_COLOR: '0', NO_COLOR: '1', CLICOLOR: '0', TERM: 'dumb' }
+  for (const key of ['GREP_OPTIONS', 'GREP_COLOR', 'GREP_COLORS', 'CLICOLOR_FORCE', 'LS_COLORS']) delete env[key]
+  if (extra.python) {
+    env.PATH = `${extra.python.bin}${path.delimiter}${env.PATH || ''}`
+    if (extra.python.venv) env.VIRTUAL_ENV = extra.python.venv
+    delete env.PYTHONHOME
+  }
+  Object.assign(env, extra.files || {}, extra.setting || {})
+  return env
+}
+
+const DEFAULT_TIMEOUT = 120      // seconds
+const MAX_TIMEOUT = 600
+const SERVER_QUIET = 3_000       // quiet this long after saying it is ready → a server that is up
+const SHOWN = 30_000             // characters of output handed back whole
+const KEEP = 1_000_000           // characters a background task keeps
+
+// A command that prints this and then goes quiet has started a server: it will not exit.
+const READY = /listening|ready in|running (at|on)|started server|localhost:\d+|127\.0\.0\.1:\d+|0\.0\.0\.0:\d+|press ctrl\+c/i
+
+// Exit 1 that means "no" rather than "broken".
+const BENIGN = /^\s*(?:\S+=\S+\s+)*(grep|egrep|fgrep|rg|ag|diff|cmp|test|\[|find|git\s+(diff|grep|ls-files|merge-base))\b/
+
+// ---- the shell's working directory, per conversation ----
+
+// Every marker is removed: when its command ends, or — for one still running when VS Code
+// closes — when the extension host exits.
+const markers = new Set()
+const dropMarker = (marker) => { markers.delete(marker); try { fs.unlinkSync(marker) } catch { /* never written */ } }
+process.on('exit', () => { for (const marker of markers) dropMarker(marker) })
+const cwdFile = () => {
+  const marker = path.join(os.tmpdir(), `aipictury-cwd-${process.pid}-${Math.random().toString(36).slice(2, 8)}`)
+  markers.add(marker)
+  return marker
+}
+
+/** The command wrapped so the directory it ends in is recorded, and its exit code kept. */
+function wrap(command, cwd, marker) {
+  const quoted = (p) => `'${p.replace(/'/g, `'\\''`)}'`
+  return `cd ${quoted(cwd)} 2>/dev/null || cd ${quoted(root().fsPath)}\n${command}\n__aip_rc=$?\npwd -P > ${quoted(marker)} 2>/dev/null\nexit $__aip_rc`
+}
+
+/** Where the next command starts: the conversation's directory, when still in the workspace. */
+function startDir(session) {
+  const base = root().fsPath
+  const cwd = session?.cwd
+  if (!cwd) return base
+  const inside = cwd === base || cwd.startsWith(base + path.sep)
+  return inside && fs.existsSync(cwd) ? cwd : base
+}
+
+function followCwd(session, marker) {
+  let note = ''
+  try {
+    let now
+    try { now = fs.readFileSync(marker, 'utf8').trim() } finally { dropMarker(marker) }
+    if (!now || !session) return ''
+    const base = fs.realpathSync(root().fsPath)
+    if (now === base || now.startsWith(base + path.sep)) {
+      session.cwd = now === base ? root().fsPath : path.join(root().fsPath, path.relative(base, now))
+    } else {
+      session.cwd = root().fsPath
+      note = `\n[the command left the workspace (${now}); the next one starts in the workspace root again]`
+    }
+  } catch { /* the command exited before recording it (exec, a crash): keep the old one */ }
+  return note
+}
+
+// ---- output ----
+
+/** What the model reads of a command's output: whole when short, else its start and its end. */
+function shown(out) {
+  const t = plain(out).replace(/\s+$/, '')
+  if (!t) return '(no output)'
+  if (t.length <= SHOWN) return t
+  const head = safeSlice(t, 0, 8_000)
+  const tail = safeSlice(t, t.length - 20_000)
+  return `${head}\n\n… [${t.length - 28_000} characters of output not shown] …\n\n${tail}`
+}
+
+// ---- background tasks ----
+
+const tasks = new Map()          // id → { child, command, out, read, exit, started, cwd }
+let nextTask = 1
+const stopGroup = (child) => { try { process.kill(-child.pid, 'SIGKILL') } catch { /* already gone */ } }
+
+function keep(task, chunk) {
+  task.out += chunk.toString()
+  if (task.out.length > KEEP) {
+    const cut = task.out.length - KEEP
+    task.out = task.out.slice(cut)
+    task.read = Math.max(0, task.read - cut)
+    task.dropped = (task.dropped || 0) + cut
+  }
+}
+
+/** Leaves a running child as a background task the model can read and stop. */
+function adopt(child, command, out, onChange) {
+  const id = `bash_${nextTask++}`
+  const task = { id, child, command, out: '', read: 0, exit: null, started: Date.now() }
+  keep(task, out)
+  task.read = task.out.length                // what was already shown is not shown again
+  child.stdout?.removeAllListeners('data')
+  child.stderr?.removeAllListeners('data')
+  child.stdout?.on('data', (c) => keep(task, c))
+  child.stderr?.on('data', (c) => keep(task, c))
+  child.on('close', (code, sig) => { task.exit = code ?? sig ?? 'killed'; onChange?.() })
+  tasks.set(id, task)
+  onChange?.()
+  return task
+}
+
+/** A monitor: a command left running whose output lines reach the agent as events — in batches,
+ *  at most one a second, each line whole. Stopped like any background task (kill_shell), or at
+ *  its time limit. `onLines(task, lines, { ended })` is called with each batch. */
+function startMonitor(command, { session, onLines, limitMs = 30 * 60_000, sandbox: boxed = null, description = '' } = {}) {
+  const shell = fs.existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh'
+  const quoted = (p) => `'${p.replace(/'/g, `'\\''`)}'`
+  const script = `cd ${quoted(startDir(session))} 2>/dev/null || cd ${quoted(root().fsPath)}\n${command}`
+  const w = boxed ? sandboxing.wrap(shell, script, boxed) : { file: shell, args: ['-c', script] }
+  const child = spawn(w.file, w.args, { cwd: root().fsPath, detached: process.platform !== 'win32', env: commandEnv() })
+  const task = adopt(child, command, '', null)
+  task.monitor = { description, delivered: 0 }
+  let partial = ''
+  let batch = []
+  let timer = null
+  const flush = (ended = false) => {
+    clearTimeout(timer); timer = null
+    if (!batch.length && !ended) return
+    const lines = batch.slice(0, 200)
+    if (batch.length > 200) lines.push(`… ${batch.length - 200} more lines`)
+    batch = []
+    task.monitor.delivered += lines.length
+    try { onLines?.(task, lines, { ended }) } catch { /* a listener's own problem */ }
+  }
+  const take = (chunk) => {
+    partial += String(chunk)
+    const parts = partial.split('\n')
+    partial = parts.pop()
+    batch.push(...parts.map((l) => l.replace(/\r$/, '')).filter((l) => l.trim()))
+    if (batch.length && !timer) timer = setTimeout(() => flush(), 1000)
+  }
+  child.stdout?.on('data', take)
+  child.stderr?.on('data', take)
+  const limit = setTimeout(() => { stopGroup(child) }, Math.max(1000, Math.min(limitMs, 2 * 3_600_000)))
+  child.on('close', (code, sig) => {
+    clearTimeout(limit)
+    if (partial.trim()) batch.push(partial.trim())
+    batch.push(`[the monitor stopped: ${code === null ? `killed (${sig})` : `exit ${code}`}]`)
+    flush(true)
+  })
+  return task
+}
+
+/** PowerShell, where there is one: Windows' own, or PowerShell 7 (pwsh) on the PATH. */
+function powershellPath(env = process.env, platform = process.platform) {
+  const names = platform === 'win32' ? ['pwsh.exe', 'powershell.exe'] : ['pwsh']
+  for (const dir of String(env.PATH || '').split(path.delimiter)) {
+    for (const n of names) { const p = path.join(dir, n); if (dir && fs.existsSync(p)) return p }
+  }
+  return platform === 'win32' ? 'powershell.exe' : null
+}
+
+function taskList() {
+  return [...tasks.values()].map((t) => ({ id: t.id, command: t.command, running: t.exit === null,
+    exit: t.exit, seconds: Math.round((Date.now() - t.started) / 1000) }))
+}
+
+/** New output of a background task since it was last read. */
+function bashOutput(args) {
+  const task = tasks.get(String(args.bash_id || args.id || ''))
+  if (!task) {
+    const known = [...tasks.keys()]
+    throw new Error(`no background task ${args.bash_id || ''}${known.length ? ` — running: ${known.join(', ')}` : ' — none are running'}`)
+  }
+  let fresh = task.out.slice(task.read)
+  task.read = task.out.length
+  if (args.filter) {
+    let re
+    try { re = new RegExp(String(args.filter)) } catch (e) { throw new Error(`bad filter: ${e.message}`, { cause: e }) }
+    fresh = fresh.split('\n').filter((l) => re.test(l)).join('\n')
+  }
+  const state = task.exit === null ? `still running (${Math.round((Date.now() - task.started) / 1000)}s)` : `exited: ${task.exit}`
+  return `${task.id} — ${task.command}\n${state}\n\n${fresh.trim() ? shown(fresh) : '(no new output)'}`
+}
+
+function killShell(args) {
+  const task = tasks.get(String(args.shell_id || args.bash_id || args.id || ''))
+  if (!task) throw new Error(`no background task ${args.shell_id || ''}`)
+  if (task.exit === null) stopGroup(task.child)
+  task.exit ??= 'killed'
+  return `stopped ${task.id} (${task.command})`
+}
+
+/** Stops every background task — when VS Code closes, or the user asks. */
+function stopBackground() {
+  for (const task of tasks.values()) if (task.exit === null) stopGroup(task.child)
+  tasks.clear()
+}
+
+// ---- read-only commands ----
+// Commands that only look: run without asking in Manual, and allowed in Plan mode, as
+// Claude Code's built-in read-only commands are. Anything that could write — redirection,
+// command substitution, an option that changes files — is not one.
+const READ_ONLY_CMD = /^(ls|ll|pwd|cat|head|tail|wc|file|stat|du|df|tree|which|whereis|type|echo|printf|date|uname|whoami|env(?=\s*$)|printenv|grep|egrep|fgrep|rg|ag|find|fd|sort|uniq|cut|tr|column|diff|cmp|basename|dirname|realpath|readlink|nl|jq|yq|true|node\s+(-v|--version)|npm\s+(ls|list|view|outdated|-v|--version|run$)|npx\s+--version|yarn\s+(-v|--version)|pnpm\s+(-v|--version)|python3?\s+(-V|--version)|pip3?\s+(list|show|freeze)|go\s+(version|env|list)|cargo\s+(--version|tree|metadata)|git\s+(status|log|diff|show|branch|tag|remote|rev-parse|ls-files|blame|describe|shortlog|config\s+--get|stash\s+list|grep|reflog))\b/
+// Redirections that only silence or merge output: 2>&1, >&2, 2>/dev/null, &>/dev/null.
+const QUIET = /\s*(?:\d?>&\d|&?\d?>>?\s*\/dev\/null)(?=\s|$|[;&|])/g
+// Anything that could write or run something else, anywhere in the line.
+const UNSAFE = new RegExp([
+  String.raw`>|<\(|\$\(|` + '`',                                       // redirection, substitution
+  String.raw`(^|[^&])&(?!&)`,                                          // a command sent to the background
+  String.raw`(^|\s)(-delete|-exec|-execdir|-ok|-okdir|-fprint\S*|--output\S*|-o|--pre|--pre-glob)(\s|=|$)`,
+  String.raw`\bsed\s+-i|\btee\b|\byq\b.*\s-i\b`,
+  String.raw`\bgit\s+(branch|tag)\b.*\s(-[a-zA-Z]*[dDmMcCfu]\b|--(delete|move|copy|force|set-upstream\S*|unset-upstream|edit-description))`,
+  // a bare name creates a branch or tag, unless it is a pattern to list by
+  String.raw`\bgit\s+(branch|tag)\b(?!.*\s(-l|--list|--contains|--no-contains|--merged|--no-merged|--points-at)\b)(\s+-\S+)*\s+[^-\s;&|]`,
+  String.raw`\bgit\s+remote\s+(add|remove|rm|rename|set-url|set-head|set-branches|prune|update)\b`,
+].join('|'))
+
+function isReadOnly(command) {
+  const c = String(command || '').trim().replace(QUIET, '')
+  if (!c || /\n/.test(c)) return false
+  if (UNSAFE.test(c)) return false
+  // Every command of a list or pipeline must be a read-only one.
+  return c.split(/\s*(?:\|\||&&|;|\|)\s*/).filter(Boolean).every((part) => READ_ONLY_CMD.test(part.trim()))
+}
+
+/** Whether a command names a path outside the workspace and the added folders (/etc/hosts,
+ *  ~/.ssh, ../other): read-only or not, that is asked about first, as Claude Code does. */
+function readsOutside(command) {
+  let base
+  try { base = root().fsPath } catch { return false }
+  const roots = [base, ...extraRoots()]
+  const within = (abs) => roots.some((r) => abs === r || abs.startsWith(r + path.sep)) || abs === '/dev/null'
+  const words = String(command || '').replace(QUIET, '').split(/[\s;&|<>()]+/).map((w) => w.replace(/^['"]|['"]$/g, '')).filter(Boolean)
+  return words.some((word) => {
+    const value = word.startsWith('-') && word.includes('=') ? word.slice(word.indexOf('=') + 1) : word
+    if (value.startsWith('-')) return false
+    if (value.startsWith('~')) return !within(path.join(os.homedir(), value.slice(1)))
+    if (value.startsWith('/')) return !within(path.resolve(value))
+    if (/(^|\/)\.\.(\/|$)/.test(value)) return !within(path.resolve(base, value))
+    return false
+  })
+}
+
+// ---- running ----
+
+/** Runs a shell command in the workspace and returns what it printed. */
+function runCommand(command, options = {}) {
+  // runCommand(command, signal) — the older form — still works.
+  const { signal, session, timeout, background = false, onTasks, sandbox: boxed = null, powershell = false } = options && typeof options.aborted === 'boolean'
+    ? { signal: options } : options || {}
+  return new Promise((done) => {
+    const started = Date.now()
+    const limit = Math.min(MAX_TIMEOUT, Math.max(1, Number(timeout) || DEFAULT_TIMEOUT)) * 1000
+    const marker = cwdFile()
+    const shell = fs.existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh'
+    let child
+    try {
+      child = powershell
+        ? spawn(powershellPath(), ['-NoProfile', '-NonInteractive', '-Command', command], { cwd: startDir(session), env: commandEnv(), detached: process.platform !== 'win32' })
+        : process.platform === 'win32'
+        ? spawn(command, { shell: true, cwd: startDir(session), env: commandEnv() })
+        : boxed
+          // Sandboxed: writes kept to the workspace, the network as allowed (sandbox.js).
+          ? (() => { const w = sandboxing.wrap(shell, wrap(command, startDir(session), marker), boxed)
+            return spawn(w.file, w.args, { cwd: root().fsPath, detached: true, env: commandEnv() }) })()
+          : spawn(shell, ['-c', wrap(command, startDir(session), marker)], { cwd: root().fsPath, detached: true, env: commandEnv() })
+    } catch (error) {
+      dropMarker(marker)
+      done(`could not run it: ${error.message}`)
+      return
+    }
+    let finished = false
+    let out = ''
+    let lastOutput = started
+    const finish = (text) => {
+      if (finished) return
+      finished = true
+      clearInterval(watch)
+      signal?.removeEventListener('abort', onAbort)
+      done(text)
+    }
+    const add = (chunk) => { if (out.length < 5_000_000) out += chunk.toString(); lastOutput = Date.now() }
+    child.stdout.on('data', add)
+    child.stderr.on('data', add)
+
+    const onAbort = () => { stopGroup(child); finish(`stopped by the user\n${shown(out)}`) }
+    signal?.addEventListener('abort', onAbort, { once: true })
+
+    const leave = (why) => {
+      const task = adopt(child, command, out, onTasks)
+      finish(`${why} — left running in the background as ${task.id}.\n${shown(out)}\n\n`
+        + `Read its new output with bash_output (bash_id "${task.id}"); stop it with kill_shell.`)
+    }
+
+    if (background) {
+      // Give it a moment, so an immediate failure (a typo, a port in use) is seen now.
+      setTimeout(() => { if (!finished) leave('started') }, 1500)
+    }
+
+    const watch = setInterval(() => {
+      if (background) return
+      const quiet = Date.now() - lastOutput
+      if (READY.test(out) && quiet > SERVER_QUIET) leave('it looks like a server that is up')
+      else if (Date.now() - started > limit) leave(`still running after ${Math.round(limit / 1000)}s`)
+    }, 500)
+
+    child.on('close', (code, sig) => {
+      const note = followCwd(session, marker)
+      const status = code === null ? `killed (${sig})` : `exit ${code}`
+      const benign = code === 1 && BENIGN.test(command) ? ' (for this command 1 means "no match" or "differs" — not an error)' : ''
+      const refused = boxed && code !== 0 ? sandboxing.note(out, boxed) : ''
+      finish(`${status}${benign}\n${shown(out)}${note}${refused}`)
+    })
+    child.on('error', (err) => { dropMarker(marker); finish(`could not run it: ${err.message}`) })
+  })
+}
+
+module.exports = { powershellPath, startMonitor, setExtraEnv, runCommand, bashOutput, killShell, stopBackground, taskList, isReadOnly, readsOutside, plain, commandEnv, shown, tasks }

package/ext/storage.js

@@ -0,0 +1,80 @@
+'use strict'
+// Firebase Storage over its REST API (the same one the SDK uses), for the extension and the CLI:
+// the media a conversation generated, and files attached to it, kept with the account under
+// users/{uid}/media/. The caller's ID token decides what may be touched (storage.rules).
+// With `emulator` ("127.0.0.1:9399") it talks to the local emulator. No VS Code here.
+
+class Storage {
+  constructor({ bucket, getToken, emulator = null, fetchImpl = globalThis.fetch }) {
+    this.bucket = bucket
+    this.getToken = getToken
+    this.fetch = fetchImpl
+    this.base = emulator ? `http://${emulator}/v0/b/${bucket}/o` : `https://firebasestorage.googleapis.com/v0/b/${bucket}/o`
+  }
+
+  async headers(extra = {}) {
+    const token = await this.getToken()
+    return token ? { ...extra, Authorization: `Firebase ${token}` } : extra
+  }
+
+  async check(response) {
+    if (response.ok) return response
+    const data = await response.json().catch(() => ({}))
+    const err = new Error(data?.error?.message || (response.status === 403 ? 'permission denied' : `Storage answered ${response.status}`))
+    err.status = response.status
+    throw err
+  }
+
+  /** Stores bytes at `path` ("users/u/media/a.png"). Resolves to the object's metadata. A multipart
+   *  upload, as the SDK's: the type goes in the object's metadata, where the rules read it. */
+  async upload(path, bytes, contentType) {
+    const boundary = `aipictury-${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`
+    const body = Buffer.concat([
+      Buffer.from(`--${boundary}\r\nContent-Type: application/json; charset=utf-8\r\n\r\n${JSON.stringify({ name: path, contentType })}\r\n`
+        + `--${boundary}\r\nContent-Type: ${contentType}\r\n\r\n`),
+      Buffer.from(bytes),
+      Buffer.from(`\r\n--${boundary}--`),
+    ])
+    const r = await this.fetch(`${this.base}?uploadType=multipart&name=${encodeURIComponent(path)}`, {
+      method: 'POST', headers: await this.headers({ 'Content-Type': `multipart/related; boundary=${boundary}`, 'X-Goog-Upload-Protocol': 'multipart' }),
+      body, signal: AbortSignal.timeout(10 * 60_000),
+    })
+    return (await this.check(r)).json()
+  }
+
+  /** The object's bytes, or null when there is none. */
+  async download(path) {
+    const r = await this.fetch(`${this.base}/${encodeURIComponent(path)}?alt=media`, { headers: await this.headers(), signal: AbortSignal.timeout(10 * 60_000) })
+    if (r.status === 404) return null
+    return Buffer.from(await (await this.check(r)).arrayBuffer())
+  }
+
+  /** Its metadata ({ size, contentType, … }), or null. */
+  async stat(path) {
+    const r = await this.fetch(`${this.base}/${encodeURIComponent(path)}`, { headers: await this.headers(), signal: AbortSignal.timeout(30_000) })
+    if (r.status === 404) return null
+    return (await this.check(r)).json()
+  }
+
+  async delete(path) {
+    const r = await this.fetch(`${this.base}/${encodeURIComponent(path)}`, { method: 'DELETE', headers: await this.headers(), signal: AbortSignal.timeout(30_000) })
+    if (r.status === 404) return
+    await this.check(r)
+  }
+
+  /** Every object under a prefix: [{ name, size, contentType }]. */
+  async list(prefix) {
+    const out = []
+    let token = ''
+    do {
+      const r = await this.fetch(`${this.base}?prefix=${encodeURIComponent(prefix)}${token ? `&pageToken=${encodeURIComponent(token)}` : ''}`,
+        { headers: await this.headers(), signal: AbortSignal.timeout(30_000) })
+      const data = await (await this.check(r)).json()
+      for (const i of data.items || []) out.push({ name: i.name, size: Number(i.size), contentType: i.contentType })
+      token = data.nextPageToken || ''
+    } while (token)
+    return out
+  }
+}
+
+module.exports = { Storage }

package/ext/tasklist.js

@@ -0,0 +1,112 @@
+'use strict'
+// The agent's task list with dependencies, as Claude Code's task tools keep it: tasks with an
+// id, a subject, a status, and the tasks they wait for. A task cannot start while one it waits
+// for is unfinished; finishing it says which tasks are now free. The same list as todo_write's
+// (that tool stays as the shortcut: the whole list at once), shown in the panel.
+const STATUSES = ['pending', 'in_progress', 'completed']
+const MAX = 50
+
+const label = (t) => `#${t.id} ${t.content}`
+const nextId = (list) => String(Math.max(0, ...list.map((t) => Number(t.id) || 0)) + 1)
+const find = (list, id) => list.find((t) => t.id === String(id).replace(/^#/, ''))
+
+/** The unfinished tasks `task` waits for. */
+function waitingOn(list, task) {
+  return (task.blockedBy || []).map((id) => find(list, id)).filter((t) => t && t.status !== 'completed')
+}
+
+/** Would `from` waiting for `to` close a loop (to already waits, through others, for from)? */
+function loops(list, from, to) {
+  const seen = new Set()
+  const walk = (id) => {
+    if (id === from) return true
+    if (seen.has(id)) return false
+    seen.add(id)
+    return (find(list, id)?.blockedBy || []).some(walk)
+  }
+  return walk(to)
+}
+
+function addWait(list, task, ids) {
+  for (const raw of ids || []) {
+    const other = find(list, raw)
+    if (!other) throw new Error(`there is no task #${String(raw).replace(/^#/, '')}`)
+    if (other.id === task.id) throw new Error('a task cannot wait for itself')
+    if (loops(list, task.id, other.id)) throw new Error(`#${task.id} waiting for #${other.id} would be a loop: #${other.id} already waits for #${task.id}`)
+    task.blockedBy = [...new Set([...(task.blockedBy || []), other.id])]
+  }
+}
+
+/** task_create: a new pending task. Returns { list, task }. */
+function create(list, args = {}) {
+  const content = String(args.subject || args.content || '').trim()
+  if (!content) throw new Error('a task needs a subject')
+  if (list.length >= MAX) throw new Error(`at most ${MAX} tasks — finish or delete some first`)
+  const task = { id: nextId(list), content, status: 'pending', description: String(args.description || '').trim() || undefined,
+    activeForm: String(args.activeForm || '').trim() || undefined, blockedBy: [] }
+  const out = [...list.map((t) => ({ ...t })), task]
+  addWait(out, task, args.blockedBy || args.addBlockedBy)
+  return { list: out, task }
+}
+
+/** task_update: change a task. Returns { list, task, freed } — the tasks its completion freed. */
+function update(list, args = {}) {
+  const out = list.map((t) => ({ ...t, blockedBy: [...(t.blockedBy || [])] }))
+  const task = find(out, args.taskId ?? args.id)
+  if (!task) throw new Error(`there is no task #${String(args.taskId ?? args.id ?? '').replace(/^#/, '')}`)
+  if (args.status === 'deleted') {
+    const rest = out.filter((t) => t !== task)
+    for (const t of rest) t.blockedBy = t.blockedBy.filter((id) => id !== task.id)
+    return { list: rest, task, freed: [] }
+  }
+  if (args.subject) task.content = String(args.subject).trim()
+  if (args.description !== undefined) task.description = String(args.description).trim() || undefined
+  if (args.activeForm !== undefined) task.activeForm = String(args.activeForm).trim() || undefined
+  if (args.owner !== undefined) task.owner = String(args.owner).trim() || undefined
+  addWait(out, task, args.addBlockedBy)
+  for (const id of args.addBlocks || []) {
+    const other = find(out, id)
+    if (!other) throw new Error(`there is no task #${String(id).replace(/^#/, '')}`)
+    addWait(out, other, [task.id])
+  }
+  let freed = []
+  if (args.status) {
+    if (!STATUSES.includes(args.status)) throw new Error(`a status is ${STATUSES.join(', ')} or deleted`)
+    const waits = waitingOn(out, task)
+    if (args.status === 'in_progress' && waits.length) throw new Error(`#${task.id} cannot start yet: it waits for ${waits.map(label).join(', ')}`)
+    const was = task.status
+    task.status = args.status
+    if (args.status === 'completed' && was !== 'completed') {
+      freed = out.filter((t) => t.status === 'pending' && t.blockedBy.includes(task.id) && !waitingOn(out, t).length)
+    }
+  }
+  return { list: out, task, freed }
+}
+
+/** task_list: every task, with what it waits for. */
+function summary(list) {
+  if (!list.length) return 'No tasks yet.'
+  const done = list.filter((t) => t.status === 'completed').length
+  return [`${done}/${list.length} done.`, ...list.map((t) => {
+    const waits = waitingOn(list, t)
+    return `${t.status === 'completed' ? '[x]' : t.status === 'in_progress' ? '[~]' : '[ ]'} ${label(t)}${t.owner ? ` (${t.owner})` : ''}`
+      + `${waits.length ? ` — waits for ${waits.map((w) => `#${w.id}`).join(', ')}` : ''}`
+  })].join('\n')
+}
+
+/** task_get: one task in full. */
+function detail(list, id) {
+  const t = find(list, id)
+  if (!t) throw new Error(`there is no task #${String(id).replace(/^#/, '')}`)
+  const waits = waitingOn(list, t)
+  const blocks = list.filter((o) => o.blockedBy?.includes(t.id))
+  return [`${label(t)} — ${t.status}`, t.description, waits.length ? `Waits for: ${waits.map(label).join(', ')}` : '',
+    blocks.length ? `Others wait for it: ${blocks.map(label).join(', ')}` : ''].filter(Boolean).join('\n')
+}
+
+/** todo_write's list given ids, so the task tools can carry on from it. */
+function fromTodos(todos) {
+  return todos.map((t, i) => ({ ...t, id: t.id || String(i + 1), blockedBy: t.blockedBy || [] }))
+}
+
+module.exports = { create, update, summary, detail, fromTodos, waitingOn, STATUSES }

package/ext/text.js

@@ -0,0 +1,31 @@
+'use strict'
+// Text helpers that must never produce something a JSON parser rejects.
+
+/** `s.slice(start, end)` that never cuts an emoji or other astral character in half. A
+ *  lone surrogate is invalid UTF-8: the server refused a whole conversation over one
+ *  (Claude Code met the same: "surrogates not allowed"). */
+function safeSlice(s, start = 0, end = undefined) {
+  const t = String(s)
+  let a = start < 0 ? Math.max(0, t.length + start) : Math.min(start, t.length)
+  let b = end === undefined ? t.length : end < 0 ? Math.max(0, t.length + end) : Math.min(end, t.length)
+  const low = (i) => { const c = t.charCodeAt(i); return c >= 0xdc00 && c <= 0xdfff }
+  if (a > 0 && a < t.length && low(a)) a += 1
+  if (b > 0 && b < t.length && low(b)) b -= 1
+  return t.slice(a, Math.max(a, b))
+}
+
+/** Removes lone surrogates anywhere in a string (text from a process can have them). */
+const wellFormed = (s) => String(s).replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '�')
+
+// Characters that do not show but change what text means: zero-width spaces and joiners,
+// bidirectional overrides (the "Trojan Source" trick), the BOM, tag characters. Claude Code
+// strips them from what is pasted and sent; so do we, and says how many. The zero-width
+// joiner stays: emoji families and flags are built with it.
+const INVISIBLE = /[\u200B\u200C\u2060-\u2064\u2066-\u2069\u202A-\u202E\u200E\u200F\uFEFF\u00AD\u180E]|[\u{E0000}-\u{E007F}]/gu
+function stripInvisible(s) {
+  const t = String(s)
+  const removed = (t.match(INVISIBLE) || []).length
+  return { text: removed ? t.replace(INVISIBLE, '') : t, removed }
+}
+
+module.exports = { safeSlice, wellFormed, stripInvisible, INVISIBLE }