picocode-core 0.9.119

package/README.md

@@ -0,0 +1,15 @@
+# picocode-core
+
+The runtime behind [pico](https://github.com/nvms/pico). It contains everything except rendering: session event logs and their derived state, the agent turn loop, the tool registry, background shells, subagents and deliberation, MCP client support, memories, skills and commands, compaction, rewind, steering, scheduled wake-ups, model catalog and Codex OAuth.
+
+The session driver lives in `controller.js`. `createController({ boot })` owns the conversation state (session log, derived transcript, model, effort, queue, live turn overlay) and exposes methods such as `send`, `interrupt`, `compact`, `resume`, `fork`, `rewind`, `switchModel`, and `sendParallel`, emitting `change`, `flash`, `derived`, `question`, `session`, and `project` events for a frontend to render. The terminal client in `packages/pico` is one consumer.
+
+Modules are imported by path:
+
+```js
+import { runTurn } from 'picocode-core/agent.js'
+import { deriveState } from 'picocode-core/derive.js'
+import { createToolset } from 'picocode-core/tools/index.js'
+```
+
+Model access goes through [@prsm/ai](https://github.com/prsmjs/ai). The package is plain ESM and requires Node 24 or newer.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "picocode-core",
+  "version": "0.9.119",
+  "description": "The agent runtime behind pico: sessions, tools, subagents, MCP, memory, and model access",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nvms/pico.git",
+    "directory": "packages/core"
+  },
+  "exports": {
+    "./*": "./src/*"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'",
+    "snapshot": "node scripts/snapshot-catalog.js",
+    "prepublishOnly": "node scripts/snapshot-catalog.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@prsm/ai": "^1.6.1",
+    "diff": "^7.0.0",
+    "fast-glob": "^3.3.0",
+    "proper-lockfile": "^4.1.2"
+  }
+}

package/src/agent-transcript.js

@@ -0,0 +1,80 @@
+import { defaultTitle } from './tools/recorder.js'
+
+function parseCallArgs(call) {
+  try {
+    return typeof call.function?.arguments === 'string'
+      ? JSON.parse(call.function.arguments)
+      : call.function?.arguments || {}
+  } catch {
+    return {}
+  }
+}
+
+function toolItem(call, startedAt) {
+  const args = parseCallArgs(call)
+  const name = call.function?.name || 'tool'
+  return {
+    kind: 'tool',
+    callId: call.id,
+    name,
+    args,
+    description: args.description,
+    title: defaultTitle(name, args),
+    status: 'running',
+    startedAt,
+  }
+}
+
+function settleTool(tools, event) {
+  const item = tools.get(event.call?.id)
+  if (!item) return
+  item.status = event.type === 'tool_error' ? 'error' : 'done'
+  item.error = event.error ? String(event.error) : null
+  item.fullOutput = event.result === undefined ? null : typeof event.result === 'string' ? event.result : JSON.stringify(event.result, null, 2)
+}
+
+function deliberationTranscript(agent) {
+  const items = [{ kind: 'user', text: agent.prompt }]
+  const tools = new Map()
+  for (const entry of agent.timeline) {
+    if (entry.kind === 'turn') {
+      const turn = entry.value
+      items.push({ kind: 'deliberation-turn', role: turn.role, round: turn.round, text: turn.text })
+      continue
+    }
+    const event = entry.value
+    if (event.type === 'tool_executing') {
+      const item = toolItem(event.call || {}, event.at)
+      tools.set(item.callId, item)
+      items.push(item)
+    }
+    if (event.type === 'tool_complete' || event.type === 'tool_error') settleTool(tools, event)
+  }
+  if (agent.result) {
+    items.push({ kind: 'deliberation-turn', role: 'synthesis', text: agent.result, interrupted: agent.status === 'cancelled' })
+  } else if (agent.error) {
+    items.push({ kind: 'assistant', text: agent.error, interrupted: true })
+  }
+  return items
+}
+
+export function agentTranscript(agent) {
+  if (!agent) return []
+  if (agent.role === 'deliberation') return deliberationTranscript(agent)
+  const items = [{ kind: 'user', text: agent.prompt }]
+  const tools = new Map()
+  let response = ''
+  for (const event of agent.events) {
+    if (event.type === 'content') response += event.content
+    if (event.type === 'tool_executing') {
+      const item = toolItem(event.call || {}, event.at || agent.updatedAt)
+      tools.set(item.callId, item)
+      items.push(item)
+    }
+    if (event.type === 'tool_complete' || event.type === 'tool_error') settleTool(tools, event)
+  }
+  const text = agent.result || response
+  if (text) items.push({ kind: 'assistant', text, interrupted: agent.status === 'cancelled' })
+  else if (agent.error) items.push({ kind: 'assistant', text: agent.error, interrupted: true })
+  return items
+}

