pi-optchat 0.6.1 → 0.6.3

package/README.md

@@ -69,7 +69,8 @@ Ask in plain words, for example: "Spawn an agent to investigate this repository
 
 - Children get the profile's memory view (frozen at launch), its instructions, read-only `zoom`/`date`, and normal coding tools plus your installed extensions.
 - Each child reports back on its own when it finishes. The parent stays alive to receive reports; it never polls.
-- The parent can send a running child guidance with `tell`.
+- In the main chat, subagent messages and reports appear in a dark grey box labelled `↳ subagent <id> · still running` or `· report`, so they don't look like something you typed. The model still receives them as ordinary user messages. (One exception: reports recovered at startup, before your first message in the session, still show as plain user messages.)
+- The parent can send a running child guidance with `tell`, and the child can message its parent mid-run with `tell_parent` (a question, an early finding). It reaches the parent like a report, marked "still running": between tool calls if the parent is busy, or waking it if it's waiting.
 - Delegation goes up to three levels below the main agent (child, grandchild, great-grandchild).
 - At most 8 agents can be active per profile, including parents waiting on descendants. Going over a limit returns an error; there is no queue.
 - Stopping an agent stops its whole subtree. A failed parent stops its descendants.
@@ -140,7 +141,7 @@ Each profile is locked to one Pi process. If you open the same profile in a seco
 
 - Your first message starts a subagent in the second window's working directory. Later messages continue the same conversation.
 - The subagent runs inside the original process, which stays the only writer of memory. It appears in the original window's inspector and uses one of the 8 agent slots. While it is open, the original window can't switch profile or import.
-- The main agent is told when the conversation starts. Use `/tell-main <message>` to message it yourself; the subagent has a `tell_main` tool, and the main agent replies with `tell`. Routine turns don't wake the main agent.
+- The main agent is told when the conversation starts. Use `/tell-main <message>` to message it yourself; the subagent can use `tell_parent`, and the main agent replies with `tell`. Routine turns don't wake the main agent.
 - Run `/complete` when done. The window closes, remaining work stops, and the compactor writes a handoff for the main agent: decisions, changes, evidence, failures, unfinished work, and links to the transcripts.
 - Closing or force-quitting the window also produces a handoff, marked **interrupted**.
 - If the original window is closed cleanly, handoffs are delivered on next start. If it is killed, reopening the profile recovers unfinished handoffs (work is not restarted).

package/package.json

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

package/src/agents.ts

