pi-optchat 0.8.7 → 0.8.9

package/docs/victor-recipe.md

@@ -12,7 +12,7 @@ The source remains upstream rather than duplicating the full article here. Its p
 
 - `src/memory.ts`: append-only log, binary summary tree, compression scheduling (§4 of the 2026-10-08 revision: a message's summary starts once fewer than 8 lines before it are unbuilt, a merge once both halves are built, kept in a queue so the tree is never scanned for work), the compactions' own view (§4: the view merged further to 16,000-32,000 bytes, ending at the node; unlike the recipe, a line not built yet shows as a placeholder instead of ending it, so a summary still sees the built lines after it), the view (§3.2: the most due pair, measured from its last message, merges in one batch from 128,000 down to 64,000 bytes, and the view is saved to `view.json` rather than refolded at start), zoom/date, and the opt-in text search over original messages (`src/tools.ts` has the tool; not in the recipe, off by default).
 - `src/compactor.ts`: contextual compression and size retries, with the 2026-10-08 revision's task (a 512-dash ruler for the size) and its "Too long" retry, verbatim. The compactions' view shows each line under its `id+n|` head, as the task's line ids need, so a reply that copies a head has it removed.
-- `src/cache.ts`: Anthropic cache marks: the view in blocks of 4 lines, one mark on the last whole block and one at the request's end, as in recipe §3.3, plus two marks 20 and 40 blocks before the last. Anthropic looks back only 20 blocks from a mark, so with the recipe's one view mark a turn that added more than 80 lines, such as 40 tool calls and their results, made the next turn rewrite the whole view. OpenAI requests get no marks: GPT-5.6 and GPT-6 Luna reject the recipe's `prompt_cache_breakpoint` with a 400 (found by @aaaxn), so they rely on implicit prefix caching. OptChat doesn't set `reasoning.context` either: GPT-5.6 already defaults to the recipe's `"all_turns"`, and OpenAI documents it only for GPT-5.6 and GPT-6.1 Sol.
+- `src/cache.ts`: Anthropic cache marks: the view in blocks of 4 lines, one mark on the last whole block and one at the request's end, as in recipe §3.3 (a compaction leaves its end unmarked, as Unii does: its task is never sent again), plus two marks 20 and 40 blocks before the last. Anthropic looks back only 20 blocks from a mark, so with the recipe's one view mark a turn that added more than 80 lines, such as 40 tool calls and their results, made the next turn rewrite the whole view. OpenAI requests get no marks: GPT-5.6 and GPT-6 Luna reject the recipe's `prompt_cache_breakpoint` with a 400 (found by @aaaxn), so they rely on implicit prefix caching. OptChat doesn't set `reasoning.context` either: GPT-5.6 already defaults to the recipe's `"all_turns"`, and OpenAI documents it only for GPT-5.6 and GPT-6.1 Sol.
 - `src/transcript.ts`: fresh context per parent run, current-run tool loop retained. The previous completed exchange is also retained in full text (left out if over 16,000 bytes by default), an intentional addition to the summary-only recipe for conversational continuity.
 - `src/agents.ts`: asynchronous Pi SDK children and automatic completion reports.
 - `src/settings.ts`: per-profile settings for the departures from the recipe. Defaults are the recipe's (no memory search), except the previous exchange (on), the summary size tolerance (640 bytes, against the recipe's strict 512) and the turn refresh threshold (30%, where the recipe has none). Grouped subagent reports are off by default, as in the revised recipe, which reports each subagent on its own.

package/package.json

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

package/src/agents.ts

