pi-optchat 0.6.4 → 0.6.6

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.
@@ -137,7 +139,7 @@ See OpenAI's guides on [exporting ChatGPT data](https://help.openai.com/en/artic
 
 ## Connected windows
 
-Each profile is locked to one Pi process. If you open the same profile in a second terminal, Pi offers to connect it to the original window as a subagent.
+Each profile is locked to one Pi process. If you open the same profile in a second terminal, Pi offers to connect it to the original window as a subagent, or to go back to the profile picker.
 
 - Your first message starts a subagent in the second window's working directory. Later messages continue the same conversation.
 - The window looks like a normal Pi chat: replies, tool calls with their output and running time, the working spinner, and reports from the subagent's own agents in the dark box. Ctrl+O expands tool output.
@@ -181,7 +183,7 @@ To delete a profile, delete its folder. Your original Pi sessions are kept in Pi
 - **Images** are available during the current run but stored in memory as text placeholders.
 - **Pi's auto-compaction is off.** A single very long run can still hit the model's context limit; stop it and continue in a new turn.
 - **Restarts**: unsent inputs are recovered into memory, and pending subagent reports are delivered. Interrupted subagents are not restarted.
-- **Skill and template inputs** can occasionally be recovered as an unanswered input after a crash, because Pi expands them after the input journal records them. Plain text chat is unaffected.
+- **Prompt-template inputs** can be saved twice: expanded, and later in their original form as an unanswered input, because Pi expands them after the input journal records them. Skill commands (`/skill:name`) are matched back to their journaled input and don't have this problem. Plain text chat is unaffected.
 
 ## How it differs from the recipe
 

package/package.json

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

package/src/agents.ts

@@ -1,8 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, getAgentDir, type AgentSession, type AgentSessionEvent, type ModelRegistry } from '@earendil-works/pi-coding-agent';
+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 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';
@@ -21,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.
@@ -28,17 +33,37 @@ const packageName = (path: string): string | undefined => {
   for (let dir = dirname(path); dir !== dirname(dir); dir = dirname(dir)) {
     const manifest = join(dir, 'package.json');
     if (!existsSync(manifest)) continue;
-    const data: unknown = JSON.parse(readFileSync(manifest, 'utf8'));
-    return data && typeof data === 'object' && 'name' in data && typeof data.name === 'string' ? data.name : undefined;
+    try {
+      const data: unknown = JSON.parse(readFileSync(manifest, 'utf8'));
+      return data && typeof data === 'object' && 'name' in data && typeof data.name === 'string' ? data.name : undefined;
+    } catch { return undefined; } // A broken manifest is not OptChat's and must not block every spawn.
   }
 };
+/** A task's cwd may start with `~` and may be relative to the spawning agent's directory. */
+export const taskDirectory = (cwd: string, path = '.', windows = process.platform === 'win32') =>
+  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,
@@ -92,6 +117,7 @@ export class Children {
     } catch (error) { this.warn(`Could not record subagent activity: ${String(error)}`); }
   }
   async spawn(tasks: { task: string; cwd?: string }[], cwd: string, signal?: AbortSignal, parentId?: string, connected = false) {
+    for (const directory of tasks.map(t => taskDirectory(cwd, t.cwd))) if (!existsSync(directory) || !statSync(directory).isDirectory()) throw new Error(`No such directory: ${directory}`);
     if (this.closing) throw new Error('Profile is closing.');
     this.settling++;
     try { await this.memory.settle(signal); } finally { this.settling--; }
@@ -113,33 +139,9 @@ export class Children {
       for (const task of tasks) {
         signal?.throwIfAborted();
         if (cancelled()) throw new Error('Parent or profile is stopping.');
-        const id = randomUUID().slice(0, 8), directory = task.cwd ?? 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 id = randomUUID().slice(0, 8), directory = taskDirectory(cwd, task.cwd);
+        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: [] };
@@ -151,7 +153,8 @@ export class Children {
       }
     } catch (error) {
       for (const child of launched) {
-        child.session.dispose(); this.running.delete(child.info.id);
+        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' };
         this.save(child.info);
@@ -161,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;
@@ -169,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()) }), { minItems: 1, maxItems: 8 }) }),
+      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));
       },
     }];
   }
