bloby-bot 0.70.12 → 0.70.13

package/supervisor/harnesses/pi/index.ts

@@ -33,7 +33,6 @@ import { createAsyncQueue, type AsyncQueue } from './async-queue.js';
 import { createPiSession, type PiSessionEvent, type PiSessionAuth } from './session.js';
 import { getPiSubProvider, getCatalogModel } from './sub-providers.js';
 import { readPiAuth } from './auth-storage.js';
-import { streamProvider } from './providers/stream.js';
 import type { PiMessage } from './providers/types.js';
 import { toolDefsForProvider } from './tools/registry.js';
 import type { PiTaskHost } from './tools/types.js';
@@ -264,6 +263,11 @@ function resolveAuth(): { ok: true; auth: PiSessionAuth } | { ok: false; error:
       maxTokensField: sub.maxTokensField,
       includeStreamUsage: sub.noStreamUsage ? false : undefined,
       contextWindow,
+      // Text-only models 400 on image blocks AND the stuck image re-fails
+      // every later message (audit C-8) — the session downgrades images to
+      // placeholders when the catalog says no vision. Unknown (dynamic
+      // sub-providers) ⇒ undefined ⇒ assume vision.
+      supportsImages: catalog?.input ? catalog.input.includes('image') : undefined,
     },
   };
 }
@@ -349,7 +353,7 @@ function createTaskHost(conv: LiveConversation, getAuth: () => PiSessionAuth): P
       // Honor the agent config's tool restrictions (claude applies these via
       // the SDK's tools/disallowedTools options — e.g. a future researcher
       // agent with disallowedTools: ['Write','Edit']).
-      let childTools = toolDefsForProvider({ forSubagent: true });
+      let childTools = toolDefsForProvider();
       if (Array.isArray(cfg.tools) && cfg.tools.length > 0) {
         childTools = childTools.filter((t) => cfg.tools.includes(t.name));
       }
@@ -491,6 +495,23 @@ function recentToPiMessages(messages: RecentMessage[] | undefined): PiMessage[]
   }));
 }
 
