pi-optchat 0.6.5 → 0.6.7

package/README.md

@@ -68,9 +68,11 @@ Compression and subagents make extra model requests with your provider credentia
 Ask in plain words, for example: "Spawn an agent to investigate this repository and report back."
 
 - Children get the profile's memory view (frozen at launch), its instructions, read-only `zoom`/`date`, and normal coding tools plus your installed extensions.
+- Children also get the Pi built-in extensions the main session loaded: MCP, codemode and tool search. Your MCP servers (`~/.pi/agent/mcp.json`, the project's `.pi/mcp.json`) work in subagents, with the sign-ins you made in Pi. If MCP is off in the main session (`--no-mcp`, `-builtin:mcp` in settings, or an extension that replaces `/mcp`), it is off in subagents too. Each subagent opens its own server connections (stdio servers start once per subagent) and closes them when it ends.
 - Each child reports back on its own when it finishes. The parent stays alive to receive reports; it never polls.
 - In the main chat, subagent messages and reports appear in a dark grey box labelled `↳ subagent <id> · still running` or `· report`, so they don't look like something you typed. The model still receives them as ordinary user messages. (One exception: reports recovered at startup, before your first message in the session, still show as plain user messages.)
 - The parent can send a running child guidance with `tell`, and the child can message its parent mid-run with `tell_parent` (a question, an early finding). It reaches the parent like a report, marked "still running": between tool calls if the parent is busy, or waking it if it's waiting.
+- `tell` to a finished child resumes it: the same agent (ID, parent, model, directory) reopens its saved transcript, gets the message as a new prompt, and sends a new report. This also works for children from earlier Pi sessions. Only the agent that started the child can resume it, and the resumed child takes one of the 8 slots. Connected windows can't be resumed, and a child whose transcript is missing must be spawned fresh.
 - Delegation goes up to three levels below the main agent (child, grandchild, great-grandchild).
 - At most 8 agents can be active per profile, including parents waiting on descendants. Going over a limit returns an error; there is no queue.
 - Stopping an agent stops its whole subtree. A failed parent stops its descendants.
@@ -103,7 +105,9 @@ Set a different shortcut with `OPTCHAT_INSPECT_KEY=ctrl+shift+a pi`. If another
 
 Guidance shows as queued until delivered, or undelivered if the child stops first. Guidance you send is also saved in main memory. Reasoning is not shown. Transcripts stay browsable after restart, and browsing them makes no model calls.
 
-**Usage** shows this session, last hour, today, last 7 days, or all time (**Left/Right**). It breaks down main agent, subagents, compactor, and imports by model: uncached input, output, cache reads/writes, and estimated cost.
+**Usage** shows this session, last hour, today, last 7 days, or all time (**Left/Right**): one row per role and model (main agent, subagents, compactor, imports) with estimated cost, share of the total, output tokens, and how much input came from the cache. Costs are API prices, not your subscription bill.
+
+![Usage page](docs/screenshots/usage.png)
 
 - Costs are API-rate estimates, not your subscription bill. Unknown rates show zero.
 - Record counts are not request counts; retries and tool overhead can add records.
@@ -185,7 +189,7 @@ To delete a profile, delete its folder. Your original Pi sessions are kept in Pi
 
 ## How it differs from the recipe
 
-The recipe's four prompts are kept verbatim in `src/prompts.ts`, along with its numbers: 512-byte summary nodes, a 128,000-byte memory view, binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Anthropic requests get stable cache breakpoints on the view. See `docs/victor-recipe.md` for notes.
+The recipe's four prompts are kept verbatim in `src/prompts.ts`, along with its numbers: 512-byte summary nodes (summaries up to 640 bytes are accepted without a retry), a 128,000-byte memory view, binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Anthropic requests get stable cache breakpoints on the view, and when that view is not cached yet, one compactor call goes first and the others wait until it starts answering, so they read the cache instead of each writing it. See `docs/victor-recipe.md` for notes.
 
 Each run's context is the memory view, the previous exchange, and your new message. Deliberate additions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-optchat",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "type": "module",
   "pi": {
     "extensions": [

package/src/agent-view.ts

@@ -3,7 +3,7 @@ import {
   createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition,
   type ExtensionContext,
 } from '@earendil-works/pi-coding-agent';
-import { Editor, Spacer, matchesKey, truncateToWidth, visibleWidth, type Component, type Focusable, type TUI, type TuiMouseEvent, type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import { Editor, Spacer, compositeTuiLine, matchesKey, truncateToWidth, visibleWidth, type Component, type Focusable, type TUI, type TuiMouseEvent, type TuiMouseEventResult } from '@earendil-works/pi-tui';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { Children } from './agents.ts';
 import type { RunInfo } from './runs.ts';
@@ -297,10 +297,27 @@ export class AgentView implements Component, Focusable {
   }
 }
 
+/**
+ * Pi never composites overlays onto rows holding a terminal image (earendil-works/pi#6995), so images in the
+ * main chat would show through the full-screen view. While it is open, image rows under overlays are blanked.
+ * If Pi renames the hook, this quietly does nothing.
+ */
+export function hideImagesUnderOverlays(tui: TUI) {
+  Object.assign(tui, { compositeLineAt: (...[base, ...rest]: Parameters<typeof compositeTuiLine>) =>
+    compositeTuiLine(/\x1b_G|\x1b\]1337;File=/.test(base) ? '' : base, ...rest) });
+  return () => { Reflect.deleteProperty(tui, 'compositeLineAt'); };
+}
+
 /** Swaps the whole screen to the subagent's conversation; Pi restores the main chat on close. */
-export function showAgentView(ctx: ExtensionContext, options: { id: string; children: Children; signal?: AbortSignal }) {
-  return ctx.ui.custom<void>((tui, theme, keybindings, done) => new AgentView({ ...options, tui,
-    rows: () => tui.terminal.rows, redraw: () => tui.requestRender(), done: () => done(undefined),
-    color: (tone, text) => theme.fg(tone, text), isExpandKey: data => keybindings.matches(data, 'app.tools.expand'),
-  }), { overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', row: 0, col: 0 } });
+export async function showAgentView(ctx: ExtensionContext, options: { id: string; children: Children; signal?: AbortSignal }) {
+  let restore = () => {};
+  try {
+    return await ctx.ui.custom<void>((tui, theme, keybindings, done) => {
+      restore = hideImagesUnderOverlays(tui);
+      return new AgentView({ ...options, tui,
+        rows: () => tui.terminal.rows, redraw: () => tui.requestRender(), done: () => done(undefined),
+        color: (tone, text) => theme.fg(tone, text), isExpandKey: data => keybindings.matches(data, 'app.tools.expand'),
+      });
+    }, { overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', row: 0, col: 0 } });
+  } finally { restore(); }
 }

package/src/agents.ts

@@ -2,8 +2,10 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, getAgentDir, type AgentSession, type AgentSessionEvent, type ModelRegistry } from '@earendil-works/pi-coding-agent';
+import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, getAgentDir, type AgentSession, type AgentSessionEvent, type ExtensionAPI, type InlineExtension, type ModelRegistry } from '@earendil-works/pi-coding-agent';
+import * as sdk from '@earendil-works/pi-coding-agent';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { Api, Model } from '@earendil-works/pi-ai';
 import { SUBAGENT, VIEW_DOC } from './prompts.ts';
 import { memoryTools } from './tools.ts';
 import { type Memory } from './memory.ts';
@@ -22,6 +24,8 @@ export interface LiveRun {
   pendingReports: string[]; pendingGuidance: string[]; wake?: () => void; completion?: Promise<void>;
 }
 interface Options { parentSession?: string; usage?: UsageLedger; createSession?: typeof createAgentSession;
+  /** Names of the built-in extensions the main session loaded (see `loadedBuiltins`). */
+  builtins?: () => Iterable<string>;
   summarizeHandoff?: (run: RunInfo, messages: AgentMessage[], descendants?: HandoffEvidence[]) => Promise<string> }
 
 // Subagents load the user's installed extensions, except any copy of OptChat itself: they get memory tools directly and must not open a profile.
@@ -40,12 +44,26 @@ export const taskDirectory = (cwd: string, path = '.', windows = process.platfor
   resolve(cwd, path.replace(windows ? /^~(?=$|[\\/])/ : /^~(?=$|\/)/, homedir()));
 export const CWD_DOC = 'Project directory the subagent works in (~ allowed); its AGENTS.md files load from there. Defaults to your current directory.';
 const isOptchat = (path: string) => packageName(path) === 'pi-optchat';
+
+// Pi's CLI adds its built-in extensions (MCP, codemode, tool search) to its own session; SDK sessions such as
+// subagents must add them. Pi versions that do not export a factory simply do not get that extension.
+const BUILTINS: Record<string, string> = { mcp: 'createMcpExtension', codemode: 'createCodemodeExtension', 'tool-search': 'createToolSearchExtension' };
+const PREFIX = 'builtin:';
+/** The built-in extensions a session loaded: `--no-mcp`, `-builtin:<name>` settings and replacing extensions leave them out. */
+export const loadedBuiltins = (pi: Pick<ExtensionAPI, 'getCommands' | 'getAllTools'>) => new Set([...pi.getCommands(), ...pi.getAllTools()]
+  .map(item => item.sourceInfo?.path ?? '').filter(path => path.startsWith(PREFIX) && Object.hasOwn(BUILTINS, path.slice(PREFIX.length))).map(path => path.slice(PREFIX.length)));
+/** Fresh built-in extensions for one session, as `builtin:<name>` resources, so the session's own settings still apply. */
+export const builtinExtensions = (names: Iterable<string>): InlineExtension[] => [...new Set(names)].flatMap(name => {
+  const create = Object.hasOwn(BUILTINS, name) ? (sdk as unknown as Record<string, unknown>)[BUILTINS[name]] : undefined;
+  return typeof create === 'function' ? [{ name, factory: create(), replaceable: true, builtin: true }] : [];
+});
 export class Children {
   private readonly running = new Map<string, LiveRun>();
   readonly history: RunHistory;
   private readonly listeners = new Set<() => void>();
   private closing = false;
   private launching = 0;
+  private readonly resuming = new Set<string>();
   private settling = 0;
   private readonly completions = new Set<Promise<void>>();
   constructor(private readonly memory: Memory, private readonly registry: ModelRegistry,
@@ -122,32 +140,8 @@ export class Children {
         signal?.throwIfAborted();
         if (cancelled()) throw new Error('Parent or profile is stopping.');
         const id = randomUUID().slice(0, 8), directory = taskDirectory(cwd, task.cwd);
-        const delegation = depth < 3 ? 'You may delegate parts of your assigned task with spawn when useful. Child reports arrive automatically after your current run ends; the harness keeps you alive to receive them. Never poll, sleep, or wait in a tool for children. Finish your current work and return; you will be prompted with their results. The profile allows 8 active agents total.' : 'You are at the maximum delegation depth. Complete your task with your own tools.';
-        const instructions = [this.instructions(), delegation, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_parent for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.'
-          : 'Use tell_parent only when your parent needs something now (a blocking question, an important early finding, or when asked to). Your final answer is delivered automatically; do not repeat it with tell_parent.'].filter(Boolean).join('\n\n');
-        // The user's settings list their installed packages; a copy in memory keeps the child from writing them back.
-        const settingsManager = SettingsManager.inMemory({ ...SettingsManager.create(directory, getAgentDir()).getSettings(), compaction: { enabled: false }, cacheWarming: 'off' });
-        const loader = new DefaultResourceLoader({ cwd: directory, agentDir: getAgentDir(), settingsManager,
-          noPromptTemplates: true,
-          extensionsOverride: base => ({ ...base, extensions: base.extensions.filter(e => !isOptchat(e.resolvedPath)) }),
-          extensionFactories: [pi => {
-            const provider = this.registry.getRegisteredProviderConfig(selected.provider);
-            if (provider) pi.registerProvider(selected.provider, provider);
-            // Same prompt as the main agent (AGENTS.md files, skills, cwd); only the OptChat preamble differs.
-            pi.on('before_agent_start', event => {
-              event.systemPromptOptions.customPrompt = `${SUBAGENT}\n\n${VIEW_DOC}`;
-              event.systemPromptOptions.sections.instructions = instructions;
-            });
-            pi.on('before_provider_request', (event, ctx) => ctx.model?.api === 'anthropic-messages' ? cachePayload(event.payload) : event.payload);
-          }],
-        });
-        await loader.reload();
-        const { session } = await (this.options.createSession ?? createAgentSession)({ cwd: directory, resourceLoader: loader, settingsManager,
-          model, thinkingLevel: selected.thinking, sessionManager: SessionManager.create(directory, join(this.profileDirectory, 'runs')),
-          customTools: [...memoryTools(() => this.memory), ...(depth < 3 ? this.delegationTools(id, directory) : []), this.parentTool(id, parentId, connected)],
-          excludeTools: depth < 3 ? [] : ['spawn', 'tell'],
-        });
-        await session.bindExtensions({});
+        const session = await this.open({ id, directory, depth, parentId, connected, provider: selected.provider, model, thinking: selected.thinking,
+          sessionManager: SessionManager.create(directory, join(this.profileDirectory, 'runs')) });
         const info: RunInfo = { id, task: task.task, cwd: directory, model: `${selected.provider}/${selected.model}`, thinking: session.thinkingLevel,
           parentSession: this.options.parentSession ?? '', parentId, depth, sessionFile: session.sessionFile, started: Date.now(), state: 'running', guidance: [], ...(connected ? { connected: true } : {}) };
         const live: LiveRun = { session, info, updated: Date.now(), tools: new Map(), pendingReports: [], pendingGuidance: [] };
@@ -159,6 +153,7 @@ export class Children {
       }
     } catch (error) {
       for (const child of launched) {
+        await this.shutdown(child.session); // Extensions such as MCP close their connections and stop their server processes.
         this.dispose(child.session); this.running.delete(child.info.id);
         child.info.state = 'failed'; child.info.ended = Date.now(); child.info.report = `Launch failed: ${String(error)}`;
         if (child.info.connected) child.info.handoff = { reason: signal?.aborted ? 'disconnected' : 'failed' };
@@ -169,7 +164,7 @@ export class Children {
     } finally { this.launching -= reserved; }
     // Each child reports independently. A slow sibling must not hold back a finished result.
     for (const live of launched) {
-      const work = this.execute(live, view).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
+      const work = this.execute(live, `${view}\n\nYour task:\n${live.info.task}`).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
         .finally(() => { this.completions.delete(work); this.changed(); });
       this.completions.add(work);
       live.completion = work;
@@ -177,15 +172,49 @@ export class Children {
     this.changed();
     return launched.map(c => c.info.id);
   }
+  /** Builds a child session with the same prompt, tools and extensions whether it is new or resumed. */
+  private async open(o: { id: string; directory: string; depth: number; parentId?: string; connected: boolean; provider: string; model: Model<Api>;
+    thinking?: ModelChoice['thinking']; sessionManager: SessionManager }) {
+    const { id, directory, depth, parentId, connected } = o;
+    const delegation = depth < 3 ? 'You may delegate parts of your assigned task with spawn when useful. Child reports arrive automatically after your current run ends; the harness keeps you alive to receive them. Never poll, sleep, or wait in a tool for children. Finish your current work and return; you will be prompted with their results. The profile allows 8 active agents total.' : 'You are at the maximum delegation depth. Complete your task with your own tools.';
+    const instructions = [this.instructions(), delegation, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_parent for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.'
+      : 'Use tell_parent only when your parent needs something now (a blocking question, an important early finding, or when asked to). Your final answer is delivered automatically; do not repeat it with tell_parent.'].filter(Boolean).join('\n\n');
+    // The user's settings list their installed packages; a copy in memory keeps the child from writing them back.
+    const settingsManager = SettingsManager.inMemory({ ...SettingsManager.create(directory, getAgentDir()).getSettings(), compaction: { enabled: false }, cacheWarming: 'off' });
+    const loader = new DefaultResourceLoader({ cwd: directory, agentDir: getAgentDir(), settingsManager,
+      noPromptTemplates: true,
+      extensionsOverride: base => ({ ...base, extensions: base.extensions.filter(e => !isOptchat(e.resolvedPath)) }),
+      extensionFactories: [...builtinExtensions(this.options.builtins?.() ?? []), pi => {
+        const provider = this.registry.getRegisteredProviderConfig(o.provider);
+        if (provider) pi.registerProvider(o.provider, provider);
+        // Same prompt as the main agent (AGENTS.md files, skills, cwd); only the OptChat preamble differs.
+        pi.on('before_agent_start', event => {
+          event.systemPromptOptions.customPrompt = `${SUBAGENT}\n\n${VIEW_DOC}`;
+          event.systemPromptOptions.sections.instructions = instructions;
+        });
+        pi.on('before_provider_request', (event, ctx) => ctx.model?.api === 'anthropic-messages' ? cachePayload(event.payload) : event.payload);
+      }],
+    });
+    await loader.reload();
+    const { session } = await (this.options.createSession ?? createAgentSession)({ cwd: directory, resourceLoader: loader, settingsManager,
+      model: o.model, thinkingLevel: o.thinking, sessionManager: o.sessionManager,
+      customTools: [...memoryTools(() => this.memory), ...(depth < 3 ? this.delegationTools(id, directory) : []), this.parentTool(id, parentId, connected)],
+      excludeTools: depth < 3 ? [] : ['spawn', 'tell'],
+    });
+    // Callers track the session only after this returns: clean up here if its extensions fail to start.
+    try { await session.bindExtensions({}); }
+    catch (error) { await this.shutdown(session); this.dispose(session); throw error; }
+    return session;
+  }
   private delegationTools(parentId: string, cwd: string) {
     return [{ name: 'spawn', label: 'Delegate task', description: 'Delegate parts of your task. Results arrive automatically after this run; never poll or sleep waiting. Maximum depth 3 and 8 active agents per profile.',
       parameters: Type.Object({ tasks: Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String({ description: CWD_DOC })) }), { minItems: 1, maxItems: 8 }) }),
       execute: async (_id: string, args: { tasks: { task: string; cwd?: string }[] }, signal?: AbortSignal) => result(`Started: ${(await this.spawn(args.tasks, cwd, signal, parentId)).join(', ')}. Results will arrive automatically.`),
-    }, { name: 'tell', label: 'Guide child', description: 'Send guidance to one of your direct children.',
+    }, { name: 'tell', label: 'Guide child', description: 'Send guidance to one of your direct children. A finished child is resumed with its earlier conversation, and its new report arrives automatically.',
       parameters: Type.Object({ id: Type.String(), message: Type.String() }),
       execute: async (_id: string, args: { id: string; message: string }) => {
         if (this.history.records.get(args.id)?.parentId !== parentId) throw new Error('You can only guide your own children.');
-        return result(await this.tell(args.id, args.message));
+        return result(await this.tell(args.id, args.message, 'manager', parentId));
       },
     }];
   }
@@ -207,16 +236,20 @@ export class Children {
       },
     };
   }
+  private async shutdown(session: AgentSession) {
+    try { await session.extensionRunner.emit({ type: 'session_shutdown', reason: 'quit' }); }
+    catch (error) { this.warn(`Subagent cleanup failed: ${String(error)}`); }
+  }
   private dispose(session: AgentSession) {
     try { session.dispose(); } catch (error) { this.warn(`Subagent cleanup failed: ${String(error)}`); }
   }
   private directChildren(id: string) { return [...this.running.values()].filter(c => c.info.parentId === id); }
-  private async execute(live: LiveRun, view: string) {
+  private async execute(live: LiveRun, prompt: string) {
     const { session, info } = live;
     try {
       if (info.connected) await this.report(`[${info.id}] User started a connected conversation in ${info.cwd}. That agent is handling this request with the user directly; don't do it yourself. Initial message: ${info.task}\n\nUse tell with this agent ID only if you know something it needs. It stays open between replies and sends a final handoff on completion or disconnect.`);
       if (this.closing || info.handoff) throw new Error('Conversation stopped before its first request.');
-      await session.prompt(`${view}\n\nYour task:\n${info.task}`);
+      await session.prompt(prompt);
       while (info.state !== 'stopping') {
         const last = session.messages.findLast(m => m.role === 'assistant');
         if (last?.role === 'assistant' && (last.stopReason === 'error' || last.stopReason === 'aborted')) break;
@@ -249,8 +282,7 @@ export class Children {
       await Promise.allSettled(children.flatMap(child => child.completion ? [child.completion] : []));
       info.ended = Date.now();
       for (const g of info.guidance) if (g.state === 'queued') g.state = 'undelivered';
-      try { await session.extensionRunner.emit({ type: 'session_shutdown', reason: 'quit' }); }
-      catch (error) { this.warn(`Subagent cleanup failed: ${String(error)}`); }
+      await this.shutdown(session);
       // A failed dispose must neither keep the slot taken nor drop the report below.
       this.dispose(session); this.running.delete(info.id);
     }
@@ -276,9 +308,12 @@ export class Children {
       this.warn(`Subagent report saved but could not wake the parent: ${String(error)}`);
     }
   }
-  async tell(id: string, message: string, source: 'manager' | 'user' = 'manager') {
+  /** `caller` is the agent sending a manager message: undefined for the main agent, else the parent subagent's ID. */
+  async tell(id: string, message: string, source: 'manager' | 'user' = 'manager', caller?: string) {
     const live = this.running.get(id);
-    if (!live || !['running', 'waiting'].includes(live.info.state)) throw new Error(`No running subagent ${id}.`);
+    if (!live && source === 'manager' && this.history.records.has(id)) return this.resume(id, message, caller);
+    if (live && !['running', 'waiting'].includes(live.info.state)) throw new Error(`${id} is finishing. Its report will arrive on its own${live.info.connected || source === 'user' ? '' : '; tell it again after that to resume it'}.`);
+    if (!live) throw new Error(`No running subagent ${id}.`);
     const text = live.info.connected && source === 'manager' ? `[Main agent guidance]\n${message.trim()}` : message.trim(); if (!message.trim()) throw new Error('Message is empty.');
     if (source === 'user') this.memory.append('user', `Direct guidance to subagent [${id}]: ${text}`);
     const guidance: RunInfo['guidance'][number] = { text, date: Date.now(), state: 'queued', from: source };
@@ -290,6 +325,54 @@ export class Children {
     catch (error) { guidance.state = 'undelivered'; this.save(live.info); throw error; }
     return 'Message queued for the next tool boundary.';
   }
+  /** Reopens a finished child from its saved transcript, same ID, parent and model, and gives it a new message. */
+  private async resume(id: string, message: string, caller: string | undefined) {
+    const run = this.history.records.get(id)!, text = message.trim();
+    if (!text) throw new Error('Message is empty.');
+    if (run.connected) throw new Error(`${id} was a connected conversation with the user. It has ended and its handoff was delivered, so it cannot be resumed. Spawn a new subagent instead.`);
+    if (!['completed', 'failed', 'stopped', 'interrupted'].includes(run.state) || this.resuming.has(id)) throw new Error(`${id} is still finishing. Its report will arrive on its own.`);
+    if (run.parentId !== caller) {
+      if (!run.parentId) throw new Error(`Only the main agent can resume ${id}.`);
+      const parent = this.running.get(run.parentId);
+      throw new Error(parent && ['running', 'waiting'].includes(parent.info.state) ? `Only ${id}'s parent ${run.parentId} can resume it. Ask ${run.parentId} with tell.`
+        : `Only ${id}'s parent ${run.parentId} can resume it, and that parent is no longer running. Resume ${run.parentId} instead, or spawn a new subagent.`);
+    }
+    if (this.closing) throw new Error('Profile is closing.');
+    if (this.running.size + this.launching + 1 > 8) throw new Error(`Profile limit: at most 8 active agents, including parents and descendants. ${id} can be resumed when one finishes.`);
+    let manager: SessionManager | undefined;
+    try { if (run.sessionFile && existsSync(run.sessionFile)) manager = SessionManager.open(run.sessionFile); } catch { manager = undefined; }
+    if (!manager?.getEntries().some(e => e.type === 'message')) throw new Error(`The saved transcript of ${id} is missing or unreadable, so it cannot be resumed. Spawn a fresh subagent and give it the context it needs.`);
+    if (!existsSync(run.cwd) || !statSync(run.cwd).isDirectory()) throw new Error(`${id}'s directory ${run.cwd} no longer exists, so it cannot be resumed. Spawn a fresh subagent instead.`);
+    const slash = run.model.indexOf('/'), provider = run.model.slice(0, slash);
+    const model = slash > 0 ? this.registry.find(provider, run.model.slice(slash + 1)) : undefined;
+    if (!model) throw new Error(`${id}'s model ${run.model} is not available, so it cannot be resumed. Spawn a fresh subagent instead.`);
+    this.launching++; this.resuming.add(id);
+    let reserved = true;
+    try {
+      // No thinking level: the session restores the one it ran with.
+      const session = await this.open({ id, directory: run.cwd, depth: run.depth, parentId: run.parentId, connected: false, provider, model, sessionManager: manager });
+      // stop() cannot see this child until it is registered, so a parent stopped meanwhile must cancel it here.
+      const parent = run.parentId ? this.running.get(run.parentId) : undefined;
+      if (this.closing || run.parentId && (!parent || !['running', 'waiting'].includes(parent.info.state))) {
+        await this.shutdown(session); this.dispose(session); throw new Error('Parent or profile is stopping.');
+      }
+      // The finished record stays untouched (and resumable) unless the new one is saved.
+      const { ended: _ended, ...rest } = run;
+      const info: RunInfo = { ...rest, state: 'running', started: Date.now(), parentSession: this.options.parentSession ?? run.parentSession,
+        guidance: [...run.guidance, { text, date: Date.now(), state: 'queued', from: 'manager' }] };
+      try { this.save(info); } catch (error) { this.history.records.set(id, run); await this.shutdown(session); this.dispose(session); throw error; }
+      const live: LiveRun = { session, info, updated: Date.now(), tools: new Map(), pendingReports: [], pendingGuidance: [] };
+      this.running.set(id, live);
+      this.launching--; reserved = false;
+      session.subscribe(event => this.observe(live, event));
+      const work = this.execute(live, text).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
+        .finally(() => { this.completions.delete(work); this.changed(); });
+      this.completions.add(work);
+      live.completion = work;
+    } finally { if (reserved) this.launching--; this.resuming.delete(id); }
+    this.changed();
+    return `${id} had finished, so I resumed it with its earlier conversation. Its new report will come back on its own.`;
+  }
   async finish(id: string, reason: FinishReason) {
     const live = this.running.get(id);
     if (live?.info.connected) {

package/src/compactor.ts

@@ -3,32 +3,71 @@ import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { COMPACT } from './prompts.ts';
 import { bytes, NODE, type Compressor } from './memory.ts';
-import { cachePayload } from './cache.ts';
+import { cachePayload, splitView } from './cache.ts';
 import { IMPORT_GUIDANCE } from './import/guidance.ts';
 
 export interface ModelChoice { provider: string; model: string; thinking: ThinkingLevel }
 const scaleBase = 'user: Keep work and personal memory separate; use a binary summary tree and inspect original messages before acting. talk: Implemented the append-only log with durable writes and a stable view. echo: Checked caching, chronological summaries, cancellation, and profile locks. user: Main agent uses Opus; compactor uses Sonnet at medium effort. work: Worker completed the parser; tests cover invalid records and repeated imports. talk: The browser opens original messages, preserving dates and sources.';
 export const SCALE = scaleBase.padEnd(NODE, '.').slice(0, NODE);
+/** The model is asked for 512 bytes; a small overshoot costs less view space than a retry costs money. */
+export const ACCEPTED = NODE * 1.25;
+const WARM_MS = 4 * 60_000; // Anthropic's short cache lives 5 minutes from its last use.
+
+/** Parallel calls can't read a cache entry that isn't written yet, so one call primes a cold prefix and the rest wait until it answers. */
+function primeFirst() {
+  const warm = new Map<string, number | Promise<void>>();
+  return async (prefix: string, signal: AbortSignal) => {
+    for (let state = warm.get(prefix); state !== undefined; state = warm.get(prefix)) {
+      if (typeof state === 'number') { if (Date.now() - state < WARM_MS) break; warm.delete(prefix); continue; }
+      // A cancelled waiter leaves at once instead of waiting for someone else's primer.
+      signal.throwIfAborted();
+      let wake = () => {};
+      const aborted = new Promise<void>(resolve => { wake = resolve; });
+      signal.addEventListener('abort', wake, { once: true });
+      await Promise.race([state, aborted]);
+      signal.removeEventListener('abort', wake);
+      signal.throwIfAborted();
+    }
+    let release = () => {};
+    const pending = warm.has(prefix) ? undefined : new Promise<void>(resolve => { release = resolve; });
+    if (pending) warm.set(prefix, pending);
+    return (ok: boolean) => {
+      if (ok) { for (const [k, at] of warm) if (typeof at === 'number' && Date.now() - at >= WARM_MS) warm.delete(k); warm.set(prefix, Date.now()); }
+      else if (warm.get(prefix) === pending) warm.delete(prefix);
+      release();
+    };
+  };
+}
 export function createCompressor(registry: ModelRegistry, choice: () => ModelChoice,
   onUsage: (message: AssistantMessage) => void = () => {}): Compressor {
+  const gate = primeFirst();
   return async (input, signal) => {
     const selected = choice();
     const model = registry.find(selected.provider, selected.model);
     if (!model) throw new Error(`Compactor model unavailable: ${selected.provider}/${selected.model}. Use /optchat model.`);
     const step = `${input.historical ? IMPORT_GUIDANCE + '\n\n' : ''}For scale, this line is exactly 512 bytes:\n${SCALE}\n\n${input.merge ? 'Merge these two lines into one' : 'Compress this message into one line'}, in at most 512 bytes:\n${input.source}`;
     const messages: Message[] = [{ role: 'user', content: [{ type: 'text', text: input.context }, { type: 'text', text: step }], timestamp: Date.now() }];
+    const view = splitView(input.context);
+    const prefix = model.api === 'anthropic-messages' && view.length > 1 ? `${model.provider}/${model.id}/${selected.thinking}\n${view.slice(0, -1).join('')}` : undefined;
     const tries: string[] = [];
     for (let attempt = 0; attempt < 5; attempt++) {
-      const reply = await registry.streamSimple(model, { systemPrompt: COMPACT, messages }, {
-        reasoning: selected.thinking === 'off' ? undefined : selected.thinking, signal, cacheRetention: 'short',
-        onPayload: payload => model.api === 'anthropic-messages' ? cachePayload(payload) : payload,
-      }).result();
+      const warmed = prefix ? await gate(prefix, signal) : () => {};
+      let reply: AssistantMessage;
+      try {
+        const stream = registry.streamSimple(model, { systemPrompt: COMPACT, messages }, {
+          reasoning: selected.thinking === 'off' ? undefined : selected.thinking, signal, cacheRetention: 'short',
+          onPayload: payload => model.api === 'anthropic-messages' ? cachePayload(payload) : payload,
+        });
+        // The cache entry is usable once the model starts answering.
+        for await (const event of stream) if (event.type !== 'start') { warmed(event.type !== 'error'); break; }
+        reply = await stream.result();
+      } finally { warmed(false); }
       onUsage(reply);
       if (reply.stopReason === 'error' || reply.stopReason === 'aborted') throw new Error(reply.errorMessage ?? `Compactor ${reply.stopReason}`);
       const line = reply.content.filter(c => c.type === 'text').map(c => c.text).join('').trim();
       if (!line) throw new Error('Compactor returned no text.');
       tries.push(line);
-      if (bytes(line) <= NODE) break;
+      if (bytes(line) <= ACCEPTED) break;
       messages.push(reply);
       const cut = Buffer.from(line).subarray(0, NODE).toString('utf8').replace(/\uFFFD$/, '');
       messages.push({ role: 'user', content: `That line is ${bytes(line)} bytes; the limit is 512. It must end where it is cut here:\n${cut}| ← LIMIT`, timestamp: Date.now() });

package/src/index.ts

@@ -14,7 +14,7 @@ import { cachePayload, record } from './cache.ts';
 import { asUser, boundedMessage, buildContext, logMessage, previousExchange, REPORT_TYPE, RUN_BOUNDARY, textContent, typedText } from './transcript.ts';
 import { registerReportRenderer } from './report-message.ts';
 import { memoryTools, result } from './tools.ts';
-import { Children, CWD_DOC } from './agents.ts';
+import { Children, CWD_DOC, loadedBuiltins } from './agents.ts';
 import { exportBrowser } from './browser.ts';
 import { Inbox } from './inbox.ts';
 import { checkpoint } from './checkpoint.ts';
@@ -147,7 +147,7 @@ export default function optchat(pi: ExtensionAPI) {
       const recovered = pendingImport(dir) ? 0 : inbox.recover(memory);
       if (recovered) ctx.ui.notify(`Recovered ${recovered} unanswered inputs into ${name}'s memory. Ask to continue them when ready.`, 'info');
       const children = new Children(memory, ctx.modelRegistry, () => config.subagent, () => `${instructions(dir)}\n\n${IMPORT_GUIDANCE}`,
-        deliverReport, text => ctx.ui.notify(text, 'error'), dir, { parentSession: sessionId, usage,
+        deliverReport, text => ctx.ui.notify(text, 'error'), dir, { parentSession: sessionId, usage, builtins: () => loadedBuiltins(pi),
           summarizeHandoff: createHandoffSummarizer(ctx.modelRegistry, () => config.compactor, message => usage.compression(message, 'compactor', sessionId)) });
       const loggedReports = new Set(memory.root.map(e => e.receipt));
       reports = saved.filter((s): s is string => typeof s === 'string' && !loggedReports.has(reportReceipt(s)));
@@ -321,7 +321,7 @@ export default function optchat(pi: ExtensionAPI) {
       return result(`Started: ${ids.join(', ')}. Reports will arrive automatically.`);
     },
   });
-  pi.registerTool({ name: 'tell', label: 'Tell background agent', description: 'Send a message to a running subagent at its next tool boundary.',
+  pi.registerTool({ name: 'tell', label: 'Tell background agent', description: 'Send a message to a subagent. A running one gets it at its next tool boundary. A finished one you started is resumed with its earlier conversation, and its new report arrives automatically.',
     parameters: Type.Object({ id: Type.String(), message: Type.String() }),
     async execute(_id, args) { return result(await required().children.tell(args.id, args.message)); },
   });

package/src/inspector.ts

@@ -2,11 +2,23 @@ import { matchesKey, sliceByColumn, truncateToWidth, visibleWidth, wrapTextWithA
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type { Children } from './agents.ts';
 import { isActiveRun } from './runs.ts';
-import { ranges, summarizeUsage, type UsageLedger, type UsageRange } from './usage.ts';
+import type { Usage } from '@earendil-works/pi-ai';
+import { ranges, summarizeUsage, type UsageLedger, type UsageRange, type UsageRole } from './usage.ts';
 
 export const clean = (text: string) => text.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '').replace(/\t/g, '  ');
 export const oneLine = (text: string) => clean(text).replace(/\n/g, ' ');
 export const count = (n: number) => n.toLocaleString('en-US');
+const units = ['', 'k', 'M', 'B'];
+/** 950, 12.3k, 164k, 2.4M: enough precision to compare rows at a glance. A value that rounds to 1000 moves up a unit. */
+export const short = (n: number) => {
+  let unit = 0, value = n;
+  const round = (v: number) => v >= 100 || !unit ? Math.round(v) : Number(v.toFixed(1));
+  while (unit < units.length - 1 && round(value) >= 1000) { value /= 1000; unit++; }
+  return `${round(value)}${units[unit]}`;
+};
+const dollars = (n: number) => `$${n.toFixed(2)}`;
+const cached = (u: Usage) => { const input = u.input + u.cacheRead + u.cacheWrite; return `${input ? Math.round(100 * u.cacheRead / input) : 0}%`; };
+const roleNames: Record<UsageRole, string> = { main: 'main', subagent: 'subagents', compactor: 'compactor', import: 'import' };
 export const elapsed = (ms: number) => ms < 60_000 ? `${Math.max(0, Math.floor(ms / 1000))}s` : `${Math.floor(ms / 60_000)}m ${Math.floor(ms / 1000) % 60}s`;
 /** Shortens plain text with an ellipsis, preferring a word boundary. */
 export function fit(text: string, width: number) {
@@ -23,7 +35,7 @@ const spread = (left: string, right: string, width: number) => {
 export type InspectorPage = 'agents' | 'usage';
 /** Closing the panel either picks the subagent model or opens one agent's conversation. */
 export type InspectorAction = 'model' | { open: string };
-type Tone = 'accent' | 'muted' | 'dim' | 'error' | 'border';
+type Tone = 'accent' | 'muted' | 'dim' | 'error' | 'warning' | 'border';
 interface Options {
   profile: string; session: string; children: Children; usage: UsageLedger; page: InspectorPage;
   rows: () => number; redraw: () => void; done: (action?: InspectorAction) => void;
@@ -96,24 +108,34 @@ export class Inspector implements Component, Focusable {
       this.scroll = Math.max(0, Math.min(this.scroll, this.lineCount - this.height));
     }
   }
-  private usageLines() {
-    const { usage, session, context } = this.options;
+  /** Period tabs, one headline, then an aligned table with a row per role and model. */
+  private usageLines(width: number) {
+    const { usage, session, context, color } = this.options;
     const entries = usage.select(this.range, session);
     const { total, groups } = summarizeUsage(entries);
-    const input = total.input + total.cacheRead + total.cacheWrite;
-    const lines = [`← → period: ${this.range}`, '', `Total processed: ${count(total.totalTokens)} tokens · ${entries.length} usage records`,
-      `Input: ${count(input)} · Output: ${count(total.output)}`,
-      `Cache read: ${count(total.cacheRead)} · Cache write: ${count(total.cacheWrite)} · Hit rate: ${input ? (100 * total.cacheRead / input).toFixed(1) : '0'}%`,
-      `Estimated API-equivalent cost: $${total.cost.total.toFixed(4)}`, '',
-      'ROLE / MODEL — input · output · cache read/write · estimated cost'];
-    for (const g of groups) lines.push(`${g.role} / ${g.model}\n  ${count(g.usage.input)} uncached input · ${count(g.usage.output)} out · ${count(g.usage.cacheRead)}/${count(g.usage.cacheWrite)} cache · $${g.usage.cost.total.toFixed(4)} · ${g.requests} records`);
+    // No-break spaces keep a label like "Last 7 days" on one line when the tabs wrap.
+    const tabs = ranges.map(r => r.replaceAll(' ', '\u00a0')).map((r, i) => ranges[i] === this.range ? color('accent', `[${r}]`) : color('dim', r)).join('  ');
+    const lines = [...wrapTextWithAnsi(tabs, width), ''];
+    if (!entries.length) lines.push(color('muted', 'No usage in this period.'));
+    else {
+      lines.push(`${color('accent', dollars(total.cost.total))} estimated · ${short(total.totalTokens)} tokens · ${cached(total)} cached`, '');
+      const order = ['main', 'subagent', 'compactor', 'import'] as const;
+      const sorted = groups.sort((a, b) => order.indexOf(a.role) - order.indexOf(b.role) || b.usage.cost.total - a.usage.cost.total);
+      const rows = sorted.map((g, i) => [i && sorted[i - 1].role === g.role ? '' : roleNames[g.role], oneLine(g.model), dollars(g.usage.cost.total),
+        `${total.cost.total ? Math.round(100 * g.usage.cost.total / total.cost.total) : 0}%`, short(g.usage.output), cached(g.usage)]);
+      const header = ['', 'model', 'cost', 'share', 'out', 'cached'];
+      const widths = header.map((h, c) => Math.max(h.length, ...rows.map(r => r[c].length)));
+      // The model column goes first when the screen is too narrow for every column.
+      const columns = widths.reduce((sum, w) => sum + w + 2, 0) - 2 <= width ? [0, 1, 2, 3, 4, 5] : [0, 2, 3, 4, 5];
+      const line = (cells: string[]) => columns.map(c => c < 2 ? cells[c].padEnd(widths[c]) : cells[c].padStart(widths[c])).join('  ').trimEnd();
+      lines.push(color('dim', line(header)), ...rows.map(r => {
+        const text = line(r); return color('muted', text.slice(0, widths[0])) + text.slice(widths[0]);
+      }));
+    }
     const current = context();
-    lines.push('', `Current parent context (Pi estimate): ${current == null ? 'unavailable' : `${count(current)} tokens`} — separate from cumulative usage.`,
-      'Costs use model API rates when available; not your subscription bill or remaining allowance.',
-      'Usage updates when responses finish. Tool overhead may be a usage record without a request count.',
-      'Main tracking starts with this version; the resumed parent session and saved children are backfilled.',
-      'Older compactor/child records without a parent session appear only in date-based totals.', ...usage.warnings);
-    return lines.join('\n');
+    if (current != null) lines.push('', `${color('muted', 'Context now')} ${short(current)} tokens`);
+    lines.push('', color('dim', 'Estimated at API prices, not your subscription bill.'), ...usage.warnings.map(w => color('warning', w)));
+    return lines.flatMap(l => l ? wrapTextWithAnsi(l, width) : ['']);
   }
   render(width: number): string[] {
     const { color, children, profile } = this.options;
@@ -121,11 +143,11 @@ export class Inspector implements Component, Focusable {
     let title = `OptChat · ${profile} · ${this.page === 'usage' ? 'Usage' : 'Agents'}`;
     let info: string, body: string[], hint: string;
     if (this.page === 'usage') {
-      const lines = wrapTextWithAnsi(clean(this.usageLines()), inner); this.lineCount = lines.length;
+      const lines = this.usageLines(inner); this.lineCount = lines.length;
       this.scroll = Math.max(0, Math.min(this.scroll, lines.length - this.height));
       body = lines.slice(this.scroll, this.scroll + this.height);
       info = `${this.scroll + 1}–${Math.min(this.scroll + this.height, lines.length)} / ${lines.length}`;
-      hint = '←→ period · ↑↓/PgUp/PgDn scroll · Tab agents · Esc close';
+      hint = '←→ period · ↑↓ scroll · Tab agents · Esc close';
     } else {
       const list = children.history.list();
       if (!this.selected) this.selected = list[0]?.id;

package/src/usage.ts

@@ -91,13 +91,13 @@ export class UsageLedger {
 }
 
 export function summarizeUsage(entries: UsageEntry[]) {
-  const total = emptyUsage(), groups = new Map<string, { role: UsageRole; model: string; requests: number; usage: Usage }>();
+  const total = emptyUsage(), groups = new Map<string, { role: UsageRole; model: string; usage: Usage }>();
   for (const entry of entries) {
-    const model = entry.provider ? `${entry.provider}/${entry.model}` : entry.model;
-    const key = `${entry.role}:${model}`;
+    // By model name alone: older compactor records lack a provider and must still land in the same row.
+    const key = `${entry.role}:${entry.model}`;
     let group = groups.get(key);
-    if (!group) { group = { role: entry.role, model, requests: 0, usage: emptyUsage() }; groups.set(key, group); }
-    group.requests++; addUsage(group.usage, entry.usage); addUsage(total, entry.usage);
+    if (!group) { group = { role: entry.role, model: entry.model, usage: emptyUsage() }; groups.set(key, group); }
+    addUsage(group.usage, entry.usage); addUsage(total, entry.usage);
   }
   return { total, groups: [...groups.values()] };
 }