package/src/agent.js

@@ -0,0 +1,170 @@
+import { readFile } from 'node:fs/promises'
+import { compose, scope, model, noToolsCalled, Inherit, getText } from '@prsm/ai'
+
+async function hydratePart(part) {
+  if (part.type !== 'image' || part.source?.kind !== 'path') return part
+  try {
+    const data = await readFile(part.source.path)
+    return {
+      type: 'image',
+      source: { kind: 'base64', mediaType: part.source.mediaType, data: data.toString('base64') },
+    }
+  } catch {
+    return { type: 'text', text: `[image unavailable: ${part.source.path}]` }
+  }
+}
+
+export function hydrateImages(history) {
+  return Promise.all(
+    history.map(async (message) =>
+      Array.isArray(message.content)
+        ? { ...message, content: await Promise.all(message.content.map(hydratePart)) }
+        : message,
+    ),
+  )
+}
+
+// reasoning models with large contexts can sit minutes before the first
+// output token; this guards against truly dead streams, not slow ones
+const STALL_MS = 300000
+
+export function compactionHistory(history, prompt) {
+  return hydrateImages([...history.filter((m) => m.role !== 'system'), { role: 'user', content: prompt }])
+}
+
+export async function compactHistory({ history, modelName, auth, prompt, signal, onStream }) {
+  const out = await compose(
+    model({
+      model: modelName,
+      ...(auth?.apiKey && { apiKey: auth.apiKey }),
+      ...(auth?.headers && { headers: auth.headers }),
+    }),
+  )({
+    history: await compactionHistory(history, prompt),
+    tools: [],
+    abortSignal: signal,
+    ...(onStream && { stream: onStream }),
+  })
+  if (signal?.aborted) throw new Error('compaction cancelled')
+  return getText(out.lastResponse?.content || '').trim()
+}
+
+// the summary has a fixed shape: an <analysis> scratchpad, then 8 numbered
+// sections; watching headers stream by is real progress, not an estimate
+export function compactProgress(streamed) {
+  const chars = streamed.length
+  const afterAnalysis = streamed.split('</analysis>')[1] ?? streamed.split('<summary>')[1]
+  if (afterAnalysis === undefined) return { phase: 'analyzing', section: 0, chars }
+  const sections = (afterAnalysis.match(/^\s*\d+\.\s/gm) || []).length
+  if (sections === 0) return { phase: 'analyzing', section: 0, chars }
+  return { phase: 'writing', section: Math.min(8, sections), chars }
+}
+
+export async function summarizeText({ text, modelName, auth }) {
+  const out = await compose(
+    model({
+      model: modelName,
+      system: 'Summarize the following conversation excerpt in 2-4 dense sentences. Capture decisions, changes made, and open questions. Output only the summary.',
+      ...(auth?.apiKey && { apiKey: auth.apiKey }),
+      ...(auth?.headers && { headers: auth.headers }),
+    }),
+  )(text.slice(0, 30000))
+  return getText(out.lastResponse?.content || '').trim()
+}
+
+export async function runTurn({ history, tools, recorder, modelName, effort, auth, system, signal, onStream, stallMs = STALL_MS }) {
+  const collected = []
+  let roundText = ''
+  let usageSeen = null
+  let stalled = false
+  // usage events carry cumulative totals per request round, so consecutive
+  // deltas recover each round's true input size; the last delta is the size
+  // of the current context as actually sent
+  let cumulativePrompt = 0
+  let lastPromptTokens = 0
+
+  const internal = new AbortController()
+  const onUserAbort = () => internal.abort()
+  if (signal?.aborted) internal.abort()
+  else signal?.addEventListener('abort', onUserAbort, { once: true })
+
+  let watchdog = null
+  const arm = () => {
+    clearTimeout(watchdog)
+    watchdog = setTimeout(() => {
+      stalled = true
+      internal.abort()
+    }, stallMs)
+  }
+
+  const stream = (event) => {
+    if (event.type === 'tool_executing') {
+      // a tool may legitimately run for minutes (test suites, slow fetches)
+      // and emits nothing while it does; the watchdog guards the provider
+      // stream, so pause it until the tool finishes. tools carry their own
+      // timeouts (bash 120s default, web tools via dredge)
+      clearTimeout(watchdog)
+      recorder.currentCall = event.call
+      onStream?.(event)
+      return
+    }
+    arm()
+    if (event.type === 'content') {
+      roundText += event.content
+    } else if (event.type === 'tool_calls_ready') {
+      collected.push({ role: 'assistant', content: roundText, tool_calls: event.calls })
+      roundText = ''
+    } else if (event.type === 'tool_complete') {
+      collected.push({ role: 'tool', tool_call_id: event.call.id, content: JSON.stringify(event.result) })
+    } else if (event.type === 'tool_error') {
+      collected.push({ role: 'tool', tool_call_id: event.call.id, content: JSON.stringify({ error: event.error }) })
+    } else if (event.type === 'usage') {
+      usageSeen = event.usage
+      const prompt = event.usage?.promptTokens || 0
+      lastPromptTokens = Math.max(0, prompt - cumulativePrompt)
+      cumulativePrompt = prompt
+    }
+    onStream?.(event)
+  }
+
+  const base = history.length
+  const step = compose(
+    scope(
+      { inherit: Inherit.Conversation, system, tools, until: noToolsCalled(), stream },
+      (ctx) =>
+        model({
+          model: modelName,
+          ...(effort && { effort }),
+          ...(auth?.apiKey && { apiKey: auth.apiKey }),
+          ...(auth?.headers && { headers: auth.headers }),
+        })({ ...ctx, abortSignal: internal.signal }),
+    ),
+  )
+
+  const partialMessages = () => {
+    const messages = [...collected]
+    if (roundText) messages.push({ role: 'assistant', content: roundText })
+    return messages
+  }
+
+  arm()
+  try {
+    const out = await step({ history: await hydrateImages(history), tools: [] })
+    const interrupted = !!signal?.aborted || stalled
+    if (interrupted) {
+      return { messages: partialMessages(), usage: usageSeen, lastPromptTokens, interrupted, stalled }
+    }
+    const messages = out.history.filter((m) => m.role !== 'system').slice(base)
+    return { messages, usage: out.usage || null, lastPromptTokens, interrupted: false, stalled: false }
+  } catch (err) {
+    if (err.name === 'AbortError' || internal.signal.aborted) {
+      return { messages: partialMessages(), usage: usageSeen, lastPromptTokens, interrupted: true, stalled }
+    }
+    // a provider error mid-turn must not discard the rounds that already
+    // ran: tools mutated the world, so the record has to survive
+    return { messages: partialMessages(), usage: usageSeen, lastPromptTokens, interrupted: true, stalled: false, error: String(err.message || err) }
+  } finally {
+    clearTimeout(watchdog)
+    signal?.removeEventListener('abort', onUserAbort)
+  }
+}