@@ -199,13 +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;
@@ -238,9 +282,9 @@ 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)}`); }
-      finally { session.dispose(); this.running.delete(info.id); }
+      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);
     }
     if (info.connected) {
       info.handoff ??= { reason: 'failed' };
@@ -264,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 };
@@ -278,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/inbox.ts

@@ -23,8 +23,14 @@ export class Inbox {
     const item = { id: randomUUID(), text, date: new Date().toISOString() };
     this.items.push(item); this.save(); return item.id;
   }
-  claim(text: string) {
-    const item = this.items.find(i => !this.claimed.has(i.id) && i.text === text);
+  claim(text: string) { return this.claimWhere(i => i.text === text); }
+  /** Pi expands `/skill:name args` after the input is journaled; match the expansion back to that input. */
+  claimSkill(name: string, args = '') {
+    const command = `/skill:${name}`;
+    return this.claimWhere(i => i.text.startsWith(command) && /^(\s|$)/.test(i.text.slice(command.length)) && i.text.slice(command.length).trim() === args);
+  }
+  private claimWhere(match: (item: Arrival) => boolean) {
+    const item = this.items.find(i => !this.claimed.has(i.id) && match(i));
     if (!item) return undefined;
     this.claimed.add(item.id); return item.id;
   }

package/src/index.ts

@@ -4,17 +4,17 @@ import { join } from 'node:path';
 import { hostname } from 'node:os';
 import { createHash } from 'node:crypto';
 import type { AgentMessage, ThinkingLevel } from '@earendil-works/pi-agent-core';
-import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { parseSkillBlock, type ExtensionAPI, type ExtensionContext, type ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { Memory } from './memory.ts';
 import { createCompressor } from './compactor.ts';
 import { atomicWrite, createProfile, instructions, lastProfile, listProfiles, loadConfig, lockProfile, profilePath, rememberProfile, saveConfig, ProfileBusyError, type ProfileConfig } from './profiles.ts';
 import { MASTER, VIEW_DOC } from './prompts.ts';
 import { cachePayload, record } from './cache.ts';
-import { asUser, boundedMessage, buildContext, logMessage, previousExchange, REPORT_TYPE, RUN_BOUNDARY, textContent } from './transcript.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 } 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';
@@ -114,6 +114,7 @@ export default function optchat(pi: ExtensionAPI) {
       untitle?.(); untitle = undefined; title.clear(); working = false;
     }
   };
+  const CONNECT = 'Start a connected subagent conversation here', BACK = 'Back';
   const chooseProfile = async (ctx: ExtensionContext): Promise<string | undefined> => {
     if (!ctx.hasUI) return undefined;
     const names = listProfiles(), last = lastProfile();
@@ -146,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)));
@@ -175,20 +176,28 @@ export default function optchat(pi: ExtensionAPI) {
 
   pi.on('session_start', async (_event, ctx) => {
     stopping = false;
-    const saved = ctx.sessionManager.getEntries().find(e => e.type === 'custom' && e.customType === binding);
+    const entries = ctx.sessionManager.getEntries();
+    const saved = entries.findLast(e => e.type === 'custom' && e.customType === binding);
     const boundName = saved?.type === 'custom' && record(saved.data) && typeof saved.data.name === 'string' ? saved.data.name : undefined;
+    // A session with conversation in it belongs to its profile. One that is only bound (a fresh `/optchat profile` session) may still pick another.
+    const settled = boundName !== undefined && entries.some(e => e.type === 'message' || e.type === 'custom_message');
     const flag = pi.getFlag('optchat-profile');
     try {
       if (boundName && typeof flag === 'string' && flag !== boundName) throw new Error(`Session belongs to ${boundName}; cannot resume it as ${flag}.`);
-      const name = boundName ?? (typeof flag === 'string' ? flag : await chooseProfile(ctx));
-      if (!name) { status(ctx); return; }
-      try { await openProfile(name, ctx); }
-      catch (error) {
-        if (!(error instanceof ProfileBusyError) || ctx.mode !== 'tui') throw error;
-        if (!await ctx.ui.confirm('Profile open in another window', `${error.owner}\nStart a connected subagent conversation here?`)) throw error;
-        remote = await openConnectedWindow(pi, ctx, name, text => title.show(t => ctx.ui.setTitle(t), text)); fault = undefined;
+      let name = boundName ?? (typeof flag === 'string' ? flag : await chooseProfile(ctx));
+      for (;;) {
+        if (!name) { status(ctx); return; }
+        try { await openProfile(name, ctx); break; }
+        catch (error) {
+          if (!(error instanceof ProfileBusyError) || ctx.mode !== 'tui') throw error;
+          // A resumed conversation already belongs to this profile, so another profile needs a new session (/optchat profile).
+          const choice = await ctx.ui.select(`${name} is open in another window\n${error.owner}`, settled ? [CONNECT] : [CONNECT, BACK]);
+          if (choice === CONNECT) { remote = await openConnectedWindow(pi, ctx, name, text => title.show(t => ctx.ui.setTitle(t), text)); fault = undefined; break; }
+          if (choice !== BACK) throw error;
+          name = await chooseProfile(ctx);
+        }
       }
-      if (!boundName) pi.appendEntry(binding, { name });
+      if (name !== boundName) pi.appendEntry(binding, { name });
     } catch (error) {
       if (active) await stop().catch(() => {});
       fault = errorText(error); ctx.ui.notify(fault, 'error');
@@ -243,7 +252,10 @@ export default function optchat(pi: ExtensionAPI) {
         const text = textContent(message.content);
         if (reports.includes(text)) receipts.set(message, reportReceipt(text));
         else {
-          let receipt = active.inbox.claim(text);
+          // The inbox journaled the typed input: match without image placeholders or Pi's image notes.
+          const typed = typedText(message.content), skill = parseSkillBlock(typed.bare);
+          let receipt = active.inbox.claim(typed.text) ?? active.inbox.claim(typed.bare)
+            ?? (skill ? active.inbox.claimSkill(skill.name, skill.userMessage) : undefined);
           if (!receipt) { active.inbox.record(text); receipt = active.inbox.claim(text); }
           if (receipt) receipts.set(message, receipt);
         }
@@ -302,14 +314,14 @@ export default function optchat(pi: ExtensionAPI) {
   registerReportRenderer(pi);
   for (const tool of memoryTools(() => required().memory)) pi.registerTool(tool);
   pi.registerTool({ name: 'spawn', label: 'Spawn background agents',
-    description: 'Start background subagents, returning IDs immediately. Use only when the user asks. Each receives the current memory view and read-only zoom/date. Children may delegate two more levels; the whole profile allows 8 active agents. Completion reports arrive automatically; never poll or sleep waiting for them.',
-    parameters: Type.Object({ tasks: Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String()) }), { minItems: 1, maxItems: 8 }) }),
+    description: 'Start background subagents, returning IDs immediately. Use only when the user asks. Give each task the cwd of the project it works on, so the subagent starts there with that project\'s AGENTS.md. Each receives the current memory view and read-only zoom/date. Children may delegate two more levels; the whole profile allows 8 active agents. Completion reports arrive automatically; never poll or sleep waiting for them.',
+    parameters: Type.Object({ tasks: Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String({ description: CWD_DOC })) }), { minItems: 1, maxItems: 8 }) }),
     async execute(_id, args, signal, _update, ctx) {
       const ids = await required().children.spawn(args.tasks, ctx.cwd, signal); status(ctx);
       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/memory.ts

@@ -12,10 +12,12 @@ export interface Part { l: number; i: number }
 export interface Summary extends Part { text: string; size: number }
 export interface Compression { context: string; source: string; merge: boolean; historical?: boolean }
 export type Compressor = (input: Compression, signal: AbortSignal) => Promise<string>;
-const key = ({ l, i }: Part) => `${l}:${i}`;
+const key = ({ l, i }: Part) => l * 2 ** 40 + i;
+const UNBUILT = '(not summarized yet: zoom it)';
 export const start = ({ l, i }: Part) => i * 2 ** l;
 export const end = (part: Part) => start(part) + 2 ** part.l;
 export const bytes = (s: string) => Buffer.byteLength(s, 'utf8');
+const UNBUILT_BYTES = bytes(UNBUILT);
 export const flat = (s: string) => s.replace(/[\r\n]+/g, ' ');
 export function cap(text: string, limit = CAP) {
   if (text.length <= limit) return text;
@@ -68,13 +70,17 @@ function isSummary(value: unknown): value is Summary {
 /** The log is authoritative. The tree and monotonically coarsening view follow recipe §§2–6. */
 export class Memory {
   readonly root: Entry[] = [];
-  readonly tree = new Map<string, Summary>();
+  readonly tree = new Map<number, Summary>();
   readonly view: Part[] = [];
   private readonly events = new EventEmitter();
   private readonly controller = new AbortController();
-  private readonly busy = new Map<string, Promise<void>>();
-  private readonly retryAt = new Map<string, number>();
-  private readonly reported = new Set<string>();
+  private readonly busy = new Map<number, Promise<void>>();
+  private readonly retryAt = new Map<number, number>();
+  private readonly reported = new Set<number>();
+  private viewBytes = 0;
+  private leaves = 0;
+  /** Per level, every node below this index is built. */
+  private readonly low: number[] = [];
   private retryTimer?: ReturnType<typeof setTimeout>;
   private scheduled = false;
   private stopped = false;
@@ -91,40 +97,53 @@ export class Memory {
     for (const value of records(join(directory, 'tree'), warn)) {
       if (!isSummary(value) || value.l < 0 || value.i < 0 || end(value) > this.root.length)
         throw new Error('Invalid OptChat summary record.');
+      if (value.l === 0 && !this.tree.has(key(value))) this.leaves++;
       this.tree.set(key(value), { ...value, size: bytes(value.text) });
     }
     // Fold history in order; do not retile the entire log on each turn.
-    for (let i = 0; i < this.root.length; i++) { this.view.push({ l: 0, i }); this.fit(i + 1); }
+    for (let i = 0; i < this.root.length; i++) { this.push(i); this.fit(i + 1); }
     this.schedule();
   }
   append(kind: Kind, text: string, date = new Date().toISOString(), receipt?: string) {
     if (this.stopped) throw new Error('Memory is closed.');
     const entry: Entry = { i: this.root.length, kind, text, date, size: bytes(`${kind}: ${text}`), ...(receipt ? { receipt } : {}) };
     appendJson(join(this.directory, 'main', `${localDay()}.jsonl`), entry);
-    this.root.push(entry); this.view.push({ l: 0, i: entry.i }); this.fit(); this.schedule();
+    this.root.push(entry); this.push(entry.i); this.fit(); this.schedule();
     return entry;
   }
   node(part: Part) { return this.tree.get(key(part)); }
-  private text(part: Part) { return this.node(part)?.text ?? '(not summarized yet: zoom it)'; }
+  private text(part: Part) { return this.node(part)?.text ?? UNBUILT; }
+  private partBytes(part: Part) { return this.node(part)?.size ?? UNBUILT_BYTES; }
+  private push(i: number) { const part = { l: 0, i }; this.view.push(part); this.viewBytes += this.partBytes(part); }
   render() { return `<chat>\n${this.view.map(p => `${start(p)}+${2 ** p.l}|${flat(this.text(p))}`).join('\n')}\n</chat>`; }
   get ready() { return this.view.every(p => this.node(p)); }
-  get pending() { return this.root.filter(e => !this.tree.has(key({ l: 0, i: e.i }))).length; }
+  get pending() { return this.root.length - this.leaves; }
   get active() { return this.busy.size; }
-  get size() { return this.view.reduce((n, p) => n + bytes(this.text(p)), 0); }
+  get size() { return this.viewBytes; }
+  /** The view tiles the log in order, so a binary search finds the part covering a position. */
+  private visible(part: Part) {
+    const at = start(part);
+    for (let lo = 0, hi = this.view.length - 1; lo <= hi;) {
+      const mid = (lo + hi) >> 1, p = this.view[mid];
+      if (end(p) <= at) lo = mid + 1;
+      else if (start(p) > at) hi = mid - 1;
+      else return p.l === part.l && p.i === part.i;
+    }
+    return false;
+  }
   private fit(total = this.root.length) {
-    let size = this.size;
-    while (size > this.budget) {
+    while (this.viewBytes > this.budget) {
       let best = -1; let due = -Infinity;
       for (let j = 0; j + 1 < this.view.length; j++) {
         const a = this.view[j], b = this.view[j + 1];
-        if (a.l !== b.l || a.i % 2 || b.i !== a.i + 1 || !this.node({ l: a.l + 1, i: a.i / 2 })) continue;
+        if (a.l !== b.l || a.i % 2 || b.i !== a.i + 1) continue;
         const age = (total - start(a)) / 2 ** (a.l + 2);
-        if (age > due) { best = j; due = age; }
+        if (age > due && this.node({ l: a.l + 1, i: a.i / 2 })) { best = j; due = age; }
       }
       if (best < 0) break;
       const a = this.view[best], b = this.view[best + 1];
       const parent = { l: a.l + 1, i: a.i / 2 };
-      size += bytes(this.text(parent)) - bytes(this.text(a)) - bytes(this.text(b));
+      this.viewBytes += this.partBytes(parent) - this.partBytes(a) - this.partBytes(b);
       this.view.splice(best, 2, parent);
     }
     this.events.emit('change');
@@ -140,11 +159,14 @@ export class Memory {
     const first = this.view.find(p => !this.node(p));
     const boundary = first ? start(first) : total;
     for (let l = 0; 2 ** l <= total; l++) {
-      for (let i = 0; (i + 1) * 2 ** l <= total; i++) {
+      let low = this.low[l] ?? 0;
+      while (this.node({ l, i: low })) low++;
+      this.low[l] = low;
+      for (let i = low; (i + 1) * 2 ** l <= total; i++) {
         if (this.busy.size >= this.jobs) return;
         const part = { l, i }, id = key(part);
+        if ((l === 0 ? i : end(part)) > boundary) break;
         if (this.node(part) || this.busy.has(id) || (this.retryAt.get(id) ?? 0) > Date.now()) continue;
-        if ((l === 0 ? i : end(part)) > boundary) continue;
         if (l && (!this.node({ l: l - 1, i: 2 * i }) || !this.node({ l: l - 1, i: 2 * i + 1 }))) continue;
         const promise = this.build(part).catch(error => {
           if (this.stopped) return;
@@ -173,6 +195,8 @@ export class Memory {
     const node = { ...part, text, size: bytes(text) };
     appendJson(join(this.directory, 'tree', `${localDay()}.jsonl`), node);
     this.tree.set(key(part), node); this.retryAt.delete(key(part));
+    // A leaf is usually still in the view when built, but after a damaged tree file a saved parent can already hide it.
+    if (part.l === 0) { this.leaves++; if (this.visible(part)) this.viewBytes += node.size - UNBUILT_BYTES; }
     if (!this.retryAt.size) this.lastError = undefined;
     this.fit();
   }

package/src/transcript.ts

@@ -8,16 +8,22 @@ export const RUN_BOUNDARY = 'optchat.run';
 /** Subagent traffic to the main agent: a custom message on screen, a plain user message to the model and memory. */
 export const REPORT_TYPE = 'optchat-report';
 
-export function textContent(content: unknown): string {
+export function textContent(content: unknown, images = true): string {
   if (typeof content === 'string') return content;
   if (!Array.isArray(content)) return '';
   return content.map((part: unknown) => {
     if (typeof part !== 'object' || part === null) return '';
     if ('type' in part && part.type === 'text' && 'text' in part && typeof part.text === 'string') return part.text;
-    if ('type' in part && part.type === 'image') return '[image attachment: available in Pi session; text memory does not preserve image bytes]';
+    if (images && 'type' in part && part.type === 'image') return '[image attachment: available in Pi session; text memory does not preserve image bytes]';
     return '';
   }).filter(Boolean).join('\n');
 }
+/** What the user typed, as Pi's input event (and so the inbox) saw it: no image placeholders, and without the
+ * `[Image …]` notes Pi appends after the text when it resizes, converts or omits an attached image. */
+export function typedText(content: unknown) {
+  const text = textContent(content, false);
+  return { text, bare: text.replace(/\n\n\[Image[ :][^\n]*\](?:\n\[Image[ :][^\n]*\])*$/, '') };
+}
 /** Reports reach the model, memory and the previous-exchange replay exactly as the user messages they used to be. */
 export function asUser(message: AgentMessage): AgentMessage {
   if (message.role !== 'custom' || message.customType !== REPORT_TYPE) return message;