@@ -23,7 +23,7 @@ import { THINKING } from './profiles.ts';
 export interface LiveRun {
   session: AgentSession; info: RunInfo; updated: number; streaming?: AgentMessage;
   tools: Map<string, { name: string; args: unknown; output?: unknown; started: number }>;
-  pendingReports: string[]; pendingGuidance: string[]; wake?: () => void; completion?: Promise<void>;
+  pendingReports: string[]; pendingGuidance: string[]; wake?: () => void; completion?: Promise<void>; primed?: Promise<unknown>;
   /** Set by the user's interrupt: the queued guidance the run continues with once its current step is aborted; with none, it pauses. */
   interruption?: RunInfo['guidance'];
   /** Messages being steered back into Pi's queue after it was cleared; other queue changes wait for it. */
@@ -98,6 +98,20 @@ export function subagentCompaction(contextWindow: number, fraction: number) {
   if (!(fraction > 0)) return { enabled: true };
   return { enabled: true, reserveTokens: Math.max(16_384, Math.round(contextWindow * (1 - fraction) - VIEW / 4)) };
 }
+/** Waits for `promise`, or until `signal` aborts. */
+async function abortable(promise: Promise<unknown>, signal?: AbortSignal) {
+  let stop = () => {};
+  const aborted = new Promise<void>(resolve => { stop = resolve; });
+  signal?.addEventListener('abort', stop, { once: true });
+  if (signal?.aborted) stop();
+  try { await Promise.race([promise, aborted]); } finally { signal?.removeEventListener('abort', stop); }
+}
+/** Resolves once the session's model starts answering, or its request ends without an answer. */
+const answering = (session: AgentSession) => new Promise<void>(resolve => {
+  const off = session.subscribe(event => {
+    if (event.type === 'message_update' || event.type === 'agent_end' || event.type === 'message_end' && event.message.role === 'assistant') { off(); resolve(); }
+  });
+});
 export class Children {
   private readonly running = new Map<string, LiveRun>();
   readonly history: RunHistory;
@@ -224,10 +238,14 @@ export class Children {
     const launched = await this.track(this.launchBatch({ tasks: runs, cwd, depth, parentId, connected, signal, cancelled }));
     // Grouped, the last child of this spawn to finish delivers every report; otherwise each reports on its own.
     const batch = groupReports && !connected ? { ids: launched.map(c => c.info.id), reports: new Map<string, string>() } : undefined;
+    // Siblings on one model and directory send the same system prompt, tools and view. Anthropic can't read a cache entry
+    // still being written, so their first requests wait until the first sibling starts answering and read its entry instead.
+    const [first] = launched, answered = launched.length > 1 && first.session.model?.api === 'anthropic-messages' ? answering(first.session) : undefined;
     for (const live of launched) {
       live.batch = batch;
       const work = this.execute(live, `${view}\n\nYour task:\n${live.info.task}`).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
         .finally(() => { this.completions.delete(work); this.changed(); });
+      if (live === first && answered) for (const sibling of launched.slice(1)) if ((['model', 'thinking', 'cwd'] as const).every(k => sibling.info[k] === first.info[k])) sibling.primed = Promise.race([answered, work]);
       this.completions.add(work);
       live.completion = work;
     }
@@ -295,7 +313,12 @@ export class Children {
           event.systemPromptOptions.customPrompt = allowSearch(`${SUBAGENT}\n\n${VIEW_DOC}${memorySearch ? SEARCH_DOC : ''}`, memorySearch);
           event.systemPromptOptions.sections.instructions = instructions;
         });
-        pi.on('before_provider_request', (event, ctx) => ctx.model?.api === 'anthropic-messages' ? cachePayload(event.payload) : event.payload);
+        pi.on('before_provider_request', async (event, ctx) => {
+          // Set by launch for a sibling's first request; a stop or an interrupt aborts the request, which ends the wait.
+          const live = this.running.get(id), primed = live?.primed;
+          if (live && primed) { live.primed = undefined; await abortable(primed, ctx.signal); }
+          return ctx.model?.api === 'anthropic-messages' ? cachePayload(event.payload) : event.payload;
+        });
       }],
     });
     await loader.reload();

package/src/cache.ts

