picocode-core 0.9.119

package/src/skills.js

@@ -0,0 +1,164 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { globalSkillsDir, projectSkillsDir } from './paths.js'
+
+export function parseFrontmatter(text) {
+  const match = text.match(/^---\n([\s\S]*?)\n---\n?/)
+  if (!match) return { meta: {}, body: text }
+  const meta = {}
+  for (const line of match[1].split('\n')) {
+    const sep = line.indexOf(':')
+    if (sep === -1) continue
+    meta[line.slice(0, sep).trim()] = line.slice(sep + 1).trim()
+  }
+  return { meta, body: text.slice(match[0].length) }
+}
+
+async function scanDir(dir, source) {
+  let names = []
+  try {
+    names = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const skills = []
+  for (const entry of names) {
+    if (!entry.isDirectory()) continue
+    const file = join(dir, entry.name, 'SKILL.md')
+    try {
+      const { meta } = parseFrontmatter(await readFile(file, 'utf-8'))
+      skills.push({
+        name: meta.name || entry.name,
+        description: meta.description || '',
+        source,
+        file,
+      })
+    } catch {}
+  }
+  return skills
+}
+
+const ASK_RULE = `Before writing anything, resolve ambiguity:
+- If the user did not say global or project, ask exactly one question: "global (available everywhere) or just this project?" Do not guess silently.
+- If the behavior or output is underspecified, state the assumptions you are making in one short line before proceeding, so the user can correct you.`
+
+const NEW_TOOL_SKILL = `Create a custom pico tool from the user's description.
+
+${ASK_RULE}
+
+A pico tool is an ES module whose default export is either a tool object or a factory
+\`(context) => tool\` where context is \`{ cwd, root }\`. The tool object shape:
+
+\`\`\`js
+export default {
+  name: 'word_count',
+  description: 'Count words, lines, and characters in a file',
+  schema: {
+    path: { type: 'string', description: 'file path relative to the working directory' },
+    words: { type: 'boolean', description: 'include word count', optional: true },
+  },
+  execute: async ({ path, words = true }) => {
+    // return any JSON-serializable value; throw an Error to report failure
+    return { path, words: 42 }
+  },
+}
+\`\`\`
+
+Schema properties support: type (string, number, boolean, array, object), description,
+optional, enum (string values), items (for arrays), properties (for nested objects).
+
+Locations: \`.pico/tools/<name>.js\` in the project root for project tools,
+\`~/.pico/tools/<name>.js\` for tools available everywhere. Default to the project unless
+the user asks for a global tool. Node builtins can be imported; npm packages cannot be
+assumed. Tools are rescanned every turn, so a new or edited tool is usable on the next
+message with no restart.
+
+Steps:
+1. Decide the tool name (snake_case), inputs, and output shape from the user's request.
+2. Write the module to the right location with the write tool.
+3. Sanity-check it loads: \`node --input-type=module -e "const t = (await import('file://<abs path>')).default; console.log(t.name)"\` (adjust if the export is a factory).
+4. Tell the user the tool is ready and will be available from their next message.`
+
+const NEW_SKILL_SKILL = `Create a pico skill from the user's description.
+
+${ASK_RULE}
+
+A skill is a markdown file at \`.pico/skills/<name>/SKILL.md\` (project) or
+\`~/.pico/skills/<name>/SKILL.md\` (global) with frontmatter and an instruction body:
+
+\`\`\`
+---
+name: release-notes
+description: draft release notes from commits since the last tag
+---
+Instructions the agent follows when this skill is loaded. Be imperative and specific.
+\`\`\`
+
+The description matters most: it is listed in the agent's system prompt, and the agent
+decides from it when to load the skill on its own. Write it as a trigger condition
+("when the user asks for X"), not marketing. The body is only loaded on invocation, so
+it can be long and detailed. Supporting files may sit next to SKILL.md in the same
+directory and be referenced by relative path.
+
+Skills are rescanned every turn, so a new skill is usable from the next message.`
+
+const NEW_COMMAND_SKILL = `Create a pico command from the user's description.
+
+${ASK_RULE}
+
+A command is a prompt template the USER invokes as \`/<name> [args]\`. The agent never
+sees commands until one is run, so use a command for user-triggered macros and a skill
+for capabilities the agent should reach for on its own.
+
+It is a markdown file at \`.pico/commands/<name>.md\` (project) or
+\`~/.pico/commands/<name>.md\` (global), optionally with a description in frontmatter:
+
+\`\`\`
+---
+description: review a file for security problems
+---
+Review $ARGUMENTS for security problems. Focus on input validation and secrets.
+\`\`\`
+
+\`$ARGUMENTS\` is replaced with whatever follows the command; without the placeholder,
+arguments are appended after the body. Commands are rescanned every turn, so a new
+command appears in the slash menu from the next message.`
+
+export async function createSkillIndex(root) {
+  const builtin = [
+    {
+      name: 'new-tool',
+      description: 'create a custom pico tool from a description of what it should do',
+      source: 'builtin',
+      body: NEW_TOOL_SKILL,
+    },
+    {
+      name: 'new-skill',
+      description: 'create a pico skill that teaches the agent a reusable capability',
+      source: 'builtin',
+      body: NEW_SKILL_SKILL,
+    },
+    {
+      name: 'new-command',
+      description: 'create a pico slash command, a prompt template the user invokes',
+      source: 'builtin',
+      body: NEW_COMMAND_SKILL,
+    },
+  ]
+  const global = await scanDir(globalSkillsDir(), 'global')
+  const project = await scanDir(projectSkillsDir(root), 'project')
+  const byName = new Map()
+  for (const skill of [...builtin, ...global, ...project]) byName.set(skill.name, skill)
+  const skills = [...byName.values()]
+
+  return {
+    list: () => skills,
+    async load(name) {
+      const skill = byName.get(name)
+      if (!skill) return null
+      if (skill.body) return skill.body
+      const { body } = parseFrontmatter(await readFile(skill.file, 'utf-8'))
+      return body
+    },
+  }
+}

package/src/steer.js

@@ -0,0 +1,129 @@
+export const STEER_ROLES = ['user', 'assistant']
+
+function validRole(role) {
+  return STEER_ROLES.includes(role)
+}
+
+function insertionIndex(timeline, anchor) {
+  if (!anchor) {
+    const first = timeline.findIndex((event) => event.type === 'message')
+    return first < 0 ? timeline.length : first
+  }
+  let index = timeline.indexOf(anchor) + 1
+  let followsToolSequence = !!anchor.data.message.tool_calls?.length
+  while (index < timeline.length) {
+    const event = timeline[index]
+    if (event.type !== 'message') {
+      index++
+      continue
+    }
+    const message = event.data.message
+    if (followsToolSequence && message.role === 'tool') {
+      index++
+      continue
+    }
+    if (followsToolSequence && message.role === 'assistant' && !message.content && message.tool_calls?.length) {
+      index++
+      continue
+    }
+    break
+  }
+  return index
+}
+
+function insertedEvent(transaction, change, index) {
+  return {
+    id: change.id,
+    at: transaction.at,
+    type: 'message',
+    data: { message: change.message },
+    _steered: true,
+    _sourceIndex: index,
+  }
+}
+
+export function applySteering(events) {
+  const timeline = []
+  const messages = new Map()
+  const active = new Set()
+  const insertionTails = new Map()
+  let compactIndex = -1
+
+  const rebuildActive = () => {
+    active.clear()
+    for (const event of timeline) {
+      if (event.type === 'clear') active.clear()
+      else if (event.type === 'message') active.add(event.id)
+    }
+  }
+
+  events.forEach((event, sourceIndex) => {
+    if (event.type !== 'steer') {
+      const normalized = event.type === 'message' ? { ...event, _sourceIndex: sourceIndex } : event
+      timeline.push(normalized)
+      if (event.type === 'message') {
+        messages.set(event.id, normalized)
+        active.add(event.id)
+      } else if (event.type === 'clear') {
+        active.clear()
+        compactIndex = -1
+      } else if (event.type === 'compact') {
+        compactIndex = sourceIndex
+      }
+      return
+    }
+
+    for (const change of event.data.changes || []) {
+      if (change.op === 'replace') {
+        const target = messages.get(change.target)
+        if (!target || !active.has(change.target) || target._sourceIndex < compactIndex) continue
+        if (!validRole(change.message?.role)) continue
+        target.data = {
+          ...target.data,
+          message: { ...target.data.message, role: change.message.role, content: change.message.content },
+        }
+        target._steered = true
+        continue
+      }
+      if (change.op === 'insert') {
+        if (!change.id || !STEER_ROLES.includes(change.message?.role)) continue
+        const anchor = change.after == null ? null : messages.get(change.after)
+        if (anchor && (!active.has(change.after) || anchor._sourceIndex < compactIndex)) continue
+        if (!anchor && change.after != null) continue
+        const inserted = insertedEvent(event, change, sourceIndex)
+        const stagedTail = insertionTails.get(change.after)
+        const tailId = stagedTail && active.has(stagedTail) ? stagedTail : change.after
+        const tail = tailId == null ? null : messages.get(tailId)
+        const at = insertionIndex(timeline, tail)
+        timeline.splice(at, 0, inserted)
+        messages.set(inserted.id, inserted)
+        active.add(inserted.id)
+        insertionTails.set(change.after, inserted.id)
+        continue
+      }
+      if (change.op === 'delete') {
+        const target = messages.get(change.target)
+        if (!target || !active.has(change.target) || target._sourceIndex < compactIndex) continue
+        const start = timeline.indexOf(target)
+        const end = insertionIndex(timeline, target)
+        const removed = new Set([target])
+        if (target.data.message.tool_calls?.length) {
+          for (let index = start + 1; index < end; index++) {
+            if (timeline[index].type === 'message') removed.add(timeline[index])
+          }
+        }
+        for (let index = timeline.length - 1; index >= 0; index--) {
+          if (removed.has(timeline[index])) timeline.splice(index, 1)
+        }
+        for (const message of removed) active.delete(message.id)
+      }
+    }
+    rebuildActive()
+  })
+
+  return timeline
+}
+
+export function steerableTranscript(transcript) {
+  return transcript.filter((item) => item.messageId && STEER_ROLES.includes(item.role || item.kind))
+}

package/src/system-prompt.js

@@ -0,0 +1,49 @@
+import { platform, arch, release } from 'node:os'
+
+const PLATFORM_NOTES = {
+  darwin: `macOS (darwin ${arch()}, kernel ${release()}). BSD userland: GNU-only tools like timeout, tac, gdate, or sed -i without a suffix argument are absent or behave differently. Prefer portable POSIX forms, and check a tool exists before relying on it.`,
+  linux: `Linux (${arch()}, kernel ${release()}). GNU userland.`,
+  win32: `Windows (${arch()}). Commands run through a POSIX-style shell; prefer portable forms.`,
+}
+
+export function buildSystemPrompt({ cwd, contextFiles = [], skills = [], memoryIndexText = '' }) {
+  const now = new Date()
+  const parts = [
+    `You are pico, a coding agent running in a terminal.`,
+    ``,
+    `Working directory: ${cwd}`,
+    `Platform: ${PLATFORM_NOTES[platform()] || platform()}`,
+    `Current date and time: ${now.toString()}`,
+    ``,
+    `Use the available tools to read, search, and modify files, and to run commands.`,
+    `Use absolute paths in tool calls.`,
+    `Prefer the built-in tools for file and shell work: read, write, edit, bash, glob, grep.`,
+    `Tools with server-prefixed names come from MCP servers: reach for them only when they provide a capability the built-in tools do not, never as a substitute for simple file access or shell commands.`,
+    `Prefer reading files before editing them. Keep edits minimal and precise.`,
+    `When a tool result includes context_from_agents_md, treat it as project instructions that apply from that point on.`,
+    `Tools are yours alone: the user cannot invoke them, so never suggest the user run a tool. Do it yourself, or describe the outcome instead.`,
+    `Delegate only when a worker's result will materially inform the task. Workers do not receive the parent conversation, so every worker prompt must be a self-contained brief containing all conversation-specific terms, goals, constraints, and decisions that cannot be discovered from the available files and tools. Before starting an agent, identify the work that depends on its result; while it runs, perform only genuinely independent work, then collect the result before making dependent decisions or edits. If you can confidently complete the task without the result, do not start the agent.`,
+    `Deliberation and delegation serve different purposes. Use deliberate when the task is to evaluate competing approaches, challenge a proposal, or reach a consequential decision under genuine uncertainty. Use ordinary agents when independent work can be divided and collected. When the user requests deliberation, immediately call deliberate with a self-contained brief; do not research first or approximate deliberation with multiple ordinary agents. The deliberation participants own all supporting research. Do not deliberate routine implementation or questions answerable through direct research.`,
+    `Be direct and concise. Use markdown. Never invent file contents you have not read.`,
+    `When providing links that you want the user to be able to click, output either plain URLs or unfenced Markdown links.`,
+    `Announcing future work and stopping is forbidden. If your reply contains phrases like "I'll update", "I will now", or "Next I'll", you must make those tool calls in this same turn instead of ending it. A turn may only end in one of two states: the work is done, or you are asking the user a question and waiting. When the user asks "should we do X?" and your answer is yes, say yes briefly and then do X immediately in the same turn; stop to ask first only when doing X is destructive, expensive, or genuinely ambiguous.`,
+  ]
+
+  if (memoryIndexText) {
+    parts.push(``, memoryIndexText)
+  }
+
+  if (skills.length) {
+    parts.push(
+      ``,
+      `Skills available via the skill tool (load one when its description matches the task):`,
+      ...skills.map((s) => `- ${s.name}: ${s.description}`),
+    )
+  }
+
+  for (const file of contextFiles) {
+    parts.push(``, `Project instructions from ${file.path}:`, ``, file.content.trim())
+  }
+
+  return parts.join('\n')
+}

package/src/terminal-theme.js

@@ -0,0 +1,49 @@
+export function parseOsc11(response) {
+  const match = response.match(/\]11;rgb:([0-9a-f]+)\/([0-9a-f]+)\/([0-9a-f]+)/i)
+  if (!match) return null
+  const channel = (hex) => parseInt(hex, 16) / (16 ** hex.length - 1)
+  const luminance = 0.2126 * channel(match[1]) + 0.7152 * channel(match[2]) + 0.0722 * channel(match[3])
+  return luminance > 0.5 ? 'light' : 'dark'
+}
+
+export function themeFromColorfgbg(value) {
+  const token = (value || '').split(';').at(-1)
+  if (!/^\d+$/.test(token)) return null
+  const bg = Number(token)
+  return bg === 7 || bg === 15 ? 'light' : 'dark'
+}
+
+export function detectTerminalTheme({ timeoutMs = 150 } = {}) {
+  const fallback = () => themeFromColorfgbg(process.env.COLORFGBG) || 'dark'
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return Promise.resolve(fallback())
+
+  return new Promise((resolve) => {
+    let buffer = ''
+    let settled = false
+    const wasRaw = process.stdin.isRaw
+
+    // never pause() here: an explicit pause sticks, and trend's mount only
+    // attaches a data listener, which will not un-pause an explicitly
+    // paused stream - input would be frozen for the whole session
+    const finish = (theme) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      process.stdin.off('data', onData)
+      process.stdin.setRawMode(wasRaw)
+      resolve(theme)
+    }
+
+    const onData = (chunk) => {
+      buffer += chunk.toString('latin1')
+      const theme = parseOsc11(buffer)
+      if (theme) finish(theme)
+    }
+
+    const timer = setTimeout(() => finish(fallback()), timeoutMs)
+    process.stdin.setRawMode(true)
+    process.stdin.on('data', onData)
+    process.stdin.resume()
+    process.stdout.write('\x1b]11;?\x1b\\')
+  })
+}

