pi-optchat 0.10.1 → 0.11.0

package/src/report-message.ts

@@ -2,7 +2,8 @@ import { getMarkdownTheme, type ExtensionAPI, type Theme } from '@earendil-works
 import { Box, Markdown, Text } from '@earendil-works/pi-tui';
 import { REPORT_TYPE, textContent, withoutFullChat } from './transcript.ts';
 
-const HEAD = /^\[([0-9a-f]{8})\] (?:(Message from subagent \(still running\)|Connected agent message): )?/;
+/** `[id]` or `[id · title]` (runs.ts `reportHead`); titles hold no brackets. */
+const HEAD = /^\[([0-9a-f]{8})(?: · ([^\]\n]*))?\] (?:(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 }
@@ -13,8 +14,9 @@ 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';
-  return { label: `subagent ${match[1]} · ${kind}`, body: text.slice(match[0].length) };
+  const [, id, title, message] = match;
+  const kind = message === undefined ? 'report' : message.startsWith('Message') ? 'still running' : 'connected window';
+  return { label: `subagent ${id}${title ? ` · ${title}` : ''} · ${kind}`, body: text.slice(match[0].length) };
 }
 
 /** The theme's neutral grey, darkened on dark themes so the box recedes behind the conversation. */

package/src/runs.ts

@@ -3,7 +3,7 @@ import { basename, join } from 'node:path';
 import { SessionManager } from '@earendil-works/pi-coding-agent';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import { atomicWrite } from './store.ts';
-import { record } from './cache.ts';
+import { record } from './core/cache.ts';
 import { textContent } from './transcript.ts';
 
 /** `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. */