@@ -33,8 +33,9 @@ function lastBlock(message: Record<string, unknown>) {
 /** Anthropic: marks on the view (see MARKS) plus a mark at the end of the request, so the next call finds the last one's entry
  * and pays only for the lines after it. The end mark sits on the last block itself rather than as top-level automatic caching:
  * a proxy or setting that gives block marks a 1h TTL makes Anthropic refuse a top-level mark, whose TTL defaults to 5m, on the
- * same block ("Top-level cache_control has ttl='5m' but the target block already has cache_control with ttl='1h'"). */
-export function cachePayload(payload: unknown): unknown {
+ * same block ("Top-level cache_control has ttl='5m' but the target block already has cache_control with ttl='1h'").
+ * `end: false` leaves the end unmarked: a compaction's task is never sent again, so marking it would only write it at 1.25× (#197). */
+export function cachePayload(payload: unknown, { end: markEnd = true } = {}): unknown {
   if (!record(payload) || !Array.isArray(payload.messages)) return payload;
   const messages = payload.messages;
   const view = new Set<unknown>();
@@ -42,9 +43,12 @@ export function cachePayload(payload: unknown): unknown {
     if (!record(message) || message.role !== 'user' || !Array.isArray(message.content)) continue;
     const at = message.content.findIndex((block: unknown) => record(block) && block.type === 'text' && typeof block.text === 'string' && isView(block.text));
     if (at < 0) continue;
-    const pieces = splitView(message.content[at].text), marked = new Set(MARKS.map(back => pieces.length - 2 - back));
+    // A subagent's task follows the view in the same text. Lines never hold a newline, so the first one before </chat> ends the view;
+    // the task goes in its own block, so the view's marks fall on lines its siblings share and they can read one another's entry.
+    const text: string = message.content[at].text, close = text.indexOf('\n</chat>'), end = close < 0 ? text.length : close + '\n</chat>'.length;
+    const pieces = splitView(text.slice(0, end)), marked = new Set(MARKS.map(back => pieces.length - 2 - back));
     const blocks = pieces.map((text, j) => ({ type: 'text', text, ...(marked.has(j) ? { cache_control: { type: 'ephemeral' } } : {}) }));
-    message.content.splice(at, 1, ...blocks);
+    message.content.splice(at, 1, ...blocks, ...(end < text.length ? [{ type: 'text', text: text.slice(end) }] : []));
     for (const block of blocks) view.add(block);
     break;
   }
@@ -62,7 +66,7 @@ export function cachePayload(payload: unknown): unknown {
   // Pi may end the request with an empty system message carrying settings (effort); it holds nothing to cache.
   const [before, last] = messages.filter(message => !record(message) || message.role !== 'system').slice(-2);
   const turn = isAtWork(last) && record(before) && before.role === 'user' ? lastBlock(before) : undefined;
-  const end = turn ?? endBlock(messages);
+  const end = markEnd ? turn ?? endBlock(messages) : undefined;
   if (end) end.cache_control = { type: 'ephemeral' };
   return payload;
 }

package/src/compactor.ts

@@ -42,10 +42,21 @@ function primeFirst() {
     };
   };
 }
+/** Pi's agent loop retries a dropped connection itself; streamSimple doesn't, so a transient error is asked again before it surfaces. */
+export async function retryTransient(ask: () => Promise<AssistantMessage>, onReply: (reply: AssistantMessage) => void,
+  delays: readonly number[] = [1000, 2000], signal?: AbortSignal) {
+  for (let retry = 0; ; retry++) {
+    const reply = await ask();
+    onReply(reply);
+    if (retry >= delays.length || !isRetryableAssistantError(reply)) return reply;
+    await sleep(delays[retry], undefined, { signal });
+  }
+}
+
 /** The model is asked for 512 bytes; `accepted` is the longest line kept without a retry (the profile's summary size tolerance). */
 export function createCompressor(registry: ModelRegistry, choice: () => ModelChoice,
   onUsage: (message: AssistantMessage) => void = () => {}, accepted = () => DEFAULT_SETTINGS.summaryAcceptBytes,
-  retryDelays: readonly number[] = [1000, 2000]): Compressor {
+  retryDelays?: readonly number[]): Compressor {
   const gate = primeFirst();
   return async (input, signal) => {
     const selected = choice();
@@ -65,26 +76,19 @@ export function createCompressor(registry: ModelRegistry, choice: () => ModelCho
           // A shared session id is the OpenAI prompt-cache key; SSE because over a websocket Codex would chain unrelated parallel calls on one cached connection.
           sessionId: 'optchat-compactor', transport: 'sse',
           reasoning: thinking, signal, cacheRetention: 'short',
-          onPayload: payload => model.api === 'anthropic-messages' ? cachePayload(payload) : payload,
+          onPayload: payload => model.api === 'anthropic-messages' ? cachePayload(payload, { end: false }) : payload,
         });
         // The cache entry is usable once the model starts answering.
         for await (const event of stream) if (event.type !== 'start') { warmed(event.type !== 'error'); break; }
         return await stream.result();
       } finally { warmed(false); }
     };