package/src/agents.js

@@ -0,0 +1,213 @@
+import { getText } from '@prsm/ai'
+
+export function resultText(messages = []) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'assistant') {
+      const text = getText(messages[i].content || '').trim()
+      if (text) return text
+    }
+  }
+  return ''
+}
+
+function restoredAgent(data, at) {
+  return {
+    id: String(data.agentId),
+    description: data.description || data.prompt?.slice(0, 80) || `agent ${data.agentId}`,
+    prompt: data.prompt || '',
+    model: data.model || null,
+    role: data.role || 'worker',
+    parentId: data.parentId || null,
+    sessionId: data.sessionId || null,
+    sessionFile: data.sessionFile || null,
+    tools: data.tools || [],
+    status: 'cancelled',
+    createdAt: at,
+    updatedAt: at,
+    startedAt: at,
+    endedAt: at,
+    events: [],
+    result: '',
+    error: null,
+    usage: null,
+    options: data,
+  }
+}
+
+export function reduceAgentEvents(events = []) {
+  const agents = new Map()
+  for (const record of events) {
+    const data = record.data || {}
+    const id = String(data.agentId || '')
+    if (!id) continue
+    if (record.type === 'agent_start') {
+      agents.set(id, restoredAgent(data, record.at))
+      continue
+    }
+    if (record.type === 'agent_dismiss') {
+      agents.delete(id)
+      continue
+    }
+    const agent = agents.get(id)
+    if (!agent) continue
+    if (record.type === 'agent_event') {
+      agent.events.push(data.event)
+      agent.updatedAt = record.at
+      if (data.event?.type === 'usage') agent.usage = data.event.usage
+    } else if (record.type === 'agent_result') {
+      agent.result = data.result || resultText(data.messages)
+      agent.usage = data.usage || agent.usage
+      agent.error = data.error || null
+      agent.status = data.error ? 'failed' : data.interrupted ? 'cancelled' : 'completed'
+      agent.updatedAt = record.at
+      agent.endedAt = record.at
+    }
+  }
+  const restored = [...agents.values()]
+  for (const agent of restored) {
+    agent.done = Promise.resolve(agent)
+    agent.resolve = () => {}
+  }
+  return restored
+}
+
+export function createAgentManager({ run, concurrency = 8, onChange = () => {}, onCreate = () => {}, onEvent = () => {}, onFinish = () => {}, defaults = () => ({}) } = {}) {
+  const agents = new Map()
+  const queue = []
+  let nextId = 1
+  let active = 0
+  let generation = 0
+
+  const changed = () => onChange()
+
+  function pump() {
+    while (active < concurrency && queue.length) {
+      const agent = queue.shift()
+      if (agent.status !== 'queued') continue
+      agent.status = 'running'
+      agent.startedAt = Date.now()
+      agent.generation = generation
+      active++
+      changed()
+      Promise.resolve().then(() => run(agent, agent.controller.signal, (event) => {
+        if (agent.generation !== generation) return
+        agent.events.push(event)
+        if (event.type === 'usage') agent.usage = event.usage
+        agent.updatedAt = Date.now()
+        onEvent(agent, event)
+        changed()
+      })).then((result) => {
+        if (agent.generation !== generation) return
+        agent.result = typeof result === 'string' ? result : resultText(result?.messages)
+        agent.usage = result?.usage || agent.usage
+        agent.error = result?.error || null
+        agent.status = agent.error ? 'failed' : result?.interrupted ? 'cancelled' : 'completed'
+      }).catch((error) => {
+        if (agent.generation !== generation) return
+        agent.error = String(error?.message || error)
+        agent.status = agent.controller.signal.aborted ? 'cancelled' : 'failed'
+      }).finally(() => {
+        if (agent.generation !== generation) return agent.resolve(agent)
+        agent.endedAt = Date.now()
+        active--
+        onFinish(agent)
+        changed()
+        agent.resolve(agent)
+        pump()
+      })
+    }
+  }
+
+  function start(options) {
+    options = { ...defaults(), ...options }
+    const id = String(nextId++)
+    let resolve
+    const done = new Promise((r) => { resolve = r })
+    if (!options.prompt?.trim()) throw new Error('agent prompt is required')
+    const agent = {
+      id,
+      description: options.description || options.prompt.slice(0, 80),
+      prompt: options.prompt,
+      model: options.model,
+      role: options.role || 'worker',
+      parentId: options.parentId || null,
+      sessionId: options.sessionId || null,
+      sessionFile: options.sessionFile || null,
+      tools: options.tools || [],
+      status: 'queued',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      startedAt: null,
+      endedAt: null,
+      events: [],
+      result: '',
+      error: null,
+      usage: null,
+      controller: new AbortController(),
+      resolve,
+      done,
+      options,
+    }
+    agents.set(id, agent)
+    onCreate(agent)
+    queue.push(agent)
+    changed()
+    pump()
+    return agent
+  }
+
+  function restore(events) {
+    generation++
+    for (const agent of agents.values()) {
+      if (agent.status === 'queued') agent.resolve(agent)
+      else if (agent.status === 'running') agent.controller.abort()
+    }
+    agents.clear()
+    queue.length = 0
+    active = 0
+    let maxId = 0
+    for (const agent of reduceAgentEvents(events)) {
+      agents.set(agent.id, agent)
+      maxId = Math.max(maxId, Number(agent.id) || 0)
+    }
+    nextId = maxId + 1
+    changed()
+  }
+
+  return {
+    start,
+    restore,
+    clear: () => restore([]),
+    get: (id) => agents.get(String(id)) || null,
+    list: () => [...agents.values()].sort((a, b) => Number(b.id) - Number(a.id)),
+    collect: async (ids) => {
+      const selected = await Promise.all(ids.map((id) => agents.get(String(id))?.done).filter(Boolean))
+      const at = Date.now()
+      for (const agent of selected) agent.collectedAt = at
+      changed()
+      return selected
+    },
+    dismiss(id) {
+      const agent = agents.get(String(id))
+      if (!agent || ['queued', 'running'].includes(agent.status)) return false
+      agents.delete(String(id))
+      changed()
+      return true
+    },
+    cancel(id) {
+      const agent = agents.get(String(id))
+      if (!agent || ['completed', 'failed', 'cancelled'].includes(agent.status)) return false
+      if (agent.status === 'queued') {
+        agent.status = 'cancelled'
+        agent.endedAt = Date.now()
+        onFinish(agent)
+        agent.resolve(agent)
+        changed()
+      } else agent.controller.abort()
+      return true
+    },
+    cancelAll() {
+      for (const agent of agents.values()) this.cancel(agent.id)
+    },
+  }
+}