@@ -12,6 +12,8 @@ export type RunState = typeof runStates[number];
 export type FinishReason = 'complete' | 'disconnected' | 'owner-stopped' | 'failed';
 export interface RunInfo {
   id: string; task: string; cwd: string; model: string; thinking: string;
+  /** The spawning agent's short label for the task, shown instead of it where there is room for one line. */
+  title?: string;
   parentSession: string; sessionFile?: string; started: number; ended?: number;
   parentId?: string; depth: number;
   state: RunState; report?: string;
@@ -24,6 +26,8 @@ export interface RunInfo {
   guidance: Guidance[];
 }
 export type Guidance = { text: string; date: number; state: 'queued' | 'delivered' | 'undelivered'; from?: 'user' | 'manager'; sent?: string };
+/** How a run's reports and messages start: `[id]`, or `[id · title]` (see `HEAD` in report-message.ts). */
+export const reportHead = (run: { id: string; title?: string }) => `[${run.id}${run.title ? ` · ${run.title}` : ''}]`;
 /** The text the agent receives, which is how Pi's queue and the session know the message. */
 export const sentText = (g: Guidance) => g.sent ?? g.text;
 const moves: Record<RunState, readonly RunState[]> = {
@@ -56,6 +60,7 @@ function isRun(value: unknown): value is RunInfo {
     && typeof value.id === 'string' && /^[a-zA-Z0-9-]+$/.test(value.id)
     && runStates.includes(value.state as RunState) && typeof value.started === 'number' && Number.isFinite(value.started)
     && (value.ended === undefined || typeof value.ended === 'number')
+    && (value.title === undefined || typeof value.title === 'string')
     && (value.sessionFile === undefined || typeof value.sessionFile === 'string')
     && (value.report === undefined || typeof value.report === 'string')
     && (value.connected === undefined || typeof value.connected === 'boolean')

package/src/settings.ts

@@ -1,4 +1,5 @@
-import { NODE } from './memory.ts';
+import { ACCEPTED_BYTES } from './core/compactor.ts';
+import { NODE } from './core/memory.ts';
 
 /** Per-profile choices where OptChat departs from Victor's recipe. Each default is the recipe's behaviour unless noted. */
 export const SETTINGS = {
@@ -20,7 +21,7 @@ export const SETTINGS = {
   memorySearch: { kind: 'toggle', label: 'Memory search', default: false,
     description: 'Lets agents search original messages by plain text. Off: zoom and date only (Victor\'s recipe). Toggling re-caches the prompt once.',
     applies: 'Applies from the next turn and to new or resumed subagents.' },
-  summaryAcceptBytes: { kind: 'number', label: 'Summary size tolerance', default: NODE * 1.25, min: NODE, unit: 'bytes',
+  summaryAcceptBytes: { kind: 'number', label: 'Summary size tolerance', default: ACCEPTED_BYTES, min: NODE, unit: 'bytes',
     description: `Summary lines up to this size are kept instead of retried (the compactor aims for ${NODE}). ${NODE}: strict (Victor's recipe).`,
     applies: 'Applies to the next summary.' },
   jobs: { kind: 'number', label: 'Summaries at once', default: 8, min: 1, max: 64, unit: '',

package/src/store.ts

@@ -1,48 +1,10 @@
 import { closeSync, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, truncateSync, writeFileSync, writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import type { Entry, Summary } from './memory.ts';
+import { isEntry, isSummary, type Entry, type Part, type Summary } from './core/memory.ts';
+import { EXTENSIONS, type Mime, type Saved, type Store } from './core/store.ts';
 
-/** The image types memory keeps, and the file extension each is saved under. */
-export const EXTENSIONS = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp' } as const;
-export type Mime = keyof typeof EXTENSIONS;
-export const isMime = (mime: string): mime is Mime => Object.hasOwn(EXTENSIONS, mime);
 const MIMES = new Map<string, Mime>((Object.keys(EXTENSIONS) as Mime[]).map(mime => [EXTENSIONS[mime], mime]));
 
-/** What a store gives back when a memory opens. Memory validates every record itself; `view` is the JSON `saveView` was last given. */
-export interface Saved { entries: unknown[]; tree: unknown[]; view?: string }
-/** A write is done when it returns: a store that writes behind returns a promise instead, which Memory awaits in order. */
-type Write = Promise<void> | undefined;
-type Maybe<T> = T | Promise<T>;
-
-/** Cross-machine exclusivity. Implement it only if you want it: without it OptChat keeps its machine-local lock (a socket in the
- * profile, or a named pipe on Windows), so two Pis on one machine still can't share a profile. */
-export interface Lease {
-  /** Takes the profile for `holder` (who and where, shown to anyone refused), or returns the current holder.
-   * A lease not renewed for about 30 seconds may be taken by someone else. */
-  lease(profile: string, holder: string): Promise<string | undefined>;
-  /** Renews the lease. OptChat calls it every 10 seconds while it holds the profile and only warns when it fails, so fencing is
-   * the store's job: once its lease may have lapsed, it must refuse writes (for example with a fencing token checked on each one),
-   * since a paused process cannot be trusted to stop itself in time. */
-  heartbeat(): Promise<void>;
-  release(): Promise<void>;
-}
-
-/** Where one memory keeps what travels between machines: its message log, summary nodes, saved view and images. Everything else
- * in a profile (runs, recovery journals, the active-memory pointer and imports, usage, settings, AGENTS.md) stays on the machine.
- * Memory loads once when it opens, then works in RAM and issues every write in order. */
-export interface Store {
-  load(): Maybe<Saved>;
-  /** Appends a message. Throws, writing nothing, if someone else appended since this store loaded. */
-  append(entry: Entry): Write;
-  /** Appends a summary node. */
-  appendNode(node: Summary): Write;
-  /** Replaces the saved view. */
-  saveView(view: string): Write;
-  putImage(name: string, mimeType: Mime, data: Uint8Array): Write;
-  image(name: string): Maybe<{ mimeType: Mime; data: Uint8Array } | undefined>;
-  lock?: Lease;
-}
-
 /** The one place a profile's store is chosen. A `store` setting will plug in here; until then every profile keeps its memory in files. */
 export const storeFor = (directory: string, warn: (s: string) => void = console.error): Store => new FileStore(directory, warn);
 
@@ -97,6 +59,9 @@ function records(dir: string, warn: (s: string) => void): unknown[] {
 export class FileStore implements Store {
   /** Each log file's size as this store last left it, so a write by another process is refused instead of interleaved. */
   private readonly lastSeenBytes = new Map<string, number>();
+  /** Texts stay in RAM, as before lazy text: Pi has the room, and reads stay as fast. */
+  private readonly texts: string[] = [];
+  private readonly summaries = new Map<string, string>();
   constructor(readonly directory: string, private readonly warn: (s: string) => void = console.error) {}
   load(): Saved {
     for (const sub of ['main', 'tree']) mkdirSync(join(this.directory, sub), { recursive: true, mode: 0o700 });
@@ -106,18 +71,27 @@ export class FileStore implements Store {
     // An unreadable view is rebuilt, as a damaged one is.
     let saved: string | undefined;
     if (existsSync(view)) try { saved = readFileSync(view, 'utf8'); } catch { saved = ''; }
-    return { entries, tree: records(join(this.directory, 'tree'), this.warn), view: saved };
+    const tree = records(join(this.directory, 'tree'), this.warn);
+    // Memory checks the rest; a record without its text is as broken here as before.
+    if (!entries.every(isEntry)) throw new Error('Invalid/noncontiguous OptChat log; refusing to change it.');
+    if (!tree.every(isSummary)) throw new Error('Invalid OptChat summary record.');
+    for (const { i, text } of entries) this.texts[i] = text;
+    for (const { l, i, text } of tree) this.summaries.set(`${l}:${i}`, text);
+    return { entries, tree, view: saved };
   }
+  text(i: number) { return this.texts[i]; }
+  summary({ l, i }: Part) { return this.summaries.get(`${l}:${i}`)!; }
   append(entry: Entry): undefined {
     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));
+    this.texts[entry.i] = entry.text;
   }
   private checkLog(next: string) {
     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);
   }
-  appendNode(node: Summary): undefined { appendJson(join(this.directory, 'tree', `${localDay()}.jsonl`), node); }
+  appendNode(node: Summary): undefined { appendJson(join(this.directory, 'tree', `${localDay()}.jsonl`), node); this.summaries.set(`${node.l}:${node.i}`, node.text); }
   saveView(view: string): undefined { atomicWrite(join(this.directory, 'view.json'), view); }
   putImage(name: string, mimeType: Mime, data: Uint8Array): undefined { atomicWrite(join(this.directory, 'images', `${name}.${EXTENSIONS[mimeType]}`), data); }
   image(name: string) {

package/src/title.ts

@@ -4,8 +4,9 @@ export type WindowState = StatusState | 'done' | 'disconnected';
 
 const agents = (count: number) => count > 0 ? ` · ${count} ${count === 1 ? 'agent' : 'agents'}` : '';
 export const mainTitle = (profile: string, working: boolean, running: number) => `${working ? '● ' : ''}π ${profile}${agents(running)}`;
-export const windowTitle = (profile: string, state: WindowState) =>
-  `${state === 'working' ? '● ' : ''}↳ ${profile}${state === 'done' || state === 'disconnected' ? ` · ${state}` : ''}`;
+/** `label`: the spawn title of the subagent an attached window shows. */
+export const windowTitle = (profile: string, state: WindowState, label?: string) =>
+  `${state === 'working' ? '● ' : ''}↳ ${profile}${label ? ` · ${label}` : ''}${state === 'done' || state === 'disconnected' ? ` · ${state}` : ''}`;
 /** A connected window's agent is working while it runs or stops, or waits on agents of its own; waiting with none means waiting for you. */
 export const statusState = (state: string, agents = 0): StatusState =>
   state === 'running' || state === 'stopping' || state === 'waiting' && agents > 0 ? 'working' : 'waiting';

package/src/tools.ts

@@ -1,65 +1,8 @@
-import { Type, type Static } from 'typebox';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
-import { flat, PAGE, start, type Memory } from './memory.ts';
-import { loadImages } from './images.ts';
+import type { Memory } from './core/memory.ts';
+import { memoryTools as tools } from './core/tools.ts';
 import { runTranscript } from './transcript.ts';
-export const result = (text: string) => ({ content: [{ type: 'text' as const, text }], details: {} });
-export const SEARCH_PAGE = 20;
-const SNIPPET = 200;
 
-/** 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}`;
-}
-
-const zoomParameters = Type.Object({ id: Type.Union([Type.Integer({ minimum: 0 }), Type.String({ minLength: 1 })]), n: Type.Optional(Type.Integer({ minimum: 1 })),
-  offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: PAGE })) });
-
-/** A page of a run's transcript, saying where the next one starts. */
-export function runPage(text: string, offset = 0, limit = PAGE) {
-  if (offset > text.length) throw new Error(`This transcript has ${text.length} characters; offset must be 0 to ${text.length}.`);
-  // Never split a surrogate pair: a page starts on its first half and ends after its second.
-  const from = /[\udc00-\udfff]/.test(text[offset] ?? '') ? offset - 1 : offset;
-  let to = Math.min(text.length, from + limit);
-  if (to < text.length && /[\ud800-\udbff]/.test(text[to - 1])) to += to - 1 === from ? 1 : -1;
-  return `${text.slice(from, to)}\n[characters ${from}-${to} of ${text.length}${to < text.length ? `; go on with offset ${to}` : ''}]`;
-}
-
-/** `runs` gives a subagent's messages by run id, live or finished; undefined for no such run. */
-export function memoryTools(memory: () => Memory, runs?: (id: string) => readonly AgentMessage[] | undefined) {
-  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 (the default) gives the message whole. A message over ${PAGE.toLocaleString('en-US')} characters comes in pages; offset and limit (characters) read any part of it, and are not needed for a shorter one. A message's images come back with it. zoom("<run id>") gives a subagent's whole chat so far, in the same pages.`,
-      parameters: zoomParameters,
-      async execute(_id: string, { id, n = 1, offset, limit }: Static<typeof zoomParameters>) {
-        if (typeof id === 'string') {
-          const messages = runs?.(id);
-          if (messages) return result(runPage(runTranscript(messages), offset, limit));
-          // A model may quote a message id; eight digits can be a run id (src/agents.ts), so those never open a message.
-          if (!/^\d+$/.test(id) || id.length === 8) throw new Error(`No run ${id}.`);
-        }
-        const m = memory(), text = m.zoom(Number(id), n, offset, limit), page = result(text);
-        // A message's images come back with its text, as read returns a PNG; summaries stay text.
-        return n === 1 ? { ...page, content: [...page.content, ...await loadImages(m.store, text)] } : page;
-      } },
-    { name: 'date', label: 'Memory date', description: 'The date and time of message id.',
-      parameters: Type.Object({ id: Type.Integer({ minimum: 0 }) }),
-      async execute(_id: string, args: { id: number }) { return result(memory().date(args.id)); } },
-  ] as const;
-}
-
-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)); } });
+/** zoom and date, where `runs` gives a subagent's messages by run id, live or finished; undefined for no such run. */
+export const memoryTools = (memory: () => Memory, runs?: (id: string) => readonly AgentMessage[] | undefined) =>
+  tools(memory, runs && (id => { const messages = runs(id); return messages && runTranscript(messages); }));

package/src/transcript.ts

@@ -1,12 +1,13 @@
 import { createHash } from 'node:crypto';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
-import { getCurrentSystemMessage, type SystemMessage, type UserMessage } from '@earendil-works/pi-ai';
-import { CAP, cap, flat, isView, type Memory } from './memory.ts';
-import { AT_WORK } from './prompts.ts';
-import { record } from './cache.ts';
+import { getCurrentSystemMessage, type SystemMessage } from '@earendil-works/pi-ai';
+import { cap, flat, isView, type Memory } from './core/memory.ts';
+import { completedExchange, logMessage as log, textContent as text, withView } from './core/messages.ts';
+import { AT_WORK } from './core/prompts.ts';
+import { record } from './core/cache.ts';
 import { DEFAULT_SETTINGS } from './settings.ts';
-import { imageRef, isImage } from './images.ts';
+import { imageRef } from './images.ts';
 
 export const RUN_BOUNDARY = 'optchat.run';
 /** Subagent traffic to the main agent: a custom message on screen, a plain user message to the model, `work` in memory. */
@@ -15,16 +16,8 @@ export const REPORT_RECEIPT = 'report:';
 /** A report's receipt in memory: it marks the entry as `work` and keeps a restart from delivering the report twice. */
 export const reportReceipt = (text: string) => REPORT_RECEIPT + createHash('sha256').update(text).digest('hex');
 
-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 (images && isImage(part)) return imageRef(part);
-    return '';
-  }).filter(Boolean).join('\n');
-}
+/** A message's text, its images named by `imageRef` unless `images` is false. */
+export const textContent = (content: unknown, images = true) => text(content, images ? imageRef : undefined);
 /** What the user typed, as Pi's input event (and so the inbox) saw it: no image references, and without the
  * `[Image …]` notes Pi appends after the text when it resizes, converts or omits an attached image. */
 export function typedText(content: unknown) {
@@ -46,41 +39,9 @@ export function asUser(message: AgentMessage): AgentMessage {
   if (first?.type === 'text') return { role: 'user', content: [{ ...first, text: tag + first.text }, ...rest], timestamp };
   return { role: 'user', content: [{ type: 'text', text: tag.trimEnd() }, ...content], timestamp };
 }
-export function logMessage(memory: Memory, message: AgentMessage, receipt?: string) {
-  const date = new Date(message.timestamp).toISOString();
-  if (message.role === 'user') memory.append(receipt?.startsWith(REPORT_RECEIPT) ? 'work' : 'user', textContent(message.content), date, receipt);
-  else if (message.role === 'assistant') {
-    for (const block of message.content) {
-      if (block.type === 'text' && block.text.trim()) memory.append('talk', block.text, date);
-      if (block.type === 'toolCall') memory.append('tool', `${block.name} ${JSON.stringify(block.arguments)}`, date);
-    }
-    if (message.stopReason === 'error' || message.stopReason === 'aborted')
-      memory.append('echo', `Agent ${message.stopReason}: ${message.errorMessage ?? 'No further details'}`, date);
-  } else if (message.role === 'toolResult')
-    // A zoom's page already names the images it returns.
-    memory.append('echo', cap(`${message.toolName}: ${textContent(message.content, message.toolName !== 'zoom')}`), date);
-}
-export function boundedMessage(message: AgentMessage): AgentMessage {
-  if (message.role !== 'toolResult') return message;
-  const text = message.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
-  if (text.length <= CAP) return message;
-  return { ...message, content: [{ type: 'text', text: cap(text) }, ...message.content.filter(c => c.type === 'image')] };
-}
-/** The caller supplies a single settled run, including any steering after text-only replies. */
-function completedExchange(history: readonly AgentMessage[]) {
-  const last = history.findLastIndex(m => m.role === 'user' || m.role === 'assistant');
-  const answer = history[last];
-  if (answer?.role !== 'assistant' || answer.stopReason !== 'stop'
-    || answer.content.some(block => block.type === 'toolCall')) return [];
-  const content = answer.content.flatMap(block => block.type === 'text' ? [{ type: 'text' as const, text: block.text }] : []);
-  if (!content.some(block => block.text.trim())) return [];
-  const requests: UserMessage[] = [];
-  for (const message of history.slice(0, last)) {
-    if (message.role === 'user') requests.push({ ...message, content: textContent(message.content) });
-  }
-  if (!requests.length) return [];
-  return [...requests, { ...answer, content }];
-}
+/** Logs a message to memory; a user message with a report's receipt as `work`. */
+export const logMessage = (memory: Memory, message: AgentMessage, receipt?: string) =>
+  log(memory, message, { kind: receipt?.startsWith(REPORT_RECEIPT) ? 'work' : 'user', receipt, imageRef });
 
 /** Default limit in bytes of text (16 KB, ~4,000 tokens). Most exchanges are 1-7 KB; a larger one, usually a big paste, is
  * left out entirely and the model falls back to its summaries in the memory view, zooming for the full text if it needs it. */
@@ -104,7 +65,7 @@ function latestExchange(branch: readonly SessionEntry[]) {
     if (entry.data.state === 'end') end = i;
     else if (entry.data.state === 'start') {
       if (end >= 0) {
-        const exchange = completedExchange(messages(branch.slice(i + 1, end)));
+        const exchange = completedExchange(messages(branch.slice(i + 1, end)), imageRef);
         if (exchange.length) return exchange;
       }
       end = -1;
@@ -118,7 +79,7 @@ function latestExchange(branch: readonly SessionEntry[]) {
   for (let i = 0; i < legacy.length; i++) {
     const message = legacy[i];
     if (message.role !== 'assistant' || message.stopReason === 'toolUse') continue;
-    const exchange = completedExchange(legacy.slice(boundary, i + 1));
+    const exchange = completedExchange(legacy.slice(boundary, i + 1), imageRef);
     if (exchange.length) latest = exchange;
     boundary = i + 1;
   }
@@ -148,11 +109,11 @@ export function runTranscript(messages: readonly AgentMessage[]) {
   }).join('\n');
 }
 
-/** The status line naming running agents by id and the first words of their task; none while nothing runs. */
-export function atWork(runs: readonly { id: string; task: string }[]) {
+/** The status line naming running agents by id and the first words of their title or task; none while nothing runs. */
+export function atWork(runs: readonly { id: string; task: string; title?: string }[]) {
   if (!runs.length) return undefined;
-  return AT_WORK + runs.map(({ id, task }) => {
-    const words = flat(task).replaceAll('"', "'").split(/\s+/).filter(Boolean), start = words.slice(0, 6).join(' ');
+  return AT_WORK + runs.map(({ id, task, title }) => {
+    const words = flat(title ?? task).replaceAll('"', "'").split(/\s+/).filter(Boolean), start = words.slice(0, 6).join(' ');
     // Six words, but never more than 60 characters: a task can be one long word.
     const preview = [...start].slice(0, 60).join('');
     return `${id} "${preview}${words.length > 6 || preview.length < start.length ? '…' : ''}"`;
@@ -167,57 +128,13 @@ export function buildContext(canonical: AgentMessage[], run: AgentMessage[], vie
   const system = getCurrentSystemMessage(canonical);
   const head: SystemMessage = { role: 'system', content: prompt, toolsAdded: system?.toolsAdded, timestamp: 0 };
   if (!run.some(m => m.role === 'user')) throw new Error('OptChat has no current user message; refusing to send historical context.');
-  let injected = false;
-  const messages = [...previous, ...run].filter(m => m.role !== 'system').map(message => {
-    if (message.role !== 'user' || injected) return message;
-    injected = true;
-    // OpenAI joins text blocks with nothing between them, so the user's words start their own paragraph after the view.
-    const [first, ...rest] = typeof message.content === 'string' ? [{ type: 'text' as const, text: message.content }] : message.content;
-    return { ...message, content: [{ type: 'text' as const, text: view }, ...first?.type === 'text' ? [{ ...first, text: `\n\n${first.text}` }] : first ? [first] : [], ...rest] };
-  });
+  const messages = withView([...previous, ...run].filter(m => m.role !== 'system'), view);
   return [head, ...messages, ...status && messages.at(-1)?.role !== 'toolResult' ? [{ role: 'user' as const, content: [{ type: 'text' as const, text: status }], timestamp: 0 }] : []];
 }
 
-/** Pi's own estimate for an image when it decides to compact: 4,800 characters, about 1,200 tokens. */
-const IMAGE_CHARS = 4_800;
-/** Characters a message adds to a request: its text, thinking, tool-call arguments and images, as Pi estimates them. Framing is left out. */
-export function messageChars(message: AgentMessage) {
-  if (!('content' in message)) return 0;
-  const { content } = message;
-  if (typeof content === 'string') return content.length;
-  return content.reduce((sum, block) => sum + (block.type === 'text' ? block.text.length : block.type === 'thinking' ? block.thinking.length
-    : block.type === 'toolCall' ? JSON.stringify(block.arguments).length : block.type === 'image' ? IMAGE_CHARS : 0), 0);
-}
 /** The share of the model's window the current turn's verbatim messages may fill before they move into memory (#146): the
  * profile's Turn refresh threshold, unless `OPTCHAT_REFRESH_AT` gives one (0 turns it off). */
 export function refreshFraction(setting: number, env = process.env.OPTCHAT_REFRESH_AT) {
   const override = env?.trim() ? Number(env) : NaN;
   return Number.isFinite(override) ? override : setting;
 }
-/** That share in characters, at ~4 characters a token; none when off or the window is unknown. */
-export function refreshBudget(contextWindow: number | undefined, fraction: number) {
-  return contextWindow && fraction > 0 ? Math.floor(contextWindow * fraction * 4) : undefined;
-}
-const chars = (messages: readonly AgentMessage[]) => messages.reduce((sum, m) => sum + messageChars(m), 0);
-/** Where a refresh would cut the run: the last model reply, so its tool calls and their results stay whole. 0 when there is none after the task. */
-export function lastStep(run: readonly AgentMessage[]) {
-  const task = run.findIndex(m => m.role === 'user'), step = run.findLastIndex(m => m.role === 'assistant');
-  return step > task && task >= 0 ? step : 0;
-}
-/** The run's new `keep` and the size it moves into the view, when what is sent since the last refresh passes the budget.
- * What stays verbatim (the task and the last step) must fit in half the budget: a bigger last step, such as many parallel
- * reads, would otherwise pass the budget again on the next call and refresh every call. It waits for a smaller step instead. */
-export function refreshPoint(run: readonly AgentMessage[], keep: number, budget: number | undefined) {
-  const cut = lastStep(run), task = run.find(m => m.role === 'user');
-  if (!budget || cut <= keep) return undefined;
-  const size = chars(run.slice(keep));
-  if (size <= budget || (task ? messageChars(task) : 0) + chars(run.slice(cut)) > budget / 2) return undefined;
-  return { cut, size };
-}
-/** The run as sent after a mid-turn refresh at `keep`: the task verbatim, then the run from `keep` on. Everything between is in the view. */
-export function refreshedRun(run: readonly AgentMessage[], keep: number, note: string): AgentMessage[] {
-  const task = run.find(m => m.role === 'user');
-  if (!keep || !task) return [...run];
-  const content = typeof task.content === 'string' ? [{ type: 'text' as const, text: task.content }] : task.content;
-  return [{ ...task, content: [...content, { type: 'text' as const, text: `\n\n${note}` }] }, ...run.slice(keep)];
-}

package/src/usage.ts

@@ -3,7 +3,7 @@ import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AssistantMessage, Usage } from '@earendil-works/pi-ai';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
-import { record } from './cache.ts';
+import { record } from './core/cache.ts';
 import { appendJson } from './store.ts';
 
 export type UsageRole = 'main' | 'subagent' | 'compactor' | 'import';

package/src/window-bridge.ts

@@ -2,7 +2,7 @@ import { chmodSync } from 'node:fs';
 import { createConnection, createServer, type Socket } from 'node:net';
 import { INTERRUPTED, type Children } from './agents.ts';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
-import { record } from './cache.ts';
+import { record } from './core/cache.ts';
 import { checkSocketPath, isWindows, profileSocket, removeStaleSocket } from './profiles.ts';
 import { textContent } from './transcript.ts';
 import { isActiveRun, type RunInfo } from './runs.ts';
@@ -24,6 +24,8 @@ export interface LiveState { state: string; model: string; streaming?: AgentMess
 export interface WindowEvent {
   kind: 'event'; name: 'started' | 'message' | 'status' | 'finished'; text: string; from?: 'user' | 'agent';
   message?: AgentMessage; live?: LiveState;
+  /** On `started` in an attached window: the subagent's spawn title, if it has one. */
+  title?: string;
 }
 type Frame = Request | Reply | WindowEvent;
 const errorText = (error: unknown) => error instanceof Error ? error.message : String(error);
@@ -38,7 +40,8 @@ function parse(value: unknown): Frame {
   const name = value.name, action = value.action, from = value.from;
   if (value.kind === 'event' && (name === 'started' || name === 'message' || name === 'status' || name === 'finished') && typeof value.text === 'string')
     return { kind: 'event', name, text: value.text, from: from === 'user' || from === 'agent' ? from : undefined,
-      message: isMessage(value.message) ? value.message : undefined, live: isLive(value.live) ? value.live : undefined };
+      message: isMessage(value.message) ? value.message : undefined, live: isLive(value.live) ? value.live : undefined,
+      title: typeof value.title === 'string' ? value.title : undefined };
   if (typeof value.id !== 'number' || !Number.isSafeInteger(value.id)) throw new Error('Invalid request ID');
   if (value.kind === 'reply' && (value.error === undefined || typeof value.error === 'string') && (value.text === undefined || typeof value.text === 'string'))
     return { kind: 'reply', id: value.id, error: value.error, text: value.text };
@@ -113,7 +116,7 @@ export async function serveWindows(directory: string, children: Children, availa
             const agents: AttachableAgent[] = available() ? children.history.list()
               .filter(info => !info.connected && !!children.live(info.id)
                 && (info.state === 'running' || info.state === 'waiting' || info.state === 'paused'))
-              .map(info => ({ id: info.id, task: info.task.slice(0, 200), state: info.state })) : [];
+              .map(info => ({ id: info.id, task: info.task.slice(0, 200), title: info.title, state: info.state })) : [];
             send({ kind: 'reply', id: frame.id, text: JSON.stringify(agents) }); return;
           } else if (frame.action === 'attach') {
             if (child) throw new Error('This window already has a conversation');
@@ -130,7 +133,7 @@ export async function serveWindows(directory: string, children: Children, availa
             // This socket borrows the existing session, never its lifetime, slot or report destination.
             // Other views (the main window's Agents page, other terminals) stay open alongside it.
             attached = true; child = id; finalMessages = live ? undefined : messages;
-            send({ kind: 'event', name: 'started', text: child });
+            send({ kind: 'event', name: 'started', text: child, title: info.title });
             drainMessages(messages, info);
           } else if (frame.action === 'start') {
             if (child) throw new Error('This window already has a conversation');
@@ -295,7 +298,7 @@ export async function connectWindow(directory: string, event: (event: WindowEven
   };
 }
 
-export interface AttachableAgent { id: string; task: string; state: string }
+export interface AttachableAgent { id: string; task: string; title?: string; state: string }
 /** Query the owner, not run metadata on disk: it knows which main/terminal views are actually open. */
 export async function listAttachableAgents(directory: string, timeout = 2000): Promise<AttachableAgent[]> {
   const deadline = Date.now() + timeout;
@@ -303,7 +306,7 @@ export async function listAttachableAgents(directory: string, timeout = 2000): P
   try {
     const agents: unknown = JSON.parse(await connection.request('list-agents', undefined, undefined, { timeout: Math.max(1, deadline - Date.now()) }) ?? '[]');
     if (!Array.isArray(agents) || !agents.every(agent => record(agent) && typeof agent.id === 'string'
-      && typeof agent.task === 'string' && (agent.state === 'running' || agent.state === 'waiting' || agent.state === 'paused')))
+      && typeof agent.task === 'string' && (agent.title === undefined || typeof agent.title === 'string') && (agent.state === 'running' || agent.state === 'waiting' || agent.state === 'paused')))
       throw new Error('Invalid background agent list from the profile owner');
     return agents;
   } finally { connection.close(); }