picocode-core 0.9.123 → 0.9.125

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picocode-core",
-  "version": "0.9.123",
+  "version": "0.9.125",
   "description": "The agent runtime behind pico: sessions, tools, subagents, MCP, memory, and model access",
   "type": "module",
   "license": "MIT",

package/src/tools/bash.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 import { spawn } from 'node:child_process'
 import { stripAnsi, createSgrTracker } from '../ansi.js'
 
@@ -67,7 +68,7 @@ export function createBash({ cwd, env, recorder, signal, shells, sessionId, sess
       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' },
+      description: describeParam,
     },
     execute: ({ command, timeout, background, description }) => {
       if (background && shells) {

package/src/tools/edit.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 import { readFile, writeFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { makeReversibleEdit } from '../reversible-edit.js'
@@ -54,7 +55,7 @@ export function createEdit({ cwd, recorder, tracker }) {
     name: 'edit',
     description: 'Replace oldText with newText in a file. oldText must appear exactly once unless replaceAll is set.',
     schema: {
-      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      description: describeParam,
       path: { type: 'string', description: 'file path, relative to the working directory or absolute' },
       oldText: { type: 'string', description: 'exact text to replace, must be unique in the file' },
       newText: { type: 'string', description: 'replacement text' },

package/src/tools/glob.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 import { execFile } from 'node:child_process'
 import fg from 'fast-glob'
 
@@ -18,7 +19,7 @@ export function createGlob({ cwd, recorder }) {
     name: 'glob',
     description: 'Find files matching a glob pattern, relative to the working directory. Respects .gitignore; use bash to look inside ignored paths.',
     schema: {
-      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      description: describeParam,
       pattern: { type: 'string', description: 'glob pattern, e.g. src/**/*.js' },
       maxResults: { type: 'number', description: 'cap on returned paths, default 200', optional: true },
     },

package/src/tools/grep.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 import { execFile } from 'node:child_process'
 import { relative, resolve } from 'node:path'
 
@@ -16,7 +17,7 @@ export function createGrep({ cwd, recorder }) {
     name: 'grep',
     description: 'Search file contents with a regex using ripgrep. mode "content" returns matching lines, "files" returns matching file paths, "count" returns per-file match counts.',
     schema: {
-      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      description: describeParam,
       pattern: { type: 'string', description: 'regex pattern' },
       path: { type: 'string', description: 'file or directory to search, defaults to the working directory', optional: true },
       mode: { type: 'string', enum: ['content', 'files', 'count'], optional: true },

package/src/tools/index.js

@@ -1,4 +1,4 @@
-import { createRecorder, recorded } from './recorder.js'
+import { createRecorder, describeParam, recorded } from './recorder.js'
 import { createRead } from './read.js'
 import { createWrite } from './write.js'
 import { createEdit } from './edit.js'
@@ -32,6 +32,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         name: 'shell_output',
         description: 'Read recent output from a background shell started with bash background: true. Use only when intermediate output is needed to diagnose a suspected problem or make a decision before the shell exits. Do not use for routine progress polling; completion is delivered automatically, so if no independent work remains, end your turn and wait.',
         schema: {
+          description: describeParam,
           id: { type: 'string', description: 'the shell id' },
           tail: { type: 'number', description: 'how many trailing lines to return, default 100', optional: true },
         },
@@ -47,6 +48,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         name: 'shell_kill',
         description: 'Stop a background shell by id.',
         schema: {
+          description: describeParam,
           id: { type: 'string', description: 'the shell id' },
         },
         execute: ({ id }) => shells.kill(id, 'model'),
@@ -60,7 +62,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         name: 'schedule_wakeup',
         description: 'Schedule a one-time wake-up: after the delay you receive a system notification carrying your note and can act on it. For a recurring loop, schedule the next wake-up at the end of each one. Do not use this to poll a background shell; its exit already notifies you. Wake-ups are lost if pico exits.',
         schema: {
-          description: { type: 'string', description: 'briefly explain why this wake-up is needed, shown to the human watching' },
+          description: describeParam,
           delaySeconds: { type: 'number', description: 'seconds from now, minimum 5' },
           note: { type: 'string', description: 'what to do when you wake up; written to your future self' },
         },
@@ -73,6 +75,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         name: 'cancel_wakeup',
         description: 'Cancel a pending wake-up by id.',
         schema: {
+          description: describeParam,
           id: { type: 'string', description: 'the wake-up id' },
         },
         execute: ({ id }) => wakeups.cancel(id),
@@ -80,7 +83,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
       {
         name: 'list_wakeups',
         description: 'List your pending scheduled wake-ups: id, when each fires, and its note.',
-        schema: {},
+        schema: { description: describeParam },
         execute: () => ({
           wakeups: wakeups.list().map((w) => ({
             id: w.id,
@@ -98,6 +101,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
       name: 'ask_user',
       description: 'Ask the user one or more focused questions when their answers are genuinely needed to continue. Supports free text, one choice, or multiple choices. Do not ask questions you can answer from available context.',
       schema: {
+        description: describeParam,
         questions: {
           type: 'array',
           description: 'questions to present, in order',
@@ -146,6 +150,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         name: 'agent_plan',
         description: 'Declare the background worker budget for the current assistant turn before starting any workers. The main agent is excluded. Set count to the number of workers you intend to start this turn; collecting a worker does not restore budget. Interpret any user-requested count semantically; otherwise use the configured default.',
         schema: {
+          description: describeParam,
           count: { type: 'integer', description: `background workers permitted this turn, excluding the main agent (1-${maxAgentStarts || 100})` },
           reason: { type: 'string', description: 'brief explanation of how the count follows the user request or research scope' },
         },
@@ -162,7 +167,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         description: 'Start one background worker, consuming one unit of the current turn\'s agent_plan budget. Workers do not receive the parent conversation, only the supplied prompt and their available project context and tools. Make the prompt self-contained by including all conversation-specific terms, goals, constraints, and decisions the worker cannot discover itself. Collected or completed workers do not restore budget within that turn. Continue only independent work until you collect its result with agent_collect.',
         schema: {
           prompt: { type: 'string', description: 'complete, self-contained task and desired output, including necessary context from the parent conversation' },
-          description: { type: 'string', description: 'short label shown to the user' },
+          description: describeParam,
           tools: { type: 'array', items: { type: 'string' }, description: 'tool names to allow; omit for the configured worker tools', optional: true },
         },
         execute: ({ prompt, description, tools }) => {
@@ -176,13 +181,13 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
       {
         name: 'agent_list',
         description: 'List background agents and their current status.',
-        schema: {},
+        schema: { description: describeParam },
         execute: () => ({ agents: agents.list().map(({ id, description, model, status }) => ({ id, description, model, status })) }),
       },
       {
         name: 'agent_collect',
         description: 'Collect background agent results. Waits for any selected agents that are still running.',
-        schema: { ids: { type: 'array', items: { type: 'string' }, description: 'agent ids whose results to collect' } },
+        schema: { description: describeParam, ids: { type: 'array', items: { type: 'string' }, description: 'agent ids whose results to collect' } },
         execute: async ({ ids }) => {
           const requested = (ids || []).map(String)
           const collected = await agents.collect(requested)
@@ -203,7 +208,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
       {
         name: 'agent_cancel',
         description: 'Cancel a queued or running background agent.',
-        schema: { id: { type: 'string', description: 'agent id' } },
+        schema: { description: describeParam, id: { type: 'string', description: 'agent id' } },
         execute: ({ id }) => ({ cancelled: agents.cancel(id) }),
       },
     )
@@ -214,6 +219,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
       name: 'deliberate',
       description: 'Evaluate competing approaches, challenge a proposal, or reach a consequential decision under genuine uncertainty through a bounded, evidence-seeking exchange between two full tool-using agents. When the user requests deliberation, call this tool immediately with a self-contained brief: do not research first or approximate deliberation with multiple ordinary agents. Its participants own all supporting research. Use ordinary agents when independent work can be divided and collected. Do not deliberate routine implementation or questions answerable through direct research.',
       schema: {
+        description: describeParam,
         brief: { type: 'string', description: 'self-contained decision, relevant context, constraints, and desired outcome' },
         rounds: { type: 'integer', description: 'number of proposer-reviewer exchanges (1-5, default 3)', optional: true },
       },
@@ -242,6 +248,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         name: 'recall',
         description: 'Load the full content of a saved memory by name. Your memory index is in the system prompt.',
         schema: {
+          description: describeParam,
           name: { type: 'string', description: 'the memory name from the index' },
         },
         execute: async ({ name }) => {
@@ -261,6 +268,7 @@ export function createToolset({ cwd, env, tracker, skills, shells, sessionId, se
         .map((s) => `- ${s.name}: ${s.description}`)
         .join('\n')}`,
       schema: {
+        description: describeParam,
         name: { type: 'string', description: 'skill name' },
       },
       execute: async ({ name }) => {

package/src/tools/read.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 
@@ -17,7 +18,7 @@ export function createRead({ cwd, recorder, tracker }) {
     name: 'read',
     description: 'Read a file. Returns line-numbered content. Use offset/limit for large files.',
     schema: {
-      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      description: describeParam,
       path: { type: 'string', description: 'file path, relative to the working directory or absolute' },
       offset: { type: 'number', description: '1-indexed line to start from', optional: true },
       limit: { type: 'number', description: 'max lines to return', optional: true },

package/src/tools/recorder.js

@@ -7,6 +7,13 @@ function collapseHomePath(value) {
   return value
 }
 
+// every built-in tool takes this parameter; it is the line the human sees
+// in the transcript while the call runs
+export const describeParam = {
+  type: 'string',
+  description: 'what this call is doing, in present tense, a few words shown to the human watching, e.g. "Creating the test file" or "Collecting the worker results"',
+}
+
 export function defaultTitle(name, args = {}) {
   const candidate = args.path || args.command || args.pattern || args.url || args.name
   if (typeof candidate === 'string' && candidate) return collapseHomePath(candidate)
@@ -24,6 +31,7 @@ export function createRecorder(onChange) {
       this.pending = {
         callId: this.currentCall?.id ?? null,
         name,
+        args,
         title: defaultTitle(name, args),
         description: args.description,
         status: 'done',

package/src/tools/web.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 const DEFAULT_SLICE_CHARS = 24000
 const MAX_SLICE_CHARS = 100000
 
@@ -34,7 +35,7 @@ export function createWebTools({ dredge, recorder, signal }) {
         'Search the web. Google-style operators work: site:, filetype:pdf, quoted phrases. Returns ranked results; pass a result url to web_fetch to read it.',
       schema: {
         q: { type: 'string', description: 'the search query' },
-        description: { type: 'string', description: 'briefly explain what this search is intended to find, shown to the human watching' },
+        description: describeParam,
       },
       execute: async ({ q }) => {
         recorder.extra({ title: q })
@@ -58,6 +59,7 @@ export function createWebTools({ dredge, recorder, signal }) {
       description:
         'Fetch a url and read it as clean markdown (html, pdf, docx, and textual formats like json). Long documents arrive in slices: the result says which slice you have (e.g. "slice 1 of 12") and next_cursor continues from there. Every slice you fetch permanently occupies conversation context, so only walk cursors for content you actually need, and raise maxChars only when the task genuinely needs a bigger window.',
       schema: {
+        description: describeParam,
         url: { type: 'string', description: 'the url to fetch' },
         cursor: { type: 'string', description: 'pagination cursor from a previous web_fetch of the same url', optional: true },
         maxChars: { type: 'number', description: `slice size in characters, default ${DEFAULT_SLICE_CHARS}, max ${MAX_SLICE_CHARS}`, optional: true },

package/src/tools/write.js

@@ -1,3 +1,4 @@
+import { describeParam } from './recorder.js'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { makeWriteEdit } from '../reversible-edit.js'
@@ -8,7 +9,7 @@ export function createWrite({ cwd, recorder, tracker }) {
     name: 'write',
     description: 'Write content to a file, creating it and any parent directories if needed. Overwrites existing content.',
     schema: {
-      description: { type: 'string', description: 'briefly explain why this tool call is needed, shown to the human watching' },
+      description: describeParam,
       path: { type: 'string', description: 'file path, relative to the working directory or absolute' },
       content: { type: 'string', description: 'the full file content to write' },
     },