package/src/attachments.js

@@ -0,0 +1,141 @@
+import { existsSync } from 'node:fs'
+import { basename } from 'node:path'
+
+const MEDIA_TYPES = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+}
+
+export function mediaTypeFor(path) {
+  return MEDIA_TYPES[path.split('.').pop().toLowerCase()] || null
+}
+
+function unquote(token) {
+  if (/^'.*'$/.test(token) || /^".*"$/.test(token)) return token.slice(1, -1)
+  return token.replace(/\\ /g, ' ')
+}
+
+function toPath(token) {
+  const raw = unquote(token.trim())
+  if (raw.startsWith('file://')) {
+    try {
+      return decodeURIComponent(raw.slice('file://'.length))
+    } catch {
+      return null
+    }
+  }
+  return raw
+}
+
+export function extractImagePaths(text, exists = existsSync) {
+  const tokens = text.trim().match(/'[^']*'|"[^"]*"|(?:\\ |[^ \t\n\r])+/g)
+  if (!tokens || tokens.length === 0) return []
+  const paths = []
+  for (const token of tokens) {
+    const path = toPath(token)
+    if (!path || !path.startsWith('/')) return []
+    if (!mediaTypeFor(path) || !exists(path)) return []
+    paths.push(path)
+  }
+  return paths
+}
+
+export function imageLabel(part) {
+  if (part.source?.path) return `[image: ${basename(part.source.path)}]`
+  return '[image]'
+}
+
+const IMAGE_PATH_RE = /(["'])(\/[^"']+?\.(?:png|jpe?g|gif|webp|bmp))\1|(\/(?:\\ |[^ \t\n\r"'])+\.(?:png|jpe?g|gif|webp|bmp))/gi
+
+export function splitTextByImagePaths(text, exists = existsSync) {
+  const parts = []
+  let last = 0
+  for (const match of text.matchAll(IMAGE_PATH_RE)) {
+    const path = match[2] || match[3].replace(/\\ /g, ' ')
+    const mediaType = mediaTypeFor(path)
+    if (!mediaType || !exists(path)) continue
+    if (match.index > last) parts.push({ type: 'text', text: text.slice(last, match.index) })
+    parts.push({ type: 'image', source: { kind: 'path', path, mediaType } })
+    last = match.index + match[0].length
+  }
+  if (parts.length === 0) return null
+  const tail = text.slice(last)
+  if (tail) parts.push({ type: 'text', text: tail })
+  return parts
+}
+
+export function buildUserContent(text, attachments) {
+  const parts = []
+  let last = 0
+  const used = []
+  for (const match of text.matchAll(/\[Image #\d+\]/g)) {
+    const attachment = attachments.get(match[0])
+    if (!attachment) continue
+    const before = text.slice(last, match.index)
+    if (before) parts.push({ type: 'text', text: before })
+    parts.push({
+      type: 'image',
+      source: { kind: 'path', path: attachment.path, mediaType: attachment.mediaType },
+    })
+    used.push(match[0])
+    last = match.index + match[0].length
+  }
+  if (parts.length === 0) return { content: text, used }
+  const tail = text.slice(last)
+  if (tail) parts.push({ type: 'text', text: tail })
+  return { content: parts, used }
+}
+
+export function placeholderizeImagePaths(text, { attachments, nextId, exists = existsSync }) {
+  const parts = splitTextByImagePaths(text, exists)
+  if (!parts) return { text, changed: false }
+  let out = ''
+  for (const part of parts) {
+    if (part.type === 'text') {
+      out += part.text
+    } else {
+      const placeholder = `[Image #${nextId()}]`
+      attachments.set(placeholder, { path: part.source.path, mediaType: part.source.mediaType })
+      out += placeholder
+    }
+  }
+  return { text: out, changed: true }
+}
+
+export function inputTextFromContent(content, { attachments, nextId }) {
+  if (!Array.isArray(content)) return String(content)
+  let out = ''
+  for (const part of content) {
+    if (part.type === 'text') {
+      out += part.text
+    } else if (part.type === 'image' && part.source?.path) {
+      const placeholder = `[Image #${nextId()}]`
+      attachments.set(placeholder, { path: part.source.path, mediaType: part.source.mediaType })
+      out += placeholder
+    } else {
+      out += '[image]'
+    }
+  }
+  return out
+}
+
+export function finalizeUserContent(text, attachments, exists = existsSync) {
+  const { content, used } = buildUserContent(text, attachments)
+  const parts = Array.isArray(content) ? content : [{ type: 'text', text: content }]
+  const expanded = []
+  for (const part of parts) {
+    if (part.type !== 'text') {
+      expanded.push(part)
+      continue
+    }
+    const split = splitTextByImagePaths(part.text, exists)
+    if (split) expanded.push(...split)
+    else expanded.push(part)
+  }
+  if (expanded.length === 1 && expanded[0].type === 'text') return { content: expanded[0].text, used }
+  return { content: expanded, used }
+}

package/src/boot.js

@@ -0,0 +1,28 @@
+import { homedir } from 'node:os'
+import { findProjectRoot } from './paths.js'
+import { loadStartupContext, createContextTracker } from './context.js'
+import { createSkillIndex } from './skills.js'
+import { createCommandIndex } from './commands.js'
+import { createMcpRuntime } from './mcp.js'
+import { createMemory } from './memory.js'
+
+export async function buildProjectBoot(cwd, { onMcpChange = () => {} } = {}) {
+  const home = homedir()
+  const root = findProjectRoot(cwd)
+  const startupContext = loadStartupContext(cwd)
+  const tracker = createContextTracker({
+    stopDir: startupContext.stopDir,
+    loaded: new Set(startupContext.files.map((f) => f.path)),
+  })
+  return {
+    cwd,
+    root,
+    displayCwd: cwd.startsWith(home) ? cwd.replace(home, '~') : cwd,
+    startupContext,
+    tracker,
+    skills: await createSkillIndex(root),
+    commands: await createCommandIndex(root),
+    mcp: await createMcpRuntime({ root, onChange: onMcpChange }),
+    memory: createMemory(root),
+  }
+}