+const DOC_INLINE_CAP_CHARS = 48_000;
+
+/** Text-like documents can ride inline as decoded text on every flavor. */
+function isTextLikeMediaType(mediaType: string): boolean {
+  const mt = (mediaType || '').toLowerCase();
+  return (
+    mt.startsWith('text/') ||
+    mt.includes('json') ||
+    mt.includes('xml') ||
+    mt.includes('yaml') ||
+    mt.includes('csv') ||
+    mt.includes('javascript') ||
+    mt.includes('typescript') ||
+    mt === 'application/x-sh'
+  );
+}
+
 /** Wrap a raw user input into a PiMessage with text + optional image blocks. */
 function buildUserMessage(text: string, attachments?: AgentAttachment[], savedFiles?: SavedFile[]): PiMessage {
   const content: PiMessage['content'] = [];
@@ -498,10 +519,28 @@ function buildUserMessage(text: string, attachments?: AgentAttachment[], savedFi
     for (const att of attachments) {
       if (att.type === 'image') {
         content.push({ type: 'image', mediaType: att.mediaType, data: att.data });
+      } else if (isTextLikeMediaType(att.mediaType)) {
+        // Text-like documents are inlined (codex-parity posture, audit D5-7):
+        // claude sends native document blocks; pi inlines the decoded text,
+        // capped so a huge file can't blow the context.
+        let docText = '';
+        try { docText = Buffer.from(att.data, 'base64').toString('utf-8'); } catch {}
+        const capped = docText.length > DOC_INLINE_CAP_CHARS
+          ? `${docText.slice(0, DOC_INLINE_CAP_CHARS)}\n…[truncated at ${DOC_INLINE_CAP_CHARS} characters — the full file is in the saved-files note below]`
+          : docText;
+        content.push({
+          type: 'text',
+          text: capped
+            ? `[Attached document: ${att.name} (${att.mediaType})]\n${capped}\n[End of ${att.name}]`
+            : `[Attached document: ${att.name} (${att.mediaType}) — could not decode]`,
+        });
       } else {
-        // Documents aren't directly supported across all sub-providers yet.
-        // Surface their existence in the text body instead.
-        content.push({ type: 'text', text: `[Attached document: ${att.name} (${att.mediaType})]` });
+        // Binary documents (PDF etc.) can't be inlined across all
+        // sub-providers — point the model at the saved copy instead.
+        content.push({
+          type: 'text',
+          text: `[Attached document: ${att.name} (${att.mediaType}). It is saved to disk — see the saved-files note below and use your tools to inspect it if needed.]`,
+        });
       }
     }
   }
@@ -582,7 +621,7 @@ export async function startConversation(
   const session = createPiSession({
     getAuth,
     systemPrompt,
-    tools: toolDefsForProvider(),
+    tools: toolDefsForProvider({ withTask: true }),
     cwd: WORKSPACE_DIR,
     abortController,
     taskHost: createTaskHost(conv, getAuth),
@@ -647,8 +686,17 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
       conv.onMessage('bot:tool', { conversationId: conv.id, name: toolName, input: evt.input, ...syn });
       break;
     }
+    case 'thinking':
+      // Reasoning-model liveness pulse (house standard, codex M1 analog) —
+      // the UI dedups repeated name+running entries, channels get a chunk
+      // flush opportunity. Reasoning TEXT is never forwarded.
+      conv.onMessage('bot:tool', { conversationId: conv.id, name: 'thinking', status: 'running', ...syn });
+      break;
     case 'tool_result':
-      // Not surfaced yet (Phase D: translate to a bot:tool progress pulse).
+      // Progress pulse between tool rounds (audit D1-7): claude punctuates
+      // long tasks with tool_progress events; this is pi's equivalent —
+      // commits dashboard bubbles and flushes channel chunks mid-task.
+      conv.onMessage('bot:tool', { conversationId: conv.id, name: evt.name, status: 'running', ...syn });
       break;
     case 'turn_complete': {
       conv.busy = false;
@@ -795,9 +843,20 @@ export function anyOneShotActive(): boolean {
 }
 
 /**
- * One-shot text query — used by customer WhatsApp + scheduler. Uses the
- * provider stream directly (no async queue), drains it, emits the same
- * bloby events the live path does.
+ * One-shot agentic query — used by customer WhatsApp + scheduler (pulse/cron).
+ *
+ * Phase C (audit D5-1/D3-1): runs the SAME tool loop as the live path — a
+ * single-message `createPiSession` — so pulse/cron runs can actually edit
+ * files, run Bash, and read skills, and the tool-advertising system prompt is
+ * finally true (a tool-less request under that prompt made Gemini emit
+ * MALFORMED_FUNCTION_CALL — PI-HARNESS.md gotcha #3). No task host: background
+ * sub-agents stay a live-conversation feature (claude parity), so the Task def
+ * is excluded from the tool list and a hallucinated call fails gracefully.
+ *
+ * Guarantees preserved: finally-emitted bot:done, 5-min non-resetting
+ * watchdog, activeQueries registration AFTER the awaited prompt build
+ * (leak-ordering, claude.ts), supportPrompt bypasses the owner prompt +
+ * skills index entirely.
  */
 export async function startBlobyAgentQuery(
   conversationId: string,
@@ -809,7 +868,7 @@ export async function startBlobyAgentQuery(
   names?: { botName: string; humanName: string },
   recentMessages?: RecentMessage[],
   supportPrompt?: string,
-  _maxTurns?: number,
+  maxTurns?: number,
 ): Promise<void> {
   const resolved = resolveAuth();
   if (!resolved.ok) {
@@ -820,7 +879,6 @@ export async function startBlobyAgentQuery(
     onMessage('bot:done', { conversationId, usedFileTools: false });
     return;
   }
-  const auth = resolved.auth;
 
   // Build the prompt BEFORE registering in activeQueries / arming the watchdog
   // (claude.ts ordering): if anything in here ever rejected after registration,
@@ -830,15 +888,21 @@ export async function startBlobyAgentQuery(
   if (supportPrompt) {
     systemPrompt = supportPrompt;
   } else {
-    systemPrompt = await buildSystemPrompt(names, recentMessages);
+    // History rides ONLY as structured messages (initialMessages below).
+    // Passing it here too duplicated every prior turn into the system prompt
+    // (audit D3-6).
+    systemPrompt = await buildSystemPrompt(names, undefined);
+    // The base prompt routes heavy coding to the Agent tool, which only LIVE
+    // conversations have (one-shots have no task host) — keep the model
+    // honest so it doesn't chase a tool that isn't declared (review PI-C-4).
+    systemPrompt +=
+      '\n\n---\n# One-shot run\nThis is a scheduled/one-shot run: the Agent tool is NOT available here. ' +
+      'Do any heavy work yourself, directly with Read, Write, Edit, and Bash.';
   }
 
-  const messages: PiMessage[] = recentToPiMessages(recentMessages);
-  messages.push(buildUserMessage(prompt, attachments, savedFiles));
-
   const abortController = new AbortController();
   activeQueries.set(conversationId, abortController);
-  // Hard watchdog — a hung provider stream would otherwise pin this query forever (finally never
+  // Hard watchdog — a hung turn would otherwise pin this query forever (finally never
   // runs, bot:done never fires). Abort after 5 min; cleared in the finally on normal completion.
   const watchdog = setTimeout(() => {
     log.warn(`[pi/bloby-agent] one-shot timed out (5m) — aborting conv=${conversationId}`);
@@ -847,76 +911,107 @@ export async function startBlobyAgentQuery(
 
   onMessage('bot:typing', { conversationId });
 
-  let accumulated = '';
+  let usedFileTools = false;
+  // Track tool names LIVE (not only via turn_complete): an aborted run never
+  // emits turn_complete, and files written in earlier rounds must still flag
+  // usedFileTools on bot:done or the backend serves stale code
+  // (review PI-C-1; mirrors claude.ts:723-760 and runAgentQuery below).
   const usedTools = new Set<string>();
-  // Errors are stashed, not emitted inline — at the end, partial text wins
-  // over the error bubble (audit D3-5/D6-2, claude.ts:730-737 precedence).
-  let errorMsg: string | null = null;
+  let sawResponse = false;
+  let capHit = false;
   const batcher = createTokenBatcher((text) => onMessage('bot:token', { conversationId, token: text }));
 
+  // Re-resolve auth per round, same as the live path — a key/model fix in the
+  // wizard applies to the next round of an in-flight pulse run too.
+  let currentAuth: PiSessionAuth = resolved.auth;
+  const getAuth = (): PiSessionAuth => {
+    const fresh = resolveAuth();
+    if (fresh.ok) currentAuth = fresh.auth;
+    return currentAuth;
+  };
+
   try {
-    const stream = streamProvider(auth.flavor, {
-      modelId: auth.modelId,
-      baseUrl: auth.baseUrl,
-      apiKey: auth.apiKey,
+    const session = createPiSession({
+      getAuth,
       systemPrompt,
-      messages,
-      maxOutputTokens: auth.maxOutputTokens,
-      maxTokensField: auth.maxTokensField,
-      includeStreamUsage: auth.includeStreamUsage,
-      signal: abortController.signal,
+      initialMessages: recentToPiMessages(recentMessages),
+      tools: toolDefsForProvider(), // no Task — one-shots have no task host
+      cwd: WORKSPACE_DIR,
+      abortController,
+      maxToolRounds: maxTurns ?? 50, // claude one-shot default (claude.ts:677)
+      onEvent: (evt: PiSessionEvent) => {
+        switch (evt.type) {
+          case 'text_delta':
+            batcher.add(evt.delta);
+            break;
+          case 'text_end':
+            // Session precedence (D6-2): emitted even on errored turns when
+            // partial text streamed — the partial reaches the customer/pulse.
+            batcher.flush();
+            sawResponse = true;
+            onMessage('bot:response', { conversationId, content: evt.text });
+            break;
+          case 'tool_use': {
+            batcher.flush();
+            usedTools.add(evt.name);
+            const toolName = evt.name === 'Agent' || evt.name === 'agent' ? 'Task' : evt.name;
+            onMessage('bot:tool', { conversationId, name: toolName, input: evt.input });
+            break;
+          }
+          case 'thinking':
+            batcher.flush();
+            onMessage('bot:tool', { conversationId, name: 'thinking', status: 'running' });
+            break;
+          case 'tool_result':
+            batcher.flush();
+            onMessage('bot:tool', { conversationId, name: evt.name, status: 'running' });
+            break;
+          case 'error':
+            // Fires only when the turn produced no text, or fatally (D6-2).
+            batcher.flush();
+            sawResponse = true; // the caller got a terminal signal for this turn
+            onMessage('bot:error', { conversationId, error: evt.error });
+            break;
+          case 'turn_complete':
+            usedFileTools = usedFileTools || evt.usedFileTools;
+            if (evt.roundCapHit) capHit = true;
+            break;
+        }
+      },
     });
 
-    for await (const evt of stream) {
-      if (abortController.signal.aborted) break;
-      switch (evt.type) {
-        case 'text_delta':
-          accumulated += evt.delta;
-          batcher.add(evt.delta);
-          break;
-        case 'text_end':
-          batcher.flush();
-          accumulated = evt.text;
-          break;
-        case 'tool_use':
-          batcher.flush();
-          usedTools.add(evt.name);
-          onMessage('bot:tool', { conversationId, name: evt.name, input: evt.input });
-          break;
-        case 'error':
-          batcher.flush();
-          errorMsg = evt.error;
-          break;
-      }
-    }
-    // Abort guard (audit D3-8): a watchdog-aborted run must not surface a
-    // truncated reply — a stopped pulse could otherwise still fire <Message>
-    // pushes with half-finished content.
-    if (!abortController.signal.aborted) {
+    const queue = createAsyncQueue<PiMessage>();
+    queue.push(buildUserMessage(prompt, attachments, savedFiles));
+    queue.end();
+    await session.run(queue);
+
+    // Round-cap exhaustion with no terminal signal: the model was still
+    // mid-task when the budget ran out and no text streamed — without this the
+    // customer/pulse gets dead silence (review PI-C-2; claude surfaces an
+    // error_max_turns result on the same path).
+    if (!abortController.signal.aborted && capHit && !sawResponse) {
       batcher.flush();
-      if (accumulated) {
-        onMessage('bot:response', { conversationId, content: accumulated });
-      } else if (errorMsg) {
-        onMessage('bot:error', { conversationId, error: errorMsg });
-      }
+      onMessage('bot:error', {
+        conversationId,
+        error: `The run hit its ${maxTurns ?? 50}-round tool limit before producing a reply. Try a narrower request.`,
+      });
     }
   } catch (err: any) {
+    // session.run contains per-turn error handling; a throw here is unexpected.
     if (!abortController.signal.aborted) {
       log.warn(`[pi/bloby-agent] one-shot error: ${err?.message || err}`);
       batcher.flush();
-      if (accumulated) {
-        onMessage('bot:response', { conversationId, content: accumulated });
-      } else {
-        onMessage('bot:error', { conversationId, error: err?.message || String(err) });
-      }
+      onMessage('bot:error', { conversationId, error: err?.message || String(err) });
     }
   } finally {
+    // Aborted-run stragglers must not surface (audit D3-8) — discard, never flush.
     batcher.discard();
     clearTimeout(watchdog);
     activeQueries.delete(conversationId);
-    const FILE_TOOL_NAMES = ['Write', 'Edit', 'write', 'edit'];
-    const usedFileTools = FILE_TOOL_NAMES.some((t) => usedTools.has(t));
-    onMessage('bot:done', { conversationId, usedFileTools });
+    // Live tool tracking covers aborted runs whose turn_complete never fired —
+    // files already written must still trigger the backend restart (PI-C-1).
+    const fileToolsUsed = usedFileTools || ['Write', 'Edit', 'write', 'edit'].some((t) => usedTools.has(t));
+    onMessage('bot:done', { conversationId, usedFileTools: fileToolsUsed });
   }
 }
 
@@ -930,45 +1025,126 @@ export function stopBlobyAgentQuery(conversationId: string): void {
 
 // ── Workspace agent endpoint (POST /api/agent/query) ──────────────────────
 
+/** Minimal coding-agent prompt for /api/agent/query when the caller supplies
+ *  none — claude falls back to its native `claude_code` preset; pi's
+ *  equivalent advertises ONLY the tools that actually exist, and never the
+ *  Bloby owner persona (agent-API callers are workspace apps, not the bot). */
+const PI_CODING_AGENT_PROMPT =
+  'You are a coding agent operating non-interactively inside a project workspace. ' +
+  'Complete the request fully using your tools, then reply with a concise summary of what you did. ' +
+  'Tools: Read (file contents), Write (create/overwrite a file), Edit (exact string replacement), ' +
+  'Bash (shell commands; cwd is the workspace root). Paths are relative to the workspace root. ' +
+  'Do the work — never claim to have done something without actually using the tools.';
+
+/** In-memory session store for the agent API (audit D2-7/D3-3). Process-
+ *  lifetime only — AGENT-API.md documents that sessions die on supervisor
+ *  restart, and claude's resume has the same practical bound. */
+interface StoredAgentSession { messages: PiMessage[]; lastUsed: number }
+const agentSessions = new Map<string, StoredAgentSession>();
+const AGENT_SESSION_CAP = 50;
+const AGENT_SESSION_TTL_MS = 24 * 60 * 60_000;
+const AGENT_SESSION_MAX_MESSAGES = 40;
+
+function sweepAgentSessions(): void {
+  const now = Date.now();
+  for (const [id, s] of agentSessions) {
+    if (now - s.lastUsed > AGENT_SESSION_TTL_MS) agentSessions.delete(id);
+  }
+  if (agentSessions.size > AGENT_SESSION_CAP) {
+    const byAge = [...agentSessions.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+    for (const [id] of byAge.slice(0, agentSessions.size - AGENT_SESSION_CAP)) {
+      agentSessions.delete(id);
+    }
+  }
+}
+
+/** Trim resumed history at a clean turn boundary: the window must start on a
+ *  REAL user message (not a tool_result carrier) — an orphaned tool_result or
+ *  a leading assistant message makes Anthropic/Gemini reject the request. */
+function trimAgentHistory(messages: PiMessage[]): PiMessage[] {
+  if (messages.length <= AGENT_SESSION_MAX_MESSAGES) return messages;
+  const isRealUser = (m: PiMessage) =>
+    m.role === 'user' && !m.content.some((b) => b.type === 'tool_result');
+  const windowStart = messages.length - AGENT_SESSION_MAX_MESSAGES;
+  for (let i = windowStart; i < messages.length; i++) {
+    if (isRealUser(messages[i])) return messages.slice(i);
+  }
+  // No clean boundary inside the window — a single tool-heavy turn (each round
+  // adds an assistant + a tool_result message) exceeds the cap by itself.
+  // Fall back BACKWARD to that turn's own user message: the window overshoots
+  // the cap (bounded by the turn's size) instead of silently wiping the whole
+  // history to [] (review PI-C-3 — total session amnesia).
+  for (let j = windowStart - 1; j >= 0; j--) {
+    if (isRealUser(messages[j])) return messages.slice(j);
+  }
+  return messages;
+}
+
+/** Per-sessionId serialization (review PI-C-SESS-2): two concurrent resumes of
+ *  the same session would both read the same stored history and last-write-win
+ *  the store, silently erasing one call's turn. Chaining the second behind the
+ *  first keeps the linear-history contract; each run is bounded by its own
+ *  timeout (≤300s), so the wait is too. */
+const agentSessionLocks = new Map<string, Promise<void>>();
+
 export async function runAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResult> {
+  if (!req.sessionId) return runAgentQueryInner(req);
+  const id = req.sessionId;
+  const prev = agentSessionLocks.get(id) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((r) => { release = r; });
+  const chained = prev.then(() => gate);
+  agentSessionLocks.set(id, chained);
+  await prev;
+  try {
+    return await runAgentQueryInner(req);
+  } finally {
+    release();
+    if (agentSessionLocks.get(id) === chained) agentSessionLocks.delete(id);
+  }
+}
+
+async function runAgentQueryInner(req: AgentQueryRequest): Promise<AgentQueryResult> {
   const resolved = resolveAuth();
   if (!resolved.ok) return { ok: false, error: resolved.error };
-  const auth = resolved.auth;
 
   const timeout = Math.min(Math.max(req.timeout || 120_000, 5_000), 300_000);
+  // Same clamp as claude.ts:781 — maxTurns maps onto the session's tool-round budget.
+  const maxTurns = Math.min(Math.max(req.maxTurns || 25, 1), 50);
   const abortController = new AbortController();
   const timeoutHandle = setTimeout(() => abortController.abort(), timeout);
 
-  const systemPrompt = req.systemPrompt ?? '';
-  const messages: PiMessage[] = [{
-    role: 'user',
-    content: [{ type: 'text', text: req.message }],
-  }];
+  const systemPrompt = req.systemPrompt?.trim() ? req.systemPrompt : PI_CODING_AGENT_PROMPT;
+
+  sweepAgentSessions();
+  const resumed = req.sessionId ? agentSessions.get(req.sessionId) : undefined;
+  const sessionId = resumed ? req.sessionId! : crypto.randomUUID();
+  if (resumed) resumed.lastUsed = Date.now();
 
   let fullText = '';
   const usedTools = new Set<string>();
   let errored = false;
   let errorMsg = '';
+  let usedFileTools = false;
+  let capHit = false;
 
-  try {
-    const stream = streamProvider(auth.flavor, {
-      modelId: auth.modelId,
-      baseUrl: auth.baseUrl,
-      apiKey: auth.apiKey,
-      systemPrompt,
-      messages,
-      maxOutputTokens: auth.maxOutputTokens,
-      maxTokensField: auth.maxTokensField,
-      includeStreamUsage: auth.includeStreamUsage,
-      signal: abortController.signal,
-    });
+  let currentAuth: PiSessionAuth = resolved.auth;
+  const getAuth = (): PiSessionAuth => {
+    const fresh = resolveAuth();
+    if (fresh.ok) currentAuth = fresh.auth;
+    return currentAuth;
+  };
 
-    for await (const evt of stream) {
-      if (abortController.signal.aborted) break;
+  const session = createPiSession({
+    getAuth,
+    systemPrompt,
+    initialMessages: resumed ? trimAgentHistory(resumed.messages) : undefined,
+    tools: toolDefsForProvider(), // no Task — no task host on this path
+    cwd: WORKSPACE_DIR,
+    abortController,
+    maxToolRounds: maxTurns,
+    onEvent: (evt: PiSessionEvent) => {
       switch (evt.type) {
-        case 'text_delta':
-          fullText += evt.delta;
-          break;
         case 'text_end':
           fullText = evt.text;
           break;
@@ -979,22 +1155,66 @@ export async function runAgentQuery(req: AgentQueryRequest): Promise<AgentQueryR
           errored = true;
           errorMsg = evt.error;
           break;
+        case 'turn_complete':
+          usedFileTools = usedFileTools || evt.usedFileTools;
+          // The error EVENT is suppressed when partial text streamed (D6-2) —
+          // read the outcome fields so a failed turn isn't reported clean.
+          if (evt.errored) {
+            errored = true;
+            errorMsg = errorMsg || evt.errorMsg || '';
+          }
+          if (evt.roundCapHit) capHit = true;
+          break;
       }
-    }
+    },
+  });
+
+  try {
+    log.info(`[pi/agent-api] Query: msg="${req.message.slice(0, 80)}..." maxTurns=${maxTurns} timeout=${timeout}ms resume=${resumed ? sessionId : 'none'}`);
+    const queue = createAsyncQueue<PiMessage>();
+    queue.push({ role: 'user', content: [{ type: 'text', text: req.message }] });
+    queue.end();
+    await session.run(queue);
   } catch (err: any) {
-    if (abortController.signal.aborted) {
-      return { ok: false, error: 'Query timed out.' };
-    }
-    return { ok: false, error: err?.message || String(err) };
+    if (abortController.signal.aborted) return { ok: false, error: 'Query timed out.', sessionId };
+    return { ok: false, error: err?.message || String(err), sessionId };
   } finally {
     clearTimeout(timeoutHandle);
   }
 
+  if (abortController.signal.aborted) {
+    // Timed-out histories can hold a dangling tool_use (aborted mid-round) —
+    // don't persist them for resume.
+    return { ok: false, error: 'Query timed out.', sessionId };
+  }
+
+  // Round-cap exhaustion with no answer: the model was still mid-task when the
+  // budget ran out (claude maps the same state to an error_max_turns result —
+  // review PI-C-2; an ok:true empty response reads as a silent blank bubble in
+  // the documented maxTurns:1 aichat pattern). Don't persist the half-done
+  // turn either — a fresh retry beats resuming into unanswered tool results.
+  if (capHit && !fullText) {
+    return {
+      ok: false,
+      error: `Agent hit its turn limit (maxTurns=${maxTurns}) before producing a response — raise maxTurns or narrow the request.`,
+      sessionId,
+      toolsUsed: Array.from(usedTools),
+    };
+  }
+
+  // Trim at store time too — otherwise a long-lived session's stored history
+  // grows unboundedly across resumes (the resume-side trim only caps what the
+  // provider sees, not what we keep in memory).
+  agentSessions.set(sessionId, { messages: trimAgentHistory(session.getMessages()), lastUsed: Date.now() });
+
   // Partial-text precedence (claude parity, audit D6-2): if the model streamed
   // anything before failing, return it as a successful (truncated) response —
   // claude's runAgentQuery only reports the error when nothing streamed.
-  if (errored && !fullText) return { ok: false, error: errorMsg || 'Agent query failed' };
+  if (errored && !fullText) {
+    return { ok: false, error: errorMsg || 'Agent query failed', sessionId, toolsUsed: Array.from(usedTools) };
+  }
 
-  const usedFileTools = ['Write', 'Edit', 'write', 'edit'].some((t) => usedTools.has(t));
-  return { ok: true, response: fullText, toolsUsed: Array.from(usedTools), usedFileTools };
+  const fileToolsUsed = usedFileTools || ['Write', 'Edit', 'write', 'edit'].some((t) => usedTools.has(t));
+  log.info(`[pi/agent-api] Done: ${fullText.length} chars, tools=[${Array.from(usedTools).join(',')}], session=${sessionId}`);
+  return { ok: true, response: fullText, sessionId, toolsUsed: Array.from(usedTools), usedFileTools: fileToolsUsed };
 }

package/supervisor/harnesses/pi/providers/humanize-error.ts

@@ -113,8 +113,8 @@ export function classifyPiError(
 export function classifyPiNetworkError(providerLabel: string, err: any): ClassifiedPiError {
   const raw = err?.message || String(err);
   // undici's body/headers timeouts surface as the famously cryptic 'terminated'
-  // and 'Headers Timeout Error' — translate them.
-  const stalled = /terminated|timeout/i.test(raw);
+  // and 'Headers Timeout Error'; our own SSE idle guard says 'stalled'.
+  const stalled = /terminated|timeout|stalled/i.test(raw);
   return {
     kind: 'transient',
     retryable: true,

package/supervisor/harnesses/pi/providers/retry.ts

@@ -51,6 +51,37 @@ export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+/** Per-chunk SSE idle guard (audit D6-7). Without it, a stalled-but-open
+ *  stream waits ~300s for Node's undici body timeout and then surfaces a
+ *  cryptic 'terminated'. 120s is generous: Anthropic pings every ~20s and
+ *  Gemini/OpenAI chunk every few seconds while healthy. */
+export const SSE_IDLE_TIMEOUT_MS = 120_000;
+
+export async function readWithIdleTimeout<T>(
+  reader: { read(): Promise<T>; cancel?: (reason?: any) => Promise<void> | void },
+  providerLabel: string,
+): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeoutP = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`${providerLabel} stream stalled — no data received for ${SSE_IDLE_TIMEOUT_MS / 1000}s.`)),
+      SSE_IDLE_TIMEOUT_MS,
+    );
+  });
+  const readP = reader.read();
+  // Mark the losing read promise handled so a post-timeout rejection (after
+  // reader.cancel) never surfaces as an unhandledRejection.
+  readP.catch?.(() => {});
+  try {
+    return await Promise.race([readP, timeoutP]);
+  } catch (err) {
+    try { void reader.cancel?.(); } catch {}
+    throw err;
+  } finally {
+    clearTimeout(timer!);
+  }
+}
+
 export async function fetchWithRetry(
   url: string,
   init: RequestInit & { signal?: AbortSignal },