-    // Pi's agent loop retries a dropped connection itself; streamSimple doesn't, so a transient error is asked again before it surfaces.
-    const answer = async () => {
-      for (let retry = 0; ; retry++) {
-        const reply = await ask();
-        onUsage(reply);
-        if (retry >= retryDelays.length || !isRetryableAssistantError(reply)) return reply;
-        await sleep(retryDelays[retry], undefined, { signal });
-      }
-    };
+    const answer = () => retryTransient(ask, onUsage, retryDelays, signal);
     for (let attempt = 0; attempt < 5; attempt++) {
       const reply = await answer();
       // A stop reason means the model answered: a refusal or a content filter, which asking again repeats.
-      if (reply.stopReason === 'error' && reply.rawStopReason !== undefined && !isRetryableAssistantError(reply))
+      // A provider's own 'error' stop (Mistral) is a failure on its side, not an answer: a plain error, tried again later.
+      if (reply.stopReason === 'error' && reply.rawStopReason !== undefined && reply.rawStopReason !== 'error' && !isRetryableAssistantError(reply))
         throw new Refused(reply.errorMessage ?? `Compactor stopped: ${reply.rawStopReason}`);
       if (reply.stopReason === 'error' || reply.stopReason === 'aborted') throw new Error(reply.errorMessage ?? `Compactor ${reply.stopReason}`);
       // A reply cut off at the token limit, or one that calls a tool, is no summary: ask again.

package/src/handoff.ts

@@ -1,7 +1,7 @@
 import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { AssistantMessage } from '@earendil-works/pi-ai';
-import { reasoningFor, type ModelChoice } from './compactor.ts';
+import { reasoningFor, retryTransient, type ModelChoice } from './compactor.ts';
 import { HANDOFF } from './prompts.ts';
 import type { RunInfo } from './runs.ts';
 import { textContent } from './transcript.ts';
@@ -30,7 +30,7 @@ function formatEvidence({ run, messages, transcriptError }: HandoffEvidence) {
 
 /** Summarize in one call when possible; otherwise fold chunks with the prior handoff included in the budget. */
 export function createHandoffSummarizer(registry: ModelRegistry, choice: () => ModelChoice,
-  usage: (message: AssistantMessage) => void) {
+  usage: (message: AssistantMessage) => void, retryDelays?: readonly number[]) {
   return async (run: RunInfo, messages: AgentMessage[], descendants: HandoffEvidence[] = []) => {
     const selected = choice(), model = registry.find(selected.provider, selected.model);
     if (!model) throw new Error('Profile compactor model unavailable');
@@ -50,11 +50,10 @@ export function createHandoffSummarizer(registry: ModelRegistry, choice: () => M
       let end = Math.min(transcript.length, offset + available);
       // Keep multibyte characters intact at chunk boundaries.
       while (end < transcript.length && (transcript[end] & 0xc0) === 0x80) end--;
-      const reply = await registry.streamSimple(model, {
+      const reply = await retryTransient(() => registry.streamSimple(model, {
         systemPrompt: HANDOFF,
         messages: [{ role: 'user', timestamp: Date.now(), content: prefix + transcript.subarray(offset, end).toString('utf8') }],
-      }, { reasoning: reasoningFor(model, selected.thinking), maxTokens, signal: AbortSignal.timeout(300_000) }).result();
-      usage(reply);
+      }, { reasoning: reasoningFor(model, selected.thinking), maxTokens, signal: AbortSignal.timeout(300_000) }).result(), usage, retryDelays);
       if (reply.stopReason === 'error' || reply.stopReason === 'aborted') throw new Error(reply.errorMessage ?? reply.stopReason);
       if (reply.stopReason === 'length') throw new Error('Handoff hit the model output limit before finishing');
       summary = textContent(reply.content).trim();

package/src/memory.ts

@@ -279,14 +279,13 @@ export class Memory {
       }).finally(() => { this.busy.delete(id); this.schedule(); this.events.emit('change'); });
       this.busy.set(id, promise);
     };
-    // A message's node starts once fewer than `jobs` lines before it are unbuilt; a merge, once both halves are built.
-    let ahead = 0;
-    for (const i of this.unbuilt) {
-      if (ahead++ === this.jobs) break;
-      if (this.busy.size >= this.jobs) return;
-      run({ l: 0, i });
-    }
-    for (const part of this.merges.values()) {
+    // A message's node starts once fewer than `jobs` lines before it are unbuilt; a merge, once both halves are built. They start
+    // in the order of the context they end at, a merge first at a tie, as Unii's do (#194): messages first left the merges waiting
+    // through a backlog, so the views ran over budget and changed at every node built, and compactions read about 60% from the cache.
+    const ready: Part[] = [];
+    for (const i of this.unbuilt) { if (ready.length === this.jobs) break; ready.push({ l: 0, i }); }
+    const at = (part: Part) => part.l ? end(part) : part.i;
+    for (const part of [...ready, ...this.merges.values()].sort((a, b) => at(a) - at(b) || b.l - a.l)) {
       if (this.busy.size >= this.jobs) return;
       run(part);
     }