package/src/tools/bash.js

@@ -0,0 +1,184 @@
+import { spawn } from 'node:child_process'
+import { sgr, stripAnsi, updateSgrState } from '@trendr/core'
+
+const MAX_OUTPUT_CHARS = 30000
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024
+const OUTPUT_PREVIEW_LINES = 10
+const MAX_PREVIEW_LINE_CHARS = 4000
+export const AUTO_BACKGROUND_MS = 150000
+
+function capped(text) {
+  if (text.length <= MAX_OUTPUT_CHARS) return text
+  return text.slice(0, MAX_OUTPUT_CHARS) + `\n[output truncated at ${MAX_OUTPUT_CHARS} characters]`
+}
+
+function createOutputPreview() {
+  let lines = []
+  let current = ''
+  let currentStartStyle = ''
+  let completed = 0
+  const ansiState = { fg: null, bg: null, attrs: 0 }
+
+  function add(chunk) {
+    const parts = String(chunk).split('\n')
+    current = (current + parts[0]).slice(0, MAX_PREVIEW_LINE_CHARS)
+    updateSgrState(parts[0], ansiState)
+    for (let i = 1; i < parts.length; i++) {
+      lines.push({ text: current, startStyle: currentStartStyle })
+      if (lines.length > OUTPUT_PREVIEW_LINES) lines.shift()
+      completed++
+      currentStartStyle = ansiState.fg != null || ansiState.bg != null || ansiState.attrs ? sgr(ansiState.fg, ansiState.bg, ansiState.attrs) : ''
+      current = parts[i].slice(0, MAX_PREVIEW_LINE_CHARS)
+      updateSgrState(parts[i], ansiState)
+    }
+  }
+
+  function snapshot() {
+    const hasCurrentText = stripAnsi(current).length > 0
+    const visible = hasCurrentText ? [...lines, { text: current, startStyle: currentStartStyle }].slice(-OUTPUT_PREVIEW_LINES) : lines
+    if (!visible.length) return null
+    const count = completed + (hasCurrentText ? 1 : 0)
+    return {
+      fullOutput: visible.map((line) => `${line.startStyle}${line.text}`).join('\n'),
+      outputLineStart: count - visible.length + 1,
+      outputLineCount: count,
+    }
+  }
+
+  return { add, snapshot }
+}
+
+function killTree(child, signal = 'SIGTERM') {
+  if (!child.pid) return false
+  if (process.platform !== 'win32') {
+    try {
+      process.kill(-child.pid, signal)
+      return true
+    } catch {}
+  }
+  return child.kill(signal)
+}
+
+export function createBash({ cwd, env, recorder, signal, shells, sessionId, sessionFile, autoBackgroundMs = AUTO_BACKGROUND_MS }) {
+  return {
+    name: 'bash',
+    description: 'Run a shell command in the working directory. Each call is a fresh shell: cd does not persist to later calls, so chain directory changes within one command (cd /x && ls) or use absolute paths. Returns stdout, stderr, and exit code. Foreground commands still running after 150 seconds are automatically backgrounded. Run known long-lived commands with background true. Background shells notify you when they exit. If no independent work remains, end your turn and wait for that notification instead of polling. Use shell_output only when intermediate output is needed to diagnose a problem or make a decision before exit. Stop shells with shell_kill.',
+    schema: {
+      command: { type: 'string', description: 'the command to run' },
+      timeout: { type: 'number', description: 'optional foreground timeout in milliseconds; commands still running after 150 seconds are backgrounded instead', optional: true },
+      background: { type: 'boolean', description: 'run in the background and return a shell id immediately', optional: true },
+      description: { type: 'string', description: 'a few words explaining the purpose of this command, shown to the human watching' },
+    },
+    execute: ({ command, timeout, background, description }) => {
+      if (background && shells) {
+        recorder.extra({ title: command, titleLang: 'bash', description, background: true })
+        const { id } = shells.start(command, { cwd, env, description, sessionId, sessionFile })
+        return {
+          shellId: id,
+          status: 'running',
+          note: 'the shell will notify you when it exits; if no independent work remains, end your turn and wait instead of polling with shell_output, wake-ups, sleeps, or another shell',
+        }
+      }
+      return new Promise((resolve) => {
+        recorder.extra({ title: command, titleLang: 'bash' })
+        const child = spawn(command, {
+          shell: true,
+          cwd: cwd || process.cwd(),
+          env: { ...process.env, ...env, FORCE_COLOR: '0', NO_COLOR: '1' },
+          stdio: ['ignore', 'pipe', 'pipe'],
+          detached: process.platform !== 'win32',
+        })
+        const { id } = shells
+          ? shells.track(child, command, { cwd, description, sessionId, sessionFile, hidden: true })
+          : { id: null }
+        let stdout = ''
+        let stderr = ''
+        let settled = false
+        let timedOut = false
+        let killTimer = null
+        const preview = createOutputPreview()
+
+        const updateOutput = () => {
+          const snapshot = preview.snapshot()
+          if (snapshot) recorder.extra(snapshot)
+        }
+        const collectStdout = (chunk) => {
+          stdout = (stdout + chunk).slice(-MAX_BUFFER_BYTES)
+          preview.add(chunk)
+          updateOutput()
+        }
+        const collectStderr = (chunk) => {
+          stderr = (stderr + chunk).slice(-MAX_BUFFER_BYTES)
+          preview.add(chunk)
+          updateOutput()
+        }
+        child.stdout.on('data', collectStdout)
+        child.stderr.on('data', collectStderr)
+
+        const timeoutTimer = timeout
+          ? setTimeout(() => {
+              timedOut = true
+              terminate()
+            }, timeout)
+          : null
+        const backgroundTimer = shells
+          ? setTimeout(() => {
+              if (settled) return
+              settled = true
+              clearTimeout(timeoutTimer)
+              cleanup()
+              shells.reveal(id)
+              recorder.extra({ title: command, titleLang: 'bash', description, background: true })
+              resolve({
+                shellId: id,
+                status: 'running',
+                note: `automatically backgrounded after ${autoBackgroundMs}ms; the shell will notify you when it exits; if no independent work remains, end your turn and wait instead of polling`,
+              })
+            }, autoBackgroundMs)
+          : null
+        backgroundTimer?.unref?.()
+        timeoutTimer?.unref?.()
+
+        function cleanup() {
+          if (signal) signal.removeEventListener('abort', abort)
+          child.stdout.off('data', collectStdout)
+          child.stderr.off('data', collectStderr)
+          clearTimeout(killTimer)
+        }
+        function terminate() {
+          if (!killTree(child, 'SIGTERM')) return
+          clearTimeout(killTimer)
+          killTimer = setTimeout(() => killTree(child, 'SIGKILL'), 3000)
+          killTimer.unref?.()
+        }
+        function abort() {
+          terminate()
+        }
+        if (signal) {
+          if (signal.aborted) terminate()
+          else signal.addEventListener('abort', abort, { once: true })
+        }
+        child.on('close', (code) => {
+          if (settled) return
+          settled = true
+          clearTimeout(backgroundTimer)
+          clearTimeout(timeoutTimer)
+          cleanup()
+          if (id) shells.discardHidden(id)
+          const exitCode = code ?? 1
+          updateOutput()
+          recorder.extra({ exitCode })
+          resolve({
+            stdout: capped(stdout),
+            stderr: capped(stderr),
+            exitCode,
+            ...(timedOut && {
+              timedOut: true,
+              note: `killed at the ${timeout}ms timeout`,
+            }),
+          })
+        })
+      })
+    },
+  }
+}

package/src/tools/diff.js

@@ -0,0 +1,18 @@
+import { structuredPatch } from 'diff'
+
+export function makeDiff(path, oldText, newText, contextLines = 3) {
+  const patch = structuredPatch(path, path, oldText, newText, '', '', { context: contextLines })
+  let additions = 0
+  let deletions = 0
+  const hunks = patch.hunks.map((h) => ({
+    oldStart: h.oldStart,
+    newStart: h.newStart,
+    lines: h.lines.map((line) => {
+      const type = line[0] === '-' ? 'remove' : line[0] === '+' ? 'add' : 'context'
+      if (type === 'add') additions++
+      if (type === 'remove') deletions++
+      return { type, text: line.slice(1) }
+    }),
+  }))
+  return { path, hunks, additions, deletions }
+}