pi-optchat 0.6.8 → 0.7.1

package/src/inspector.ts

@@ -1,7 +1,8 @@
 import { matchesKey, sliceByColumn, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type Focusable } from '@earendil-works/pi-tui';
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type { Children } from './agents.ts';
-import { isActiveRun } from './runs.ts';
+import type { Memory } from './memory.ts';
+import { isActiveRun, isRunning } from './runs.ts';
 import type { Usage } from '@earendil-works/pi-ai';
 import { ranges, summarizeUsage, type UsageLedger, type UsageRange, type UsageRole } from './usage.ts';
 
@@ -32,12 +33,16 @@ const spread = (left: string, right: string, width: number) => {
   const gap = width - visibleWidth(left) - visibleWidth(right);
   return gap >= 2 ? `${left}${' '.repeat(gap)}${right}` : left;
 };
-export type InspectorPage = 'agents' | 'usage';
+const pages = ['agents', 'usage', 'activity'] as const;
+export type InspectorPage = typeof pages[number];
+const pageNames: Record<InspectorPage, string> = { agents: 'Agents', usage: 'Usage', activity: 'Activity' };
+/** Tab order, wrapping around: Agents, Usage, Activity. */
+export const nextPage = (page: InspectorPage, delta = 1) => pages[(pages.indexOf(page) + delta + pages.length) % pages.length];
 /** 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' | 'warning' | 'border';
 interface Options {
-  profile: string; session: string; children: Children; usage: UsageLedger; page: InspectorPage;
+  profile: string; session: string; children: Children; usage: UsageLedger; memory: Pick<Memory, 'root' | 'size' | 'budget' | 'lastError' | 'progress' | 'onChange'>; page: InspectorPage;
   rows: () => number; redraw: () => void; done: (action?: InspectorAction) => void;
   color: (tone: Tone, text: string) => string;
   context: () => number | null | undefined;
@@ -56,12 +61,12 @@ export class Inspector implements Component, Focusable {
   private hintLines = 1;
   private range: UsageRange = 'This session';
   private ended = false;
-  private readonly unsubscribe: () => void;
+  private readonly unsubscribe: (() => void)[];
   private readonly timer: ReturnType<typeof setInterval>;
   constructor(private readonly options: Options) {
     this.page = options.page;
     this.selected = options.children.history.list()[0]?.id;
-    this.unsubscribe = options.children.subscribe(() => options.redraw());
+    this.unsubscribe = [options.children.subscribe(() => options.redraw()), options.memory.onChange(() => options.redraw())];
     this.timer = setInterval(() => { options.refreshUsage?.(); options.redraw(); }, 1000); this.timer.unref();
     options.signal?.addEventListener('abort', this.abort, { once: true });
     if (options.signal?.aborted) queueMicrotask(this.abort);
@@ -69,7 +74,7 @@ export class Inspector implements Component, Focusable {
   private readonly abort = () => this.finish();
   private finish(action?: InspectorAction) { if (!this.ended) { this.dispose(); this.options.done(action); } }
   dispose() {
-    this.ended = true; clearInterval(this.timer); this.unsubscribe(); this.options.signal?.removeEventListener('abort', this.abort);
+    this.ended = true; clearInterval(this.timer); this.unsubscribe.forEach(stop => stop()); this.options.signal?.removeEventListener('abort', this.abort);
   }
   invalidate() {}
   /** Body rows left after the rules, title, hint and spacing; the rest of the screen keeps the footer visible. */
