pi-optchat 0.7.2 → 0.8.0

package/src/settings.ts

@@ -3,13 +3,13 @@ import { NODE } from './memory.ts';
 /** Per-profile choices where OptChat departs from Victor's recipe. Each default is the recipe's behaviour unless noted. */
 export const SETTINGS = {
   subagentLevels: { kind: 'number', label: 'Subagent levels', default: 1, min: 1, unit: '',
-    description: 'How many levels of subagents. 1: only the main agent starts subagents, as in Victor\'s recipe. 2: those subagents may start their own, and so on.',
+    description: 'How many levels of subagents. 1: only the main agent starts subagents. 2: those subagents may start their own, and so on.',
     applies: 'Applies to subagents started or resumed after this.' },
   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.',
+  groupReports: { kind: 'toggle', label: 'Group subagent reports', default: false,
+    description: 'Off: each subagent reports as soon as it finishes, as in Victor\'s recipe. On: the subagents started by one spawn report together, in one message once the last of them 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.',

package/src/tools.ts

@@ -1,10 +1,14 @@
 import { Type } from 'typebox';
-import { flat, start, type Memory } from './memory.ts';
+import { flat, PAGE, start, type Memory } from './memory.ts';
+import { loadImages } from './images.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.';
+const ZOOM_ONLY = 'zoom is your only\nallowed mechanism ', ZOOM_AND_SEARCH = 'zoom and search are your only\nallowed mechanisms ';
+/** With Memory search on, the view doc allows search next to zoom; also turns a built prompt either way. */
+export const allowSearch = (prompt: string, on: boolean) => on ? prompt.replace(ZOOM_ONLY, ZOOM_AND_SEARCH) : prompt.replace(ZOOM_AND_SEARCH, ZOOM_ONLY);
 
 /** 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) {
@@ -25,9 +29,14 @@ export function searchPage(memory: Memory, text: string, before?: number) {
 
 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.',
-      parameters: Type.Object({ id: Type.Integer({ minimum: 0 }), n: Type.Integer({ minimum: 1 }) }),
-      async execute(_id: string, args: { id: number; n: number }) { return result(memory().zoom(args.id, args.n)); } },
+    { 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. 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.`,
+      parameters: Type.Object({ id: Type.Integer({ minimum: 0 }), n: Type.Integer({ minimum: 1 }),
+        offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: PAGE })) }),
+      async execute(_id: string, args: { id: number; n: number; offset?: number; limit?: number }) {
+        const m = memory(), text = m.zoom(args.id, args.n, args.offset, args.limit), page = result(text);
+        // A message's images come back with its text, as read returns a PNG; summaries stay text.
+        return args.n === 1 ? { ...page, content: [...page.content, ...loadImages(m.directory, 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)); } },

package/src/transcript.ts

@@ -1,13 +1,18 @@
+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, type Memory } from './memory.ts';
 import { record } from './cache.ts';
 import { DEFAULT_SETTINGS } from './settings.ts';
+import { imageRef, isImage } 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 and memory. */
+/** Subagent traffic to the main agent: a custom message on screen, a plain user message to the model, `work` in memory. */
 export const REPORT_TYPE = 'optchat-report';
+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;
@@ -15,24 +20,34 @@ export function textContent(content: unknown, images = true): string {
   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 && 'type' in part && part.type === 'image') return '[image attachment: available in Pi session; text memory does not preserve image bytes]';
+    if (images && isImage(part)) return imageRef(part);
     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
+/** 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) {
   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. */
+/** Pi's convertToLlm sends every custom message to the model as a user message. A shown one is part of the chat, so it
+ * becomes a user message here too; another extension's starts with "[customType] ", as the recipe marks background work, so
+ * the compactor never takes it for the user's words. A hidden one (display false), such as context an extension injects
+ * each turn, stays custom: the model still sees it, and memory and the replay leave it out. Reports reach the model and the
+ * previous-exchange replay as user messages; memory logs them as `work`. */
 export function asUser(message: AgentMessage): AgentMessage {
-  if (message.role !== 'custom' || message.customType !== REPORT_TYPE) return message;
-  return { role: 'user', content: textContent(message.content), timestamp: message.timestamp };
+  if (message.role !== 'custom' || !message.display) return message;
+  const { content, customType, timestamp } = message;
+  if (customType === REPORT_TYPE) return { role: 'user', content, timestamp };
+  const tag = `[${customType}] `;
+  if (typeof content === 'string') return { role: 'user', content: tag + content, timestamp };
+  const [first, ...rest] = content;
+  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('user', textContent(message.content), date, receipt);
+  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);
@@ -40,7 +55,9 @@ export function logMessage(memory: Memory, message: AgentMessage, receipt?: stri
     }
     if (message.stopReason === 'error' || message.stopReason === 'aborted')
       memory.append('echo', `Agent ${message.stopReason}: ${message.errorMessage ?? 'No further details'}`, date);
-  } else if (message.role === 'toolResult') memory.append('echo', cap(`${message.toolName}: ${textContent(message.content)}`), 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;
@@ -78,7 +95,7 @@ export function previousExchange(branch: readonly SessionEntry[], limit = PREVIO
 function latestExchange(branch: readonly SessionEntry[]) {
   let end = -1;
   let legacyEnd = branch.length;
-  const messages = (entries: readonly SessionEntry[]) => entries.flatMap(entry => entry.type === 'message' ? [asUser(entry.message)] : entry.type === 'custom_message' && entry.customType === REPORT_TYPE ? [asUser({ role: 'custom', customType: entry.customType, content: entry.content, display: entry.display, timestamp: Date.parse(entry.timestamp) })] : []);
+  const messages = (entries: readonly SessionEntry[]) => entries.flatMap(entry => entry.type === 'message' ? [asUser(entry.message)] : entry.type === 'custom_message' ? [asUser({ role: 'custom', customType: entry.customType, content: entry.content, display: entry.display, timestamp: Date.parse(entry.timestamp) })] : []);
   for (let i = branch.length - 1; i >= 0; i--) {
     const entry = branch[i];
     if (entry.type !== 'custom' || entry.customType !== RUN_BOUNDARY || !record(entry.data)) continue;

package/src/window-bridge.ts

@@ -3,13 +3,13 @@ import { createConnection, createServer, type Socket } from 'node:net';
 import type { Children } from './agents.ts';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import { record } from './cache.ts';
-import { checkSocketPath, profileSocket, removeStaleSocket } from './profiles.ts';
+import { checkSocketPath, isWindows, profileSocket, removeStaleSocket } from './profiles.ts';
 import { textContent } from './transcript.ts';
 import { isActiveRun } from './runs.ts';
 
-type Action = 'start' | 'say' | 'tell-main' | 'complete';
+type Action = 'start' | 'say' | 'tell-main' | 'answer' | 'complete';
 interface Request { kind: 'request'; id: number; action: Action; text?: string; cwd?: string }
-interface Reply { kind: 'reply'; id: number; error?: string }
+interface Reply { kind: 'reply'; id: number; error?: string; text?: string }
 /** A tool the subagent is running right now, with its streamed output so far. */
 export interface LiveTool { id: string; name: string; args: unknown; output?: unknown; started: number }
 /** What the subagent is doing between finished messages: its streaming reply and running tools. */
@@ -36,13 +36,16 @@ function parse(value: unknown): Frame {
     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 };
   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')) return { kind: 'reply', id: value.id, error: value.error };
-  if (value.kind === 'request' && (action === 'start' || action === 'say' || action === 'tell-main' || action === 'complete')
+  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 };
+  if (value.kind === 'request' && (action === 'start' || action === 'say' || action === 'tell-main' || action === 'answer' || action === 'complete')
     && (value.text === undefined || typeof value.text === 'string') && (value.cwd === undefined || typeof value.cwd === 'string'))
     return { kind: 'request', id: value.id, action, text: value.text, cwd: value.cwd };
   throw new Error('Invalid window message');
 }
 const SHORTENED = '\n[Display shortened; full text is saved in the transcript.]';
+/** Stays under the 4 MB frame bound even when JSON escapes some characters. */
+const ANSWER_LIMIT = 1_000_000;
 const shorten = (text: string, limit: number) => text.length > limit ? `${text.slice(0, limit)}${SHORTENED}` : text;
 /** Long text parts are cut and images dropped: the window only draws them, the owner keeps the full transcript. */
 function clipContent(content: unknown): unknown {
@@ -59,7 +62,7 @@ const clipOutput = (output: unknown) => record(output) ? { ...output, content: c
  */
 const fits = (value: unknown) => { try { return JSON.stringify(value).length < 1_000_000; } catch { return false; } };
 
-/** Local JSONL protocol, bounded before parsing; the socket is accessible only by its OS user. */
+/** Local JSONL protocol, bounded before parsing. On POSIX the socket file is mode 0600, so only its OS user can connect; a Windows named pipe has no file permissions, so its hashed profile name is the only separation. */
 function wire(socket: Socket, receive: (frame: Frame) => void) {
   let buffer = '';
   socket.setEncoding('utf8');
@@ -110,6 +113,12 @@ export async function serveWindows(directory: string, children: Children, availa
             send({ kind: 'event', name: 'started', text: child });
           } else {
             if (!child) throw new Error('Send your first request to start a conversation');
+            if (frame.action === 'answer') {
+              // The agent's last reply in full, not the display copy that events carry (headless `pi -p` prints it).
+              const text = children.live(child)?.session.getLastAssistantText() ?? '';
+              if (text.length > ANSWER_LIMIT) throw new Error(`The reply is over ${ANSWER_LIMIT.toLocaleString('en')} characters; the original Pi window has it in full`);
+              send({ kind: 'reply', id: frame.id, text }); return;
+            }
             if (frame.action === 'complete') {
               const live = children.live(child);
               if (live) drainMessages(live.session.messages, live.info.task);
@@ -142,14 +151,20 @@ export async function serveWindows(directory: string, children: Children, availa
     const timer = setInterval(() => {
       if (!child || socket.destroyed || ending) return;
       const live = children.live(child), info = children.history.records.get(child);
-      if (!info) return;
+      if (!info) {
+        // Deleted from the Agents page: end the window (and a headless join) instead of leaving it waiting forever.
+        ending = true;
+        send({ kind: 'event', name: 'finished', text: 'This conversation was deleted from the Agents page.' });
+        return;
+      }
       if (live) drainMessages(live.session.messages, info.task);
       const preview = live?.streaming && 'content' in live.streaming ? textContent(live.streaming.content).slice(-2000) : '';
       const text = `${info.state === 'waiting' ? 'Awaiting user or child reports' : info.state} · ${info.model}\n${live ? [...live.tools.values()].map(t => t.name).join(', ') : ''}\n${preview}`;
       let state: LiveState = { state: info.state, model: info.model,
         streaming: live?.streaming?.role === 'assistant' ? clip(live.streaming) : undefined,
         tools: live ? [...live.tools].map(([id, t]) => ({ id, name: t.name, args: t.args, output: clipOutput(t.output), started: t.started })) : [],
-        agents: [...children.history.records.values()].filter(run => run.parentId === child && isActiveRun(run)).length };
+        // A finished child counts until its report has reached this agent, so the agent never looks idle in between.
+        agents: [...children.history.records.values()].filter(run => run.parentId === child && (isActiveRun(run) || children.live(run.id))).length };
       if (!fits(state)) state = { ...state, streaming: undefined, tools: state.tools.map(t => ({ ...t, args: {}, output: undefined })) };
       const status = JSON.stringify(state);
       if (status !== lastStatus) { lastStatus = status; send({ kind: 'event', name: 'status', text, live: state }); }
@@ -160,33 +175,38 @@ export async function serveWindows(directory: string, children: Children, availa
         send({ kind: 'event', name: 'finished', text: info.handoff.text ?? 'Conversation ended.' });
       }
     }, 150);
-    socket.on('close', () => {
+    const { promise: ended, resolve } = Promise.withResolvers<void>();
+    const connection = ended.then(async () => {
       clearInterval(timer); controller.abort(); connections.delete(socket);
-      const cleanup = queue.then(async () => { if (child) await children.finish(child, closing ? 'owner-stopped' : 'disconnected'); });
-      track(cleanup);
+      await queue;
+      if (child) await children.finish(child, closing ? 'owner-stopped' : 'disconnected');
     });
+    track(connection);
+    socket.once('close', resolve);
   });
   await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(path, () => { server.off('error', reject); resolve(); }); });
-  chmodSync(path, 0o600);
+  if (!isWindows) chmodSync(path, 0o600);
   return async () => {
     closing = true;
-    const closed = new Promise<void>(resolve => server.close(() => resolve()));
+    const { promise: closed, resolve } = Promise.withResolvers<void>();
+    server.close(() => resolve());
     for (const socket of connections) socket.destroy();
     await closed;
-    await Promise.allSettled([...work]);
+    // A socket's close handler adds its cleanup after this point, so drain the tracked work instead of snapshotting it.
+    while (work.size) await Promise.allSettled([...work]);
   };
 }
 
 export async function connectWindow(directory: string, event: (event: WindowEvent) => void, disconnected: () => void) {
   const socket = createConnection(profileSocket(directory, 'windows'));
   let next = 0;
-  const pending = new Map<number, { resolve: () => void; reject: (error: Error) => void; timer: NodeJS.Timeout }>();
+  const pending = new Map<number, { resolve: (text?: string) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }>();
   const send = wire(socket, frame => {
     if (frame.kind === 'event') { event(frame); return; }
     if (frame.kind !== 'reply') { socket.destroy(); return; }
     const request = pending.get(frame.id); if (!request) return;
     clearTimeout(request.timer); pending.delete(frame.id);
-    if (frame.error) request.reject(new Error(frame.error)); else request.resolve();
+    if (frame.error) request.reject(new Error(frame.error)); else request.resolve(frame.text);
   });
   socket.on('close', () => {
     for (const request of pending.values()) { clearTimeout(request.timer); request.reject(new Error('Connection to the original Pi window was lost')); }
@@ -202,7 +222,7 @@ export async function connectWindow(directory: string, event: (event: WindowEven
       if (socket.destroyed) throw new Error('The original Pi window is disconnected');
       if (text && text.length > 256_000) throw new Error('Connected-window messages are limited to 256,000 characters');
       const id = next++;
-      await new Promise<void>((resolve, reject) => {
+      return await new Promise<string | undefined>((resolve, reject) => {
         const timer = setTimeout(() => { pending.delete(id); reject(new Error('Owner response timed out; closing this connection')); socket.destroy(); }, 120_000);
         pending.set(id, { resolve, reject, timer }); send({ kind: 'request', id, action, text, cwd });
       });
@@ -210,3 +230,42 @@ export async function connectWindow(directory: string, event: (event: WindowEven
     close() { socket.destroy(); },
   };
 }
+
+/**
+ * A headless run (`pi -p`) on a profile another Pi owns: one request to a connected subagent, its final reply,
+ * then `complete`, so the main agent gets the handoff. Connects up front, so a missing session fails before the prompt.
+ */
+export async function joinHeadless(directory: string) {
+  let last: AgentMessage | undefined;
+  let settle: (outcome: { ended?: string; lost?: true }) => void = () => {};
+  const outcome = new Promise<{ ended?: string; lost?: true }>(resolve => { settle = resolve; });
+  const connection = await connectWindow(directory, event => {
+    if (event.name === 'message' && event.from === 'agent') last = event.message;
+    // Waiting with no agents of its own means the agent is waiting for its user: the reply is done. A paused agent
+    // waits for the owner's user instead, and a finished one ends with `finished` once its last messages are sent.
+    else if (event.name === 'status' && event.live?.state === 'waiting' && !event.live.agents) settle({});
+    else if (event.name === 'finished') settle({ ended: event.text });
+  }, () => settle({ lost: true })).catch((error: unknown) => {
+    const code = record(error) ? error.code : undefined;
+    throw code === 'ENOENT' || code === 'ECONNREFUSED' ? new Error('No running OptChat session on this profile to join') : error;
+  });
+  let asked = false;
+  return {
+    async ask(text: string, cwd: string) {
+      if (asked) throw new Error('A headless run joins for one request');
+      asked = true;
+      await connection.request('start', text, cwd);
+      const { ended, lost } = await outcome;
+      const reply = last;
+      if (reply?.role === 'assistant' && (reply.stopReason === 'error' || reply.stopReason === 'aborted')) throw new Error(reply.errorMessage ?? `Request ${reply.stopReason}`);
+      if (lost) throw new Error('Connection to the original Pi window was lost');
+      if (ended !== undefined) throw new Error(`The conversation ended before a reply: ${ended}`);
+      // Events carry display copies cut for length, so the reply itself is fetched whole.
+      const answer = await connection.request('answer') ?? '';
+      await connection.request('complete');
+      connection.close();
+      return answer;
+    },
+    close() { connection.close(); },
+  };
+}