@@ -115,7 +115,8 @@ export class Children {
         if (cancelled()) throw new Error('Parent or profile is stopping.');
         const id = randomUUID().slice(0, 8), directory = task.cwd ?? cwd;
         const delegation = depth < 3 ? 'You may delegate parts of your assigned task with spawn when useful. Child reports arrive automatically after your current run ends; the harness keeps you alive to receive them. Never poll, sleep, or wait in a tool for children. Finish your current work and return; you will be prompted with their results. The profile allows 8 active agents total.' : 'You are at the maximum delegation depth. Complete your task with your own tools.';
-        const instructions = [this.instructions(), delegation, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_main for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.' : ''].filter(Boolean).join('\n\n');
+        const instructions = [this.instructions(), delegation, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_parent for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.'
+          : 'Use tell_parent only when your parent needs something now (a blocking question, an important early finding, or when asked to). Your final answer is delivered automatically; do not repeat it with tell_parent.'].filter(Boolean).join('\n\n');
         // The user's settings list their installed packages; a copy in memory keeps the child from writing them back.
         const settingsManager = SettingsManager.inMemory({ ...SettingsManager.create(directory, getAgentDir()).getSettings(), compaction: { enabled: false }, cacheWarming: 'off' });
         const loader = new DefaultResourceLoader({ cwd: directory, agentDir: getAgentDir(), settingsManager,
@@ -135,12 +136,7 @@ export class Children {
         await loader.reload();
         const { session } = await (this.options.createSession ?? createAgentSession)({ cwd: directory, resourceLoader: loader, settingsManager,
           model, thinkingLevel: selected.thinking, sessionManager: SessionManager.create(directory, join(this.profileDirectory, 'runs')),
-          customTools: [...memoryTools(() => this.memory), ...(depth < 3 ? this.delegationTools(id, directory) : []), ...(connected ? [{
-            name: 'tell_main', label: 'Message main agent', description: 'Send the main agent a question or important finding. Its reply can arrive as guidance; continue useful work instead of polling.',
-            parameters: Type.Object({ message: Type.String() }), execute: async (_id: string, args: { message: string }) => {
-              await this.report(`[${id}] Connected agent message: ${args.message}`); return result('Message sent to the main agent.');
-            },
-          }] : [])],
+          customTools: [...memoryTools(() => this.memory), ...(depth < 3 ? this.delegationTools(id, directory) : []), this.parentTool(id, parentId, connected)],
           excludeTools: depth < 3 ? [] : ['spawn', 'tell'],
         });
         await session.bindExtensions({});
@@ -185,6 +181,24 @@ export class Children {
       },
     }];
   }
+  /** Lets a child message its parent mid-run, the way tell lets the parent guide it. */
+  private parentTool(id: string, parentId: string | undefined, connected: boolean) {
+    return { name: 'tell_parent', label: parentId ? 'Message parent agent' : 'Message main agent',
+      description: `Send ${parentId ? 'your parent agent' : 'the main agent'} a question or important finding while you keep working. Its reply can arrive as guidance; continue useful work instead of polling. Your final answer is delivered automatically.`,
+      parameters: Type.Object({ message: Type.String() }), execute: async (_id: string, args: { message: string }) => {
+        const message = args.message.trim();
+        if (!message) throw new Error('Message is empty.');
+        const text = `[${id}] ${connected ? 'Connected agent message' : 'Message from subagent (still running)'}: ${message}`;
+        if (!parentId) { await this.report(text); return result('Message sent to the main agent.'); }
+        const parent = this.running.get(parentId);
+        if (!parent || !['running', 'waiting'].includes(parent.info.state)) throw new Error('Your parent is no longer running.');
+        if (parent.info.state === 'waiting') { parent.pendingReports.push(text); parent.wake?.(); }
+        else await parent.session.steer(text);
+        this.changed();
+        return result(`Message sent to parent ${parentId}.`);
+      },
+    };
+  }
   private directChildren(id: string) { return [...this.running.values()].filter(c => c.info.parentId === id); }
   private async execute(live: LiveRun, view: string) {
     const { session, info } = live;

package/src/index.ts

@@ -11,7 +11,8 @@ import { createCompressor } from './compactor.ts';
 import { atomicWrite, createProfile, instructions, lastProfile, listProfiles, loadConfig, lockProfile, profilePath, rememberProfile, saveConfig, ProfileBusyError, type ProfileConfig } from './profiles.ts';
 import { MASTER, VIEW_DOC } from './prompts.ts';
 import { cachePayload, record } from './cache.ts';
-import { boundedMessage, buildContext, logMessage, previousExchange, RUN_BOUNDARY, textContent } from './transcript.ts';
+import { asUser, boundedMessage, buildContext, logMessage, previousExchange, REPORT_TYPE, RUN_BOUNDARY, textContent } from './transcript.ts';
+import { registerReportRenderer } from './report-message.ts';
 import { memoryTools, result } from './tools.ts';
 import { Children } from './agents.ts';
 import { exportBrowser } from './browser.ts';
@@ -76,10 +77,16 @@ export default function optchat(pi: ExtensionAPI) {
       }
     }
   };
+  // Shown as a dark background box, not as the user's own message. Before this profile has run once there is no
+  // built system prompt to reuse, so that rare case still goes through Pi's normal prompt path as a user message.
+  const sendReport = (text: string) => {
+    if (prompt) pi.sendMessage({ customType: REPORT_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: 'steer' });
+    else pi.sendUserMessage(text, { deliverAs: 'steer', expandPromptTemplates: false });
+  };
   const deliverReport = async (text: string, once = false) => {
     if (once && (active?.memory.root.some(e => e.receipt === reportReceipt(text)) || reports.includes(text))) return;
     reports.push(text); saveReports();
-    if (!stopping) pi.sendUserMessage(text, { deliverAs: 'steer', expandPromptTemplates: false });
+    if (!stopping) sendReport(text);
   };
   const stop = async () => {
     remote?.close(); remote = undefined;
@@ -95,7 +102,7 @@ export default function optchat(pi: ExtensionAPI) {
       await checkpoint(old.dir);
     } finally {
       await old.memory.close(); await old.unlock(); active = undefined;
-      run = []; previous = []; logged = 0; view = undefined; runStarted = false; receipts.clear();
+      run = []; previous = []; logged = 0; view = undefined; runStarted = false; receipts.clear(); prompt = '';
     }
   };
   const chooseProfile = async (ctx: ExtensionContext): Promise<string | undefined> => {
@@ -143,7 +150,7 @@ export default function optchat(pi: ExtensionAPI) {
       ctx.ui.notify(`OptChat · ${name} · ${memory.root.length} messages\nCompactor: ${config.compactor.provider}/${config.compactor.model} (${config.compactor.thinking})`, 'info');
       const queuedReports = [...reports];
       if (!pendingImport(dir)) recovery = children.recoverHandoffs().catch(error => ctx.ui.notify(`Handoff recovery: ${errorText(error)}`, 'error'));
-      setImmediate(() => { if (active?.memory === memory && !pendingImport(dir)) for (const text of queuedReports) pi.sendUserMessage(text, { deliverAs: 'steer', expandPromptTemplates: false }); });
+      setImmediate(() => { if (active?.memory === memory && !pendingImport(dir)) for (const text of queuedReports) sendReport(text); });
     } catch (error) {
       await closeWindows?.(); closeWindows = undefined;
       if (active && active.memory === openingMemory) {
@@ -195,10 +202,15 @@ export default function optchat(pi: ExtensionAPI) {
     }
     return { action: 'continue' };
   });
-  pi.on('before_agent_start', (event, ctx) => {
+  const startRun = (ctx: ExtensionContext) => {
     flush(); run = []; logged = 0; view = undefined; runStarted = true;
     previous = previousExchange(ctx.sessionManager.getBranch());
     pi.appendEntry(RUN_BOUNDARY, { state: 'start' });
+  };
+  // A report sent while Pi is idle starts its run without before_agent_start; it reuses the last built prompt.
+  pi.on('agent_start', (_event, ctx) => { if (active && !runStarted) startRun(ctx); });
+  pi.on('before_agent_start', (event, ctx) => {
+    startRun(ctx);
     const a = required();
     // Pi's own prompt sections (AGENTS.md files, skills, cwd) stay; the profile's instructions go last.
     event.systemPromptOptions.customPrompt = `${MASTER}\n\n${VIEW_DOC}\n\nFor conversational continuity, the memory view may be followed by the immediately preceding completed exchange (its user requests and final answer, in full text), then the new input. Use that exact wording to understand follow-ups; older exchanges and previous tool output remain accessible through memory and zoom.`;
@@ -207,7 +219,8 @@ export default function optchat(pi: ExtensionAPI) {
   });
   pi.on('message_end', (event, ctx) => {
     if (!active || !runStarted) return;
-    const message = boundedMessage(event.message);
+    const bounded = boundedMessage(event.message);
+    const message = asUser(bounded);
     if (message.role === 'user') {
       try {
         const text = textContent(message.content);
@@ -223,7 +236,7 @@ export default function optchat(pi: ExtensionAPI) {
     if (view !== undefined) {
       try { flush(); } catch (error) { ctx.abort(); fault = errorText(error); ctx.ui.notify(fault, 'error'); }
     }
-    if (message !== event.message) return { message };
+    if (bounded !== event.message) return { message: bounded };
   });
   pi.on('context_with_system', async (event, ctx) => {
     try {
@@ -268,6 +281,7 @@ export default function optchat(pi: ExtensionAPI) {
     }
   });
   registerConnectedRenderer(pi);
+  registerReportRenderer(pi);
   for (const tool of memoryTools(() => required().memory)) pi.registerTool(tool);
   pi.registerTool({ name: 'spawn', label: 'Spawn background agents',
     description: 'Start background subagents, returning IDs immediately. Use only when the user asks. Each receives the current memory view and read-only zoom/date. Children may delegate two more levels; the whole profile allows 8 active agents. Completion reports arrive automatically; never poll or sleep waiting for them.',

package/src/report-message.ts

@@ -0,0 +1,32 @@
+import { getMarkdownTheme, type ExtensionAPI, type Theme } from '@earendil-works/pi-coding-agent';
+import { Box, Markdown, Text } from '@earendil-works/pi-tui';
+import { REPORT_TYPE, textContent } from './transcript.ts';
+
+const HEAD = /^\[([0-9a-f]{8})\] (?:(Message from subagent \(still running\)|Connected agent message): )?/;
+
+/** Split "[id] Message from subagent (still running): body" into a short label and the body. */
+export function reportParts(text: string) {
+  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) };
+}
+
+/** The theme's neutral grey, darkened on dark themes so the box recedes behind the conversation. */
+function darkBackground(theme: Theme) {
+  const rgb = /^\x1b\[48;2;(\d+);(\d+);(\d+)m$/.exec(theme.getBgAnsi('toolPendingBg'))?.slice(1).map(Number);
+  if (!rgb || rgb[0] + rgb[1] + rgb[2] > 3 * 128) return (text: string) => theme.bg('toolPendingBg', text);
+  const open = `\x1b[48;2;${rgb.map(c => Math.round(c * 0.7)).join(';')}m`;
+  return (text: string) => `${open}${text}\x1b[49m`;
+}
+
+/** Background traffic: a dark neutral box with dim text, so it never looks like something the user typed. */
+export function registerReportRenderer(pi: ExtensionAPI) {
+  pi.registerMessageRenderer(REPORT_TYPE, (message, { outputPad }, theme) => {
+    const { label, body } = reportParts(textContent(message.content));
+    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) }));
+    return box;
+  });
+}

package/src/transcript.ts

@@ -5,6 +5,8 @@ import { cap, type Memory } from './memory.ts';
 import { record } from './cache.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. */
+export const REPORT_TYPE = 'optchat-report';
 
 export function textContent(content: unknown): string {
   if (typeof content === 'string') return content;
@@ -16,6 +18,11 @@ export function textContent(content: unknown): string {
     return '';
   }).filter(Boolean).join('\n');
 }
+/** Reports reach the model, memory and the previous-exchange replay exactly as the user messages they used to be. */
+export function asUser(message: AgentMessage): AgentMessage {
+  if (message.role !== 'custom' || message.customType !== REPORT_TYPE) return message;
+  return { role: 'user', content: textContent(message.content), timestamp: message.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);
@@ -54,7 +61,7 @@ function completedExchange(history: readonly AgentMessage[]) {
 export function previousExchange(branch: readonly SessionEntry[]) {
   let end = -1;
   let legacyEnd = branch.length;
-  const messages = (entries: readonly SessionEntry[]) => entries.flatMap(entry => entry.type === 'message' ? [entry.message] : []);
+  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) })] : []);
   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;