@@ -82,9 +87,10 @@ export class Inspector implements Component, Focusable {
   handleInput(data: string) {
     if (this.ended) return;
     if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) return this.finish();
-    if (data === 'u' || matchesKey(data, 'tab')) {
-      this.page = this.page === 'agents' ? 'usage' : 'agents'; this.scroll = 0;
-    } else if (this.page === 'usage') {
+    if (matchesKey(data, 'tab')) {
+      this.page = nextPage(this.page); this.scroll = 0;
+    } else if (this.page === 'activity') this.scrollInput(data);
+    else if (this.page === 'usage') {
       if (matchesKey(data, 'left') || matchesKey(data, 'right')) {
         const delta = matchesKey(data, 'left') ? -1 : 1;
         this.range = ranges[(ranges.indexOf(this.range) + delta + ranges.length) % ranges.length]; this.scroll = 0;
@@ -137,17 +143,29 @@ export class Inspector implements Component, Focusable {
     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) : ['']);
   }
+  /** Memory as a gauge: how full the view is, whether summaries are catching up, and how many agents run (their list is one Tab away). */
+  private activityLines(width: number) {
+    const { memory, children, color } = this.options;
+    const { done, total, retryIn } = memory.progress();
+    const list = children.history.list(), agents = list.filter(isRunning).length, paused = list.filter(r => r.state === 'paused').length;
+    const filled = total ? Math.floor(10 * done / total) : 0;
+    const lines = [`${color('muted', 'Memory')} · ${count(memory.root.length)} messages · view ${Math.round(memory.size / 1000)} KB / ${Math.round(memory.budget / 1000)} KB`,
+      total ? `Catching up · ${count(done)} of ${count(total)} summaries  ${color('accent', '█'.repeat(filled))}${color('dim', '░'.repeat(10 - filled))}` : color('dim', 'Settled')];
+    if (memory.lastError) lines.push(color('dim', `${oneLine(memory.lastError)}${retryIn === undefined ? '' : ` · retry in ${elapsed(retryIn)}`}`));
+    lines.push('', `${color('muted', 'Agents')} · ${agents} running${paused ? ` · ${paused} interrupted` : ''}`);
+    return lines.flatMap(l => l ? wrapTextWithAnsi(l, width) : ['']);
+  }
   render(width: number): string[] {
     const { color, children, profile } = this.options;
     const inner = Math.max(1, width - 2);
-    let title = `OptChat · ${profile} · ${this.page === 'usage' ? 'Usage' : 'Agents'}`;
+    let title = `OptChat · ${profile} · ${pageNames[this.page]}`;
     let info: string, body: string[], hint: string;
-    if (this.page === 'usage') {
-      const lines = this.usageLines(inner); this.lineCount = lines.length;
+    if (this.page !== 'agents') {
+      const lines = this.page === 'usage' ? this.usageLines(inner) : this.activityLines(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 · ↑↓ scroll · Tab agents · Esc close';
+      info = this.page === 'usage' || lines.length > this.height ? `${this.scroll + 1}–${Math.min(this.scroll + this.height, lines.length)} / ${lines.length}` : '';
+      hint = this.page === 'usage' ? '←→ period · ↑↓ scroll · Tab activity · Esc close' : '↑↓ scroll · Tab agents · Esc close';
     } else {
       const list = children.history.list();
       if (!this.selected) this.selected = list[0]?.id;
@@ -157,7 +175,7 @@ export class Inspector implements Component, Focusable {
       if (cursor >= this.top + this.height) this.top = cursor - this.height + 1;
       const rows = list.slice(this.top, this.top + this.height).map(run => {
         const live = children.live(run.id), tools = live ? [...live.tools.values()].map(t => t.name).join(', ') : '';
-        const status = live ? `${run.state === 'stopping' ? 'stopping' : run.state === 'waiting' ? 'waiting for children' : tools || (live.streaming ? 'responding' : 'working')} · ${elapsed(Date.now() - live.updated)} ago` : run.state;
+        const status = live ? `${run.state === 'stopping' ? 'stopping' : run.state === 'waiting' ? 'waiting for children' : run.state === 'paused' ? 'interrupted · waiting for you' : tools || (live.streaming ? 'responding' : 'working')} · ${elapsed(Date.now() - live.updated)} ago` : run.state;
         return { run, task: `${'  '.repeat(run.depth - 1)}${run.parentId ? '↳ ' : ''}${oneLine(run.task)}`, status, time: elapsed((run.ended ?? Date.now()) - run.started) };
       });
       // Columns: task (flexible) · status · duration (right-aligned); status yields first on narrow screens.

package/src/memory.ts

@@ -63,7 +63,7 @@ function records(dir: string, warn: (s: string) => void): unknown[] {
 function object(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
-function isEntry(value: unknown): value is Entry {
+export function isEntry(value: unknown): value is Entry {
   return object(value) && Number.isSafeInteger(value.i) && typeof value.kind === 'string'
     && ['user', 'talk', 'tool', 'echo', 'note'].includes(value.kind)
     && typeof value.text === 'string' && typeof value.date === 'string';
@@ -89,6 +89,8 @@ export class Memory {
   /** Per level, every node below this index is built. */
   private readonly low: number[] = [];
   private retryTimer?: ReturnType<typeof setTimeout>;
+  /** The most summaries owed at once since none were last owed. */
+  private peak = 0;
   private scheduled = false;
   private stopped = false;
   lastError?: string;
@@ -116,9 +118,9 @@ export class Memory {
     const main = dirname(next), names = readdirSync(main).filter(n => n.endsWith('.jsonl'));
     if (names.length !== this.lastSeenBytes.size || names.some(n => statSync(join(main, n)).size !== this.lastSeenBytes.get(join(main, n)))) throw otherWriter(next);
   }
-  append(kind: Kind, text: string, date = new Date().toISOString(), receipt?: string) {
+  append(kind: Kind, text: string, date = new Date().toISOString(), receipt?: string, origin?: Origin) {
     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 } : {}) };
+    const entry: Entry = { i: this.root.length, kind, text, date, size: bytes(`${kind}: ${text}`), ...(receipt ? { receipt } : {}), ...(origin ? { origin } : {}) };
     const file = join(this.directory, 'main', `${localDay()}.jsonl`);
     if (!this.lastSeenBytes.has(file)) this.checkLog(file);
     this.lastSeenBytes.set(file, appendJson(file, entry, this.lastSeenBytes.get(file) ?? 0));
@@ -134,17 +136,23 @@ export class Memory {
   get pending() { return this.root.length - this.leaves; }
   get active() { return this.busy.size; }
   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);
+  /** Summaries built out of the backlog since it was last empty, and when the next failed one is retried. */
+  progress(now = Date.now()) {
+    const due = Math.min(...[...this.retryAt.values()].filter(t => t > now));
+    return { done: this.peak - this.owed(), total: this.peak, retryIn: Number.isFinite(due) ? due - now : undefined };
+  }
+  private owed() { return this.expectedNodes() - this.tree.size; }
+  onChange(listener: () => void) { this.events.on('change', listener); return () => { this.events.off('change', listener); }; }
+  /** The view line covering message `at`. The view tiles the log in order, so a binary search finds it. */
+  covering(at: number): Part | undefined {
     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;
+      else return p;
     }
-    return false;
   }
+  private visible(part: Part) { const p = this.covering(start(part)); return p?.l === part.l && p.i === part.i; }
   private fit(total = this.root.length) {
     while (this.viewBytes > this.budget) {
       let best = -1; let due = -Infinity;
@@ -160,6 +168,8 @@ export class Memory {
       this.viewBytes += this.partBytes(parent) - this.partBytes(a) - this.partBytes(b);
       this.view.splice(best, 2, parent);
     }
+    const owed = this.owed();
+    this.peak = owed > 0 ? Math.max(this.peak, owed) : 0;
     this.events.emit('change');
   }
   private schedule() {
@@ -169,6 +179,8 @@ export class Memory {
   }
   private pump() {
     if (this.stopped) return;
+    // One clock reading: skipping a part and arming its retry timer must agree on what is due.
+    const now = Date.now();
     const total = this.root.length;
     const first = this.view.find(p => !this.node(p));
     const boundary = first ? start(first) : total;
@@ -180,7 +192,7 @@ export class Memory {
         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 (this.node(part) || this.busy.has(id) || (this.retryAt.get(id) ?? 0) > now) 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;
@@ -193,8 +205,8 @@ export class Memory {
       }
     }
     // A later failure can have a later deadline than the timer installed by the first.
-    const deadlines = [...this.retryAt.values()].filter(t => t > Date.now());
-    if (deadlines.length && !this.retryTimer) this.retryTimer = setTimeout(() => { this.retryTimer = undefined; this.schedule(); }, Math.max(1, Math.min(...deadlines) - Date.now()));
+    const deadlines = [...this.retryAt.values()].filter(t => t > now);
+    if (deadlines.length && !this.retryTimer) this.retryTimer = setTimeout(() => { this.retryTimer = undefined; this.schedule(); }, Math.max(1, Math.min(...deadlines) - now));
   }
   private async build(part: Part) {
     const source = part.l === 0 ? `${this.root[part.i].kind}: ${this.root[part.i].text}`
@@ -242,6 +254,17 @@ export class Memory {
       return `${start(part)}+${2 ** l}|${flat(node.text)}`;
     }).join('\n');
   }
+  /** Original messages containing `text`, ignoring case, newest first, older than message `before`. Never summaries,
+   * nor the logged zoom/search calls and results, which only copy memory. */
+  search(text: string, before = this.root.length) {
+    const needle = text.toLowerCase(), hits: Entry[] = [];
+    for (let i = Math.min(before, this.root.length) - 1; i >= 0; i--) {
+      const entry = this.root[i];
+      if ((entry.kind === 'tool' || entry.kind === 'echo') && /^(zoom|search)[ :]/.test(entry.text)) continue;
+      if (entry.text.toLowerCase().includes(needle)) hits.push(entry);
+    }
+    return hits;
+  }
   date(id: number) {
     if (!Number.isSafeInteger(id) || !this.root[id]) throw new Error(`No message ${id}.`);
     return new Date(this.root[id].date).toString();

package/src/navigation.ts

@@ -1,8 +1,9 @@
 import { CustomEditor, type ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { matchesKey, truncateToWidth, visibleWidth, type KeyId } from '@earendil-works/pi-tui';
 import type { Children } from './agents.ts';
-import { inspectorShowing, type InspectorPage } from './inspector.ts';
-import { isActiveRun } from './runs.ts';
+import type { Memory } from './memory.ts';
+import { inspectorShowing, nextPage, type InspectorPage } from './inspector.ts';
+import { isRunning } from './runs.ts';
 
 /** Configured before extension registration; this also works in legacy terminals with F6. */
 export function inspectorShortcut(value = process.env.OPTCHAT_INSPECT_KEY ?? 'f6'): KeyId {
@@ -22,7 +23,7 @@ export class BarNavigation {
     }
     if (matchesKey(data, 'escape') || matchesKey(data, 'up')) { this.selected = undefined; return true; }
     if (matchesKey(data, 'left') || matchesKey(data, 'right') || matchesKey(data, 'tab')) {
-      this.selected = this.selected === 'agents' ? 'usage' : 'agents'; return true;
+      this.selected = nextPage(this.selected, matchesKey(data, 'left') ? -1 : 1); return true;
     }
     if (matchesKey(data, 'return')) { const page = this.selected; this.selected = undefined; open(page); return true; }
     if (matchesKey(data, 'down')) return true;
@@ -30,7 +31,7 @@ export class BarNavigation {
   }
 }
 
-export function mountNavigation(ctx: ExtensionContext, children: Children, shortcut: string, open: (page: InspectorPage) => void) {
+export function mountNavigation(ctx: ExtensionContext, children: Children, memory: Pick<Memory, 'progress' | 'onChange'>, shortcut: string, open: (page: InspectorPage) => void) {
   const navigation = new BarNavigation();
   const previous = ctx.ui.getEditorComponent();
   let redraw = () => {};
@@ -51,18 +52,18 @@ export function mountNavigation(ctx: ExtensionContext, children: Children, short
       invalidate() {},
       render(width: number) {
         if (inspectorShowing()) return []; // The open panel replaces the editor and this bar.
-        const list = children.history.list(), running = list.filter(isActiveRun).length;
+        const list = children.history.list(), running = list.filter(isRunning).length, paused = list.filter(r => r.state === 'paused').length;
         const label = (page: InspectorPage, text: string) => navigation.selected === page ? theme.fg('accent', `› ${text}`) : theme.fg('muted', text);
-        const left = `${label('agents', `Agents: ${running} running · ${list.length - running} saved`)}   ${label('usage', 'Usage')}`;
+        const left = `${label('agents', `Agents: ${running} running${paused ? ` · ${paused} interrupted` : ''} · ${list.length - running - paused} saved`)}   ${label('usage', 'Usage')}   ${memory.progress().total || running ? theme.fg('accent', '● ') : ''}${label('activity', 'Activity')}`;
         const hint = theme.fg('dim', navigation.selected ? '←→ select · Enter open · Esc input' : `${previous ? '' : '↓ select · '}${shortcut} inspect`);
         const gap = width - visibleWidth(left) - visibleWidth(hint);
         return [truncateToWidth(gap >= 3 ? `${left}${' '.repeat(gap)}${hint}` : `${left}   ${hint}`, width)];
       },
     };
   }, { placement: 'belowEditor' });
-  const unsubscribe = children.subscribe(() => redraw());
+  const unsubscribe = [children.subscribe(() => redraw()), memory.onChange(() => redraw())];
   return () => {
-    unsubscribe(); ctx.ui.setWidget('optchat-agents', undefined);
+    unsubscribe.forEach(stop => stop()); ctx.ui.setWidget('optchat-agents', undefined);
     if (!previous && ctx.ui.getEditorComponent() === factory) ctx.ui.setEditorComponent(undefined);
   };
 }

package/src/prompts.ts

@@ -1,5 +1,5 @@
 // Prompts transcribed verbatim from Victor Taelin's OptChat recipe.
 export const COMPACT = "You write the memory of OptChat, an AI agent that works for one user in one\nendless chat, through tools and subagents. Each message has a kind: user\n(the user's words; but one starting \"[id] \" is a subagent's report),\ntalk (OptChat's replies), tool (OptChat's tool calls), echo (tool results), note\n(memories from before this chat).\n\nOver the messages grows a binary tree of one-line summaries. First, each\nmessage is compressed alone into a line (a short message is its own\nline). Then lines are merged in pairs: two adjacent lines become one\nline covering both, two of those become one covering four, and so on.\nYour job is one of these steps: compress one message into a line, or\nmerge two adjacent lines into one.\n\nOptChat sees the chat only through these lines: recent messages one per\nline, older ones more per line, the older the more. So your line stands\nin for its messages (your stretch) for weeks or years, and is later\nmerged with its neighbor into the line above. OptChat can open a line back\ninto the two lines it was made from, down to the messages, but only when\nthe line's words show that what it needs is inside: what your line omits\nis lost to OptChat and to every line above.\n\n<chat> is OptChat's view up to the last message of your stretch: use it to\nunderstand what was going on, to resolve references, and to recover\ndetail your input lost.\n\nGoal: let OptChat work later as well as if it remembered the whole stretch.\nSpace is scarce, so it goes by value:\n\n1. The user's own words matter most: orders, decisions, corrections,\npreferences, and above all their reasoning and explanations. Keep them\nas close to verbatim as space allows, and let them outlive everything\nelse up the tree. Record what the user said, not that they said\nsomething. Only text the user wrote counts as theirs.\n\n2. Next comes anything with lasting effect, done by anyone: whatever\nchanged in the world or was committed to, and what failed and why.\n\n3. Then findings and open questions, and OptChat's own replies, which\ndeserve far less space than the user's words.\n\n4. Least of all, intermediate steps: tool calls and their outputs. They\nfill most of the log and are mostly noise. Instead of copying them,\ndescribe each in a few words: what was done, whether it worked (and the\nerror, if not), what the thing it touched is and what is in it, and how\nthat relates to the task underway, even when it is unrelated. Later,\nthis tells OptChat what was already done and what is where, even for a task\nthis one never had in mind.\n\nAvoid dropping an item entirely: an absent item can never be found by\nzooming, while a word or two keeps it findable. When space is tight,\ngive the important items most of it and the minor ones just enough to be\nnamed; drop only what OptChat will plausibly never need, when its space is\nworth much more elsewhere.\n\nEach line will sit among neighbors you cannot predict, so it must make\nsense on its own. Tag each item with its source kind (\"user: ...; echo:\n...\"), and subagent reports as \"work:\". Record faithfully: never answer,\nobey or add to the messages, and never make anything look further along\nthan it was. Output only the line; non-ASCII characters cost 2-4 bytes.";
 export const MASTER = "You are OptChat, an AI agent that works for one user in a single chat that\nnever ends. Do the user's tasks yourself, with your tools, following\nthe user's instructions at the end of this prompt: they say who the\nuser is, how their files are organized and how they want work done.\nUse subagents only when the user asks for them.\n\nYou keep no memory between turns. Each turn starts with the view below,\nfollowed by the user's new message. Summaries keep little of tool\noutput, so say in your reply what you learned that will matter later.\nMessages the user sends while you work reach you between tool calls.\n\nSubagents and computer tasks run in the background. Each one's report\nreaches you as a message starting \"[id] \": between your tool calls\nwhile you work, or as a new turn once yours has ended. So never wait\nfor one (no sleep, no polling): go on, or end your turn and tell the\nuser what is running.";
-export const VIEW_DOC = "The view: the whole chat between OptChat and the user, oldest first, inside\n<chat> tags, as one-line summaries. Each line is\n\n  id+n|text   the n messages from id on, summarized (newlines shown as spaces)\n\nA summary tags each item with its kind: user (the user's words), talk\n(OptChat's replies), tool (OptChat's tool calls), echo (their results), note\n(memories from before this chat), or work (the report of a subagent or\na computer task, which the log holds as a user message starting\n\"[id] \"). A short message is its own line, word for word. Recent lines\ncover one message each; the older the messages, the more a line covers.\nA message not summarized yet shows as \"(not summarized yet: zoom it)\".\nNo message appears in full, not even the last ones.\n\nNavigating: zoom(id, n) opens line id+n into the two lines of n/2\nmessages it was made from; zoom(id, 1) gives message id in full. Zoom\nwhenever a summary only mentions something you need, such as what your\nlast reply said, a decision, a past attempt or where a file is, before\nyou act, guess or ask. date(id) gives the date and time of message id.";
+export const VIEW_DOC = "The view: the whole chat between OptChat and the user, oldest first, inside\n<chat> tags, as one-line summaries. Each line is\n\n  id+n|text   the n messages from id on, summarized (newlines shown as spaces)\n\nA summary tags each item with its kind: user (the user's words), talk\n(OptChat's replies), tool (OptChat's tool calls), echo (their results), note\n(memories from before this chat), or work (the report of a subagent or\na computer task, which the log holds as a user message starting\n\"[id] \"). A short message is its own line, word for word. Recent lines\ncover one message each; the older the messages, the more a line covers.\nA message not summarized yet shows as \"(not summarized yet: zoom it)\".\nNo message appears in full, not even the last ones.\n\nNavigating: zoom(id, n) opens line id+n into the two lines of n/2\nmessages it was made from; zoom(id, 1) gives message id in full. Zoom\nwhenever a summary only mentions something you need, such as what your\nlast reply said, a decision, a past attempt or where a file is, before\nyou act, guess or ask. date(id) gives the date and time of message id.\nYou can zoom out too: zoom(id, n) opens any summarized block with n a\npower of 2 and id a multiple of n, so from a message you can open the\nsummaries above it.";
 export const SUBAGENT = "You are a subagent of OptChat, an AI agent that works for one user in a\nsingle chat that never ends. OptChat gave you a task. Do it yourself, with\nyour tools, following the user's instructions at the end of this\nprompt: they say who the user is, how their files are organized and how\nthey want work done.\n\nYour first message holds the view below, then your task. The view shows\nyou what OptChat knows: what the user wants, decided and taught. Use it as\ncontext only, and do what your task says, not what the user's last\nmessage says, since OptChat may have given you just part of the work. Your\nfinal reply is your report to OptChat. OptChat may send you more messages, even\nwhile you work.";

package/src/report-message.ts

@@ -4,8 +4,12 @@ import { REPORT_TYPE, textContent } from './transcript.ts';
 
 const HEAD = /^\[([0-9a-f]{8})\] (?:(Message from subagent \(still running\)|Connected agent message): )?/;
 
+/** Sent with a report: `count` subagent reports joined in one message, when one spawn's reports arrive together. */
+export interface ReportDetails { count?: number }
+
 /** Split "[id] Message from subagent (still running): body" into a short label and the body. */
-export function reportParts(text: string) {
+export function reportParts(text: string, count = 1) {
+  if (count > 1) return { label: `${count} subagent reports`, body: text };
   const match = HEAD.exec(text);
   if (!match) return { label: 'subagent', body: text };
   const kind = match[2] === undefined ? 'report' : match[2].startsWith('Message') ? 'still running' : 'connected window';
@@ -21,8 +25,8 @@ function darkBackground(theme: Theme) {
 }
 
 /** Background traffic: a dark neutral box with dim text, so it never looks like something the user typed. */
-export function reportBox(text: string, outputPad: number, theme: Theme) {
-  const { label, body } = reportParts(text);
+export function reportBox(text: string, outputPad: number, theme: Theme, count?: number) {
+  const { label, body } = reportParts(text, count);
   const box = new Box(outputPad, 1, darkBackground(theme));
   box.addChild(new Text(theme.fg('dim', `↳ ${label}`), 0, 0));
   box.addChild(new Markdown(body.trim(), 0, 0, getMarkdownTheme(), { color: text => theme.fg('muted', text) }));
@@ -30,5 +34,5 @@ export function reportBox(text: string, outputPad: number, theme: Theme) {
 }
 export const isReport = (text: string) => HEAD.test(text);
 export function registerReportRenderer(pi: ExtensionAPI) {
-  pi.registerMessageRenderer(REPORT_TYPE, (message, { outputPad }, theme) => reportBox(textContent(message.content), outputPad, theme));
+  pi.registerMessageRenderer<ReportDetails | undefined>(REPORT_TYPE, (message, { outputPad }, theme) => reportBox(textContent(message.content), outputPad, theme, message.details?.count));
 }

package/src/runs.ts

@@ -6,7 +6,8 @@ import { atomicWrite } from './profiles.ts';
 import { record } from './cache.ts';
 import { textContent } from './transcript.ts';
 
-export const runStates = ['running', 'waiting', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'] as const;
+/** `paused`: interrupted by the user with nothing queued, alive and waiting for its next message. `interrupted` is a finished run cut off by Pi closing or a connected window ending. */
+export const runStates = ['running', 'waiting', 'stopping', 'completed', 'failed', 'stopped', 'interrupted', 'paused'] as const;
 export type RunState = typeof runStates[number];
 export type FinishReason = 'complete' | 'disconnected' | 'owner-stopped' | 'failed';
 export interface RunInfo {
@@ -20,8 +21,9 @@ export interface RunInfo {
   guidance: { text: string; date: number; state: 'queued' | 'delivered' | 'undelivered'; from?: 'user' | 'manager' }[];
 }
 const moves: Record<RunState, readonly RunState[]> = {
-  running: ['waiting', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'],
-  waiting: ['running', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'],
+  running: ['waiting', 'paused', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'],
+  waiting: ['running', 'paused', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'],
+  paused: ['running', 'stopping', 'failed', 'stopped', 'interrupted'],
   stopping: ['stopped', 'failed', 'interrupted'],
   // A finished run only takes the outcome of a connected handoff.
   completed: ['interrupted'], failed: ['completed', 'interrupted'], stopped: ['completed', 'interrupted'], interrupted: ['completed'],
@@ -31,7 +33,9 @@ export function transition(run: RunInfo, to: RunState) {
   if (run.state !== to && !moves[run.state].includes(to)) return false;
   run.state = to; return true;
 }
-export const isActiveRun = (run: RunInfo) => run.state === 'running' || run.state === 'waiting' || run.state === 'stopping';
+export const isActiveRun = (run: RunInfo) => run.state === 'running' || run.state === 'waiting' || run.state === 'stopping' || run.state === 'paused';
+/** Live and working: a paused run is neither running nor finished. */
+export const isRunning = (run: RunInfo) => isActiveRun(run) && run.state !== 'paused';
 function isRun(value: unknown): value is RunInfo {
   return record(value) && ['id', 'task', 'cwd', 'model', 'thinking', 'parentSession'].every(k => typeof value[k] === 'string')
     && typeof value.id === 'string' && /^[a-zA-Z0-9-]+$/.test(value.id)

package/src/settings-page.ts

@@ -3,6 +3,7 @@ import { DynamicBorder, type ExtensionContext, type Theme } from '@earendil-work
 import { defaults, THINKING, type ProfileConfig } from './profiles.ts';
 import { invalid, isNumberKey, SETTING_KEYS, SETTINGS, type NumberKey, type SettingKey } from './settings.ts';
 import type { ModelChoice } from './compactor.ts';
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 
 type Role = 'compactor' | 'subagent';
 const ROLES: Record<Role, { label: string; description: string; applies: string }> = {
@@ -20,7 +21,9 @@ const show = (key: SettingKey, value: number | boolean) => {
 };
 
 interface Options {
-  profile: string; config: ProfileConfig; models: string[];
+  profile: string; config: ProfileConfig;
+  /** Each model with the thinking levels Pi can send it (Sonnet 5.5 has no "off"). */
+  models: { name: string; thinking: readonly ThinkingLevel[] }[];
   /** Saves the whole profile config; throws if it can't be written. */
   save: (config: ProfileConfig) => void;
 }
@@ -61,21 +64,21 @@ class NumberStep extends Container {
 /** Model first (type to filter), then thinking level; Esc goes back a step. */
 class ModelStep extends Container {
   private active: { handleInput(data: string): void } = { handleInput: () => {} };
-  constructor(private readonly theme: Theme, private readonly role: Role, private readonly models: string[], private readonly current: ModelChoice,
+  constructor(private readonly theme: Theme, private readonly role: Role, private readonly models: Options['models'], private readonly current: ModelChoice,
     private readonly submit: (choice: ModelChoice) => string | undefined, private readonly cancel: () => void) {
     super();
     this.pickModel();
   }
   private pickModel() {
     const { theme, current } = this, filter = new Input();
-    const items: SelectItem[] = this.models.map(value => ({ value, label: value }));
+    const items: SelectItem[] = this.models.map(({ name }) => ({ value: name, label: name }));
     let list = new SelectList(items, 10, listTheme(theme));
     const build = () => {
       list = new SelectList(filter.getValue() ? fuzzyFilter(items, filter.getValue(), i => i.value) : items, 10, listTheme(theme));
       list.onSelect = item => this.pickThinking(item.value); list.onCancel = this.cancel;
       return list;
     };
-    build(); list.setSelectedIndex(Math.max(0, this.models.indexOf(modelName(current))));
+    build(); list.setSelectedIndex(Math.max(0, this.models.findIndex(m => m.name === modelName(current))));
     filter.focused = true;
     const box = step(theme, ROLES[this.role].label, `${ROLES[this.role].description} Now ${showModel(current)}.`, filter, 'Type to filter · Enter to choose · Esc to go back', [new Spacer(1), list]);
     this.show(box, data => {
@@ -87,11 +90,12 @@ class ModelStep extends Container {
   }
   private pickThinking(model: string) {
     const { theme, current } = this, error = new Text('', 0, 0);
-    const list = new SelectList(THINKING.map(value => ({ value, label: value })), THINKING.length, listTheme(theme));
-    list.setSelectedIndex(Math.max(0, THINKING.indexOf(current.thinking)));
+    const levels = this.models.find(m => m.name === model)?.thinking ?? THINKING;
+    const list = new SelectList(levels.map(value => ({ value, label: value })), levels.length, listTheme(theme));
+    list.setSelectedIndex(Math.max(0, levels.indexOf(current.thinking)));
     list.onCancel = () => this.pickModel();
     list.onSelect = item => {
-      const thinking = THINKING.find(level => level === item.value);
+      const thinking = levels.find(level => level === item.value);
       const slash = model.indexOf('/');
       const problem = thinking && this.submit({ provider: model.slice(0, slash), model: model.slice(slash + 1), thinking });
       if (problem) error.setText(theme.fg('error', problem));

package/src/settings.ts

@@ -8,12 +8,18 @@ export const SETTINGS = {
   maxAgents: { kind: 'number', label: 'Max active agents', default: 8, min: 1, unit: '',
     description: 'Subagents running at once in this profile, all levels together. It also caps how deep a chain can go.',
     applies: 'Applies to the next spawn.' },
+  groupReports: { kind: 'toggle', label: 'Group subagent reports', default: true,
+    description: 'On: the subagents started by one spawn report together, in one message once the last of them finishes, as in Victor\'s recipe. Off: each subagent reports as soon as it finishes.',
+    applies: 'Applies to the next spawn.' },
   previousExchange: { kind: 'toggle', label: 'Previous exchange', default: true,
     description: 'Send your last request and its answer in full with the next turn, so a follow-up reads the exact wording. Off: memory view only, as in Victor\'s recipe. On by default: a study found it costs little and saves zooms.',
     applies: 'Applies from the next turn.' },
   previousExchangeKB: { kind: 'number', label: 'Previous exchange limit', default: 16, min: 1, unit: 'KB',
     description: 'A larger last exchange, usually a big paste, is left out and the model zooms into memory instead.',
     applies: 'Applies from the next turn.' },
+  memorySearch: { kind: 'toggle', label: 'Memory search', default: false,
+    description: 'Give agents a search tool that finds original messages by plain text, newest first, for exact names, numbers, paths or errors the view doesn\'t show. Off: zoom and date only, as in Victor\'s recipe. Turning it on or off makes the next turn re-cache its prompt once.',
+    applies: 'Applies from the next turn, and to subagents started or resumed after this.' },
   summaryAcceptBytes: { kind: 'number', label: 'Summary size tolerance', default: NODE * 1.25, min: NODE, unit: 'bytes',
     description: `The compactor is always asked for ${NODE}-byte lines; a longer line up to this size is kept instead of retried. ${NODE}: strict, as in Victor's recipe. The default saves retries for a little more view space.`,
     applies: 'Applies to the next summary.' },

package/src/tools.ts

@@ -1,6 +1,28 @@
 import { Type } from 'typebox';
-import type { Memory } from './memory.ts';
+import { flat, start, type Memory } from './memory.ts';
 export const result = (text: string) => ({ content: [{ type: 'text' as const, text }], details: {} });
+export const SEARCH_PAGE = 20;
+const SNIPPET = 200;
+/** Added after the view doc when Memory search is on. */
+export const SEARCH_DOC = '\n\nsearch(text) finds the original messages that contain text, newest first. Use it for an exact name, number, PR, path or error the view doesn\'t show, then zoom(id, 1) to read a hit. A hit is one message: zoom around it too, especially the messages after it, where the outcome usually is.';
+
+/** One page of hits, each with its id, the view line holding it, its date and a snippet around the first match; at most ~5 KB. */
+export function searchPage(memory: Memory, text: string, before?: number) {
+  const hits = memory.search(text, before), older = before === undefined ? '' : 'older ';
+  if (!hits.length) return `No ${older}messages contain "${text}".`;
+  const page = hits.slice(0, SEARCH_PAGE), needle = text.toLowerCase();
+  const lines = page.map(entry => {
+    // Cut the original text, whose match may span lines, and flatten only the cut.
+    const at = Math.max(0, entry.text.toLowerCase().indexOf(needle) - SNIPPET / 4);
+    const snippet = flat(entry.text.slice(at, at + SNIPPET).replace(/^[\udc00-\udfff]|[\ud800-\udbff]$/g, ''));
+    // The live view, which may have folded since the turn's snapshot: its lines are built, so zoom always opens them.
+    const line = memory.covering(entry.i); // Named only when the hit is inside a summary line.
+    return `${entry.i}${line?.l ? ` (in ${start(line)}+${2 ** line.l})` : ''} · ${new Date(entry.date).toString().slice(0, 21)} · ${entry.kind}: ${at ? '…' : ''}${snippet}${at + SNIPPET < entry.text.length ? '…' : ''}`;
+  });
+  const more = hits.length > page.length ? `\nOlder matches: search again with before: ${page[page.length - 1].i}.` : '';
+  return `${hits.length} ${older}${hits.length === 1 ? 'message contains' : 'messages contain'} "${text}", newest first:\n${lines.join('\n')}${more}`;
+}
+
 export function memoryTools(memory: () => Memory) {
   return [
     { name: 'zoom', label: 'Zoom memory', description: 'Open the line id+n of the view into the two lines of n/2 under it; n = 1 gives the message whole.',
@@ -11,3 +33,8 @@ export function memoryTools(memory: () => Memory) {
       async execute(_id: string, args: { id: number }) { return result(memory().date(args.id)); } },
   ];
 }
+
+export const searchTool = (memory: () => Memory) => ({ name: 'search', label: 'Search memory',
+  description: `Find the original messages that contain text (plain text, any case), newest first, ${SEARCH_PAGE} at a time; before: id continues with older ones. zoom(id, 1) gives a hit whole.`,
+  parameters: Type.Object({ text: Type.String({ minLength: 1 }), before: Type.Optional(Type.Integer({ minimum: 0 })) }),
+  async execute(_id: string, args: { text: string; before?: number }) { return result(searchPage(memory(), args.text, args.before)); } });