@bevel-software/ael 0.0.0-stage → 0.1.0

package/src/harness/pi-in-process.ts

@@ -0,0 +1,444 @@
+import { AsyncResource } from 'node:async_hooks';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { InMemoryCredentialStore } from '@earendil-works/pi-ai';
+import {
+  createAgentSession,
+  createMcpExtension,
+  DefaultResourceLoader,
+  getPackageDir,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+  type AgentSession,
+  type AgentSessionEvent,
+} from '@earendil-works/pi-coding-agent';
+import { MCP_SERVER_NAME, type Harness, type RunEvent, type SessionResult, type SessionStartParams, type SessionState, type Verdict } from '../run/contract.js';
+import { VERDICT_NUDGE, parseOutputs, parseVerdict } from '../run/verdict.js';
+import { stallGuardedFetch } from './stall-guard.js';
+import { pruneSessionEntries } from './session-state.js';
+
+/**
+ * pi as a library, inside the platform process: the harness of
+ * `environment: none`. No shell, no filesystem, no files of its own; the
+ * model through the platform's gateway with the run key; tools through the
+ * platform's MCP endpoint as the actor; the session state exported after
+ * every turn and restored from the thread on resume.
+ *
+ * Verified by the phase 0 spike (ticket `bp-workflows-phase-0-pi-in-process`).
+ * Two facts from it shape this file: `noTools: "all"` drops custom tools too,
+ * so the built-in tools are registered under `"builtin"` and never activated;
+ * and the in-memory MCP credential store is not exported by pi's index, so it
+ * is reached by file URL (an upstream request is open).
+ */
+
+export interface PiInProcessOptions {
+  /**
+   * Activate pi's built-in tools (shell, files) too. Off in the platform
+   * process, where a run has no shell by design; on inside a run container,
+   * where the workspace is the session's to use.
+   */
+  builtinTools?: boolean;
+  /** How long the MCP extension may take to connect before the first prompt. */
+  mcpStartupWaitMs?: number;
+  /** Default step budget when the caller gives none. */
+  defaultTimeoutMs?: number;
+  /** The nudge is one short turn; it never gets a step's full budget. */
+  verdictNudgeTimeoutMs?: number;
+}
+
+const STATE_VERSION = 1;
+/** pi spells a server's tools `mcp__<name>__<tool>` with the name's other characters as `_`: `knowledge-base` becomes `knowledge_base`. */
+const PI_MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME.replace(/[^A-Za-z0-9_]/g, '_')}__`;
+const BUILTIN_TOOLS = new Set(['read', 'bash', 'powershell', 'edit', 'write', 'grep', 'find', 'ls']);
+const AUTH_REFUSED = /\b40[13]\b|unauthori[sz]ed|invalid[_ ]api[_ ]key|incorrect api key|api key (is )?(missing|not set|required)|no api key/i;
+const RATE_LIMITED = /\b429\b|rate.?limit|too many requests|quota|usage limit|session limit/i;
+
+// pi's package index exports neither; the extension's own credential store
+// would otherwise write `<agentDir>/mcp-auth.json`. Loaded once, lazily.
+type McpCredentialStoreCtor = new (backend: unknown) => unknown;
+type AuthBackendCtor = new () => unknown;
+let piInternals: Promise<{ McpOAuthCredentialStore: McpCredentialStoreCtor; InMemoryAuthStorageBackend: AuthBackendCtor }> | undefined;
+function loadPiInternals() {
+  piInternals ??= (async () => {
+    const dist = path.join(getPackageDir(), 'dist');
+    const oauth = (await import(pathToFileURL(path.join(dist, 'extensions/mcp/oauth.js')).href)) as { McpOAuthCredentialStore: McpCredentialStoreCtor };
+    const auth = (await import(pathToFileURL(path.join(dist, 'core/auth-storage.js')).href)) as { InMemoryAuthStorageBackend: AuthBackendCtor };
+    return { McpOAuthCredentialStore: oauth.McpOAuthCredentialStore, InMemoryAuthStorageBackend: auth.InMemoryAuthStorageBackend };
+  })();
+  return piInternals;
+}
+
+const now = () => new Date().toISOString();
+
+/** What a session is told when its last message had nothing in it: the model answered with reasoning alone, and the loop took that for its end. */
+const EMPTY_NUDGE =
+  'Your last message was empty: it said nothing and called no tool. Go on with the work where you left off, and end with what you did, or that there was nothing to do, in one line.';
+
+/** Whether the session's last message is an assistant message with nothing in it: no text, no tool call, ended by the model itself. */
+function endedEmpty(session: AgentSession): boolean {
+  const messages = session.agent.state.messages as ReadonlyArray<{ role: string; stopReason?: string; content?: ReadonlyArray<{ type: string; text?: string }> }>;
+  const last = messages[messages.length - 1];
+  if (!last || last.role !== 'assistant' || last.stopReason === 'error' || last.stopReason === 'aborted') return false;
+  return !(last.content ?? []).some((c) => c.type === 'toolCall' || (c.type === 'text' && c.text?.trim()));
+}
+
+/** Why the session's last assistant message ended, when that was not the model's own end: the error pi gave up on, or an abort. */
+function stoppedBy(session: AgentSession): string | undefined {
+  const messages = session.agent.state.messages as ReadonlyArray<{ role: string; stopReason?: string; errorMessage?: string }>;
+  const last = [...messages].reverse().find((m) => m.role === 'assistant');
+  if (last?.stopReason === 'error') return last.errorMessage?.trim() || 'the model answered with an error';
+  if (last?.stopReason === 'aborted') return 'the session was aborted before it answered';
+  return undefined;
+}
+
+/** The reasoning summary an assistant message carries (pi's thinking parts), in one text; empty for any other message, or one with none. */
+function reasoningOf(message: unknown): string {
+  const m = message as { role?: string; content?: unknown } | null;
+  if (m?.role !== 'assistant' || !Array.isArray(m.content)) return '';
+  return (m.content as ReadonlyArray<{ type?: string; thinking?: unknown }>)
+    .flatMap((c) => (c.type === 'thinking' && typeof c.thinking === 'string' && c.thinking.trim() ? [c.thinking.trim()] : []))
+    .join('\n\n');
+}
+
+/** `provider/id[:thinking]` as a configuration writes it. */
+function splitModel(model: string): { provider: string; id: string; thinking?: string } {
+  const [spec, thinking] = model.split(':');
+  const slash = spec.indexOf('/');
+  if (slash === -1) return { provider: 'gateway', id: spec, ...(thinking ? { thinking } : {}) };
+  return { provider: spec.slice(0, slash), id: spec.slice(slash + 1), ...(thinking ? { thinking } : {}) };
+}
+
+/** `"$NAME"` values in a `providers:` block are read from the session's environment. */
+function resolveEnvRefs(value: unknown, env: Record<string, string>): unknown {
+  if (typeof value === 'string') {
+    const m = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value.trim());
+    return m ? (env[m[1]] ?? '') : value;
+  }
+  if (Array.isArray(value)) return value.map((v) => resolveEnvRefs(v, env));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, resolveEnvRefs(v, env)]));
+  }
+  return value;
+}
+
+export class PiInProcessHarness implements Harness {
+  readonly name = 'pi';
+
+  constructor(private readonly options: PiInProcessOptions = {}) {}
+
+  /**
+   * The sessions running in this process, by the caller's key: where a message that arrives mid-run is handed. `inRun`
+   * runs a function in the run's own async context: the caller's event handler heartbeats the workflow engine, which
+   * answers only inside the activity that started the run ("Activity context not initialized" from a chat request).
+   */
+  private readonly live = new Map<string, { session: AgentSession; emit: (event: RunEvent) => void; inRun: <T>(work: () => T) => T }>();
+
+  /**
+   * Hand a message to a session still working under `runKey`: pi queues it as a follow-up and answers it in the same
+   * run, after the turn in progress, so the person gets one reply for both. On 8 Nov 2026 "no, i want rich widgets"
+   * and "in this chat" came seconds apart and were answered twice, the second answer a repeat of the first.
+   */
+  async followUp(runKey: string, text: string): Promise<'queued' | 'absent'> {
+    const entry = this.live.get(runKey);
+    if (!entry || !entry.session.isStreaming) {
+      console.log(`[ael] follow-up for ${runKey}: ${!entry ? `no live session under that key (live: ${[...this.live.keys()].join(', ') || 'none'})` : 'the session is not working any more'}`);
+      return 'absent';
+    }
+    await entry.inRun(async () => {
+      entry.emit({ type: 'user', at: now(), text });
+      await entry.session.prompt(text, { streamingBehavior: 'followUp' } as never);
+    });
+    return 'queued';
+  }
+
+  /**
+   * One run of the configuration: build or restore the session, send the input, and store the
+   * state after every turn. An empty last reply, or a missing verdict the step needs, gets one
+   * short turn more in the same session. While it works, `followUp` reaches it under its run key.
+   */
+  async run(p: SessionStartParams): Promise<SessionResult> {
+    const events: RunEvent[] = [];
+    const emit = (event: RunEvent) => {
+      events.push(event);
+      p.onEvent?.(event);
+    };
+    const env = p.env ?? {};
+    const { session, sessionManager, modelName, thinking } = await this.buildSession(p, env);
+    if (p.runKey) this.live.set(p.runKey, { session, emit, inRun: AsyncResource.bind(<T>(work: () => T): T => work()) as <T>(work: () => T) => T });
+    let started = false;
+    let finalText = '';
+    let lastError: string | undefined;
+
+    const unsubscribe = session.subscribe((ev: AgentSessionEvent) => {
+      switch (ev.type) {
+        case 'tool_execution_start':
+          started = true;
+          emit({ type: 'tool_call', at: now(), id: ev.toolCallId, name: ev.toolName, input: ev.args });
+          break;
+        case 'tool_execution_end':
+          emit({ type: 'tool_result', at: now(), id: ev.toolCallId, name: ev.toolName, output: ev.result, isError: ev.isError });
+          break;
+        case 'message_update':
+          started = true;
+          break;
+        case 'message_end': {
+          // The summary of what the model weighed for this message, ahead of the tools it then calls.
+          const text = reasoningOf(ev.message);
+          if (text) emit({ type: 'reasoning', at: now(), text });
+          break;
+        }
+        case 'agent_end': {
+          const error = (ev as { error?: unknown }).error;
+          if (error) lastError = String(error instanceof Error ? error.message : error);
+          break;
+        }
+        default:
+          break;
+      }
+    });
+
+    const timeoutMs = p.timeoutMs ?? this.options.defaultTimeoutMs ?? 30 * 60_000;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      void session.abort();
+    }, timeoutMs);
+    // A cancelled run: the session is aborted where it is, as on timeout.
+    if (p.signal?.aborted) void session.abort();
+    else p.signal?.addEventListener('abort', () => void session.abort(), { once: true });
+
+    try {
+      const tools = await this.connectMcp(session, p.agent.harnessTools);
+      // What the session runs with, in the platform's log: the one place that says which model, which thinking level, how big a prompt, how many tools.
+      console.log(`[ael] session on ${modelName}, thinking ${thinking}, ${tools.length} tools, system prompt ${p.systemPrompt.length} chars, input ${(p.input.text ?? '').length} chars`);
+      emit({ type: 'session_started', at: now(), harness: this.name, model: modelName, sessionId: sessionManager.getSessionId(), resumed: !!p.state, tools });
+      const storeState = () => p.onState?.(exportState(sessionManager));
+      emit({ type: 'user', at: now(), text: p.input.text });
+      await this.turn(session, p.input.text, p.input.images, storeState);
+      // A last message with nothing in it (the model answered with reasoning
+      // alone, which some gateways return with empty content) is not the end
+      // of the work: one short turn asks for the rest, and the work before it is kept.
+      if (!timedOut && !lastError && endedEmpty(session)) {
+        emit({ type: 'user', at: now(), text: EMPTY_NUDGE });
+        await this.turn(session, EMPTY_NUDGE, undefined, storeState);
+      }
+      finalText = session.getLastAssistantText() ?? '';
+      if (finalText) emit({ type: 'assistant', at: now(), text: finalText });
+      // How the loop ended is on its last assistant message: a model error pi
+      // gave up on, or an abort, is not the model's own end, whatever text
+      // came before it, and the step must not pass on it.
+      const stopped = stoppedBy(session);
+      if (stopped && !timedOut && !lastError) lastError = stopped;
+
+      let verdict: Verdict | undefined = parseVerdict(finalText);
+      if (p.expectVerdict && !verdict && !timedOut && !lastError) {
+        // One short turn in the same session, asking for the sentence the
+        // interpreter routes on; the finished work is never thrown away.
+        emit({ type: 'user', at: now(), text: VERDICT_NUDGE });
+        clearTimeout(timer);
+        const nudgeTimer = setTimeout(() => void session.abort(), this.options.verdictNudgeTimeoutMs ?? 5 * 60_000);
+        try {
+          await this.turn(session, VERDICT_NUDGE, undefined, storeState);
+        } finally {
+          clearTimeout(nudgeTimer);
+        }
+        const asked = session.getLastAssistantText() ?? '';
+        if (asked) emit({ type: 'assistant', at: now(), text: asked });
+        verdict = parseVerdict(asked);
+        if (verdict) finalText = `${finalText}\n\n${asked}`;
+      }
+      const outputs = parseOutputs(finalText) ?? undefined;
+      if (verdict) emit({ type: 'verdict', at: now(), verdict });
+      if (outputs) emit({ type: 'outputs', at: now(), values: outputs });
+
+      const accountLimit = lastError ? classifyAccountLimit(lastError) : undefined;
+      if (lastError && !accountLimit) emit({ type: 'error', at: now(), message: lastError });
+      const ok = !timedOut && !lastError;
+      const state = exportState(sessionManager);
+      emit({ type: 'session_ended', at: now(), ok, finalText });
+      return {
+        ok,
+        ...(timedOut ? { timedOut: true } : {}),
+        finalText,
+        ...(verdict ? { verdict } : {}),
+        ...(outputs ? { outputs } : {}),
+        ...(accountLimit ? { accountLimit } : {}),
+        ...(!started && !finalText ? { sessionNotStarted: true } : {}),
+        state,
+        events,
+      };
+    } finally {
+      clearTimeout(timer);
+      unsubscribe();
+      if (p.runKey && this.live.get(p.runKey)?.session === session) this.live.delete(p.runKey);
+      // `dispose()` alone leaves the MCP servers connected: the extension closes them on
+      // `session_shutdown`. A local server is a child process whose open pipe would keep
+      // the step's process alive past its session, until the executor's timeout.
+      await session.extensionRunner.emit({ type: 'session_shutdown', reason: 'quit' }).catch(() => undefined);
+      session.dispose();
+    }
+  }
+
+  private async turn(session: AgentSession, text: string, images?: SessionStartParams['input']['images'], onState?: () => void): Promise<void> {
+    const imageParts = (images ?? []).map((i) => ({ type: 'image' as const, data: i.dataBase64, mimeType: i.mediaType }));
+    await session.prompt(text, imageParts.length > 0 ? ({ images: imageParts } as never) : undefined);
+    await session.waitForIdle();
+    // The state after the turn, whatever pi emitted on the way: a turn that
+    // ends is the unit the thread stores, so the next turn or a resumed step
+    // starts from here.
+    onState?.();
+  }
+
+  /**
+   * `harnessTools` is the configuration's allowlist of built-in tools: with
+   * one, a container session gets exactly those (a read-only configuration
+   * gets no `bash`); without one, every built-in. In process the built-ins
+   * are never on, whatever the list says.
+   */
+  private async connectMcp(session: AgentSession, harnessTools: readonly string[]): Promise<string[]> {
+    // Binding the extensions emits session_start, which connects the MCP
+    // servers in the background; their tools appear once connected. Poll
+    // briefly for them rather than sleeping the whole window.
+    await session.bindExtensions({});
+    const deadline = Date.now() + (this.options.mcpStartupWaitMs ?? 5000);
+    const builtinAllowed = (name: string) => this.options.builtinTools === true && (harnessTools.length === 0 || harnessTools.includes(name));
+    let active: string[] = [];
+    const activate = () => {
+      active = session.getAllTools().map((t) => t.name).filter((n) => (BUILTIN_TOOLS.has(n) ? builtinAllowed(n) : true));
+      session.setActiveToolsByName(active);
+      return active.some((n) => n.startsWith(PI_MCP_TOOL_PREFIX));
+    };
+    while (!activate() && Date.now() < deadline) await new Promise((r) => setTimeout(r, 100));
+    return active;
+  }
+
+  /**
+   * The pi session a run works in: the platform gateway always registered with the run key, the
+   * configuration's own providers beside it, tools from the platform's MCP endpoint, and the thread's
+   * earlier state restored when there is one. A model no provider offers throws here, before the run starts.
+   */
+  private async buildSession(p: SessionStartParams, env: Record<string, string>) {
+    const { McpOAuthCredentialStore, InMemoryAuthStorageBackend } = await loadPiInternals();
+    const modelRuntime = await ModelRuntime.create({
+      credentials: new InMemoryCredentialStore(),
+      modelsPath: null,
+      allowModelNetwork: false,
+      refreshOnCreate: false,
+    });
+    // The deployment's gateway is always registered: a configuration without
+    // a model runs on it, authenticated with the run key, so usage is metered
+    // to the actor like every other call.
+    modelRuntime.registerProvider('gateway', {
+      name: 'Platform gateway',
+      baseUrl: p.platform.gatewayUrl,
+      apiKey: p.actorKey.token,
+      api: 'openai-completions',
+      models: [gatewayModel(p.platform.gatewayModel, p.platform.gatewayContextWindow)],
+    });
+    // A gateway call that never answers ends after GATEWAY_STALL_MS and pi retries it, instead of the five-minute
+    // silence of 8 Nov 2026 (see stall-guard.ts). Pi takes the fetch per request, so it rides on every stream.
+    const guardedFetch = stallGuardedFetch(globalThis.fetch, { headersMs: GATEWAY_STALL_MS, bodyMs: GATEWAY_STALL_MS });
+    const streamSimple = modelRuntime.streamSimple.bind(modelRuntime);
+    modelRuntime.streamSimple = (model, context, options) =>
+      streamSimple(model, context, model.provider === 'gateway' ? { ...options, fetch: guardedFetch } : options);
+    for (const [providerId, config] of Object.entries(p.agent.providers ?? {})) {
+      modelRuntime.registerProvider(providerId, resolveEnvRefs(config, env) as never);
+    }
+    const spec = splitModel(p.agent.model ?? `gateway/${p.platform.gatewayModel}`);
+    const model = modelRuntime.getModel(spec.provider, spec.id);
+    if (!model) throw new Error(`configuration "${p.agent.id}" names model ${spec.provider}/${spec.id}, which no provider offers`);
+
+    const cwd = p.cwd ?? process.cwd();
+    const agentDir = path.join(cwd, '.pi-agent-dir-unused');
+    const settingsManager = SettingsManager.inMemory({ compaction: { enabled: true }, retry: { enabled: true, maxRetries: 2 } });
+    const resourceLoader = new DefaultResourceLoader({
+      cwd,
+      agentDir,
+      settingsManager,
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noContextFiles: true,
+      systemPrompt: p.systemPrompt,
+      extensionFactories: [
+        createMcpExtension({
+          loadConfig: () => ({
+            servers: [
+              {
+                name: MCP_SERVER_NAME,
+                source: 'platform',
+                // In a run container the local Hexis MCP server (local tools run there, git among them); in the platform process its endpoint.
+                config: p.platform.localMcp
+                  ? { type: 'stdio', command: p.platform.localMcp.command, args: p.platform.localMcp.args, env: p.platform.localMcp.env, exposure: 'direct' }
+                  : { url: p.platform.mcpUrl, headers: { Authorization: `Bearer ${p.actorKey.token}` }, exposure: 'direct' },
+              },
+            ],
+            errors: [],
+          }),
+          credentials: new McpOAuthCredentialStore(new InMemoryAuthStorageBackend()) as never,
+          startupWaitMs: this.options.mcpStartupWaitMs ?? 5000,
+        }),
+      ],
+    });
+    await resourceLoader.reload();
+
+    // A state from an earlier run, pruned as it is stored (session-state.ts): one copy of the tool list, no pictures.
+    const restored = p.state && p.state.harness === this.name && Array.isArray(p.state.data) ? (pruneSessionEntries(p.state.data) as never[]) : undefined;
+    const sessionManager = restored ? SessionManager.inMemory(cwd, undefined, restored) : SessionManager.inMemory(cwd);
+    // The deployment's thinking level is the gateway model's default only: a model on any other provider runs off unless the configuration names a level.
+    const thinking = spec.thinking ?? (spec.provider === 'gateway' ? p.platform.gatewayThinking : undefined) ?? 'off';
+
+    const { session } = await createAgentSession({
+      cwd,
+      agentDir,
+      model,
+      thinkingLevel: thinking as never,
+      modelRuntime,
+      resourceLoader,
+      settingsManager,
+      sessionManager,
+      // Built-in tools stay registered; in the platform process they are
+      // never activated (no shell, no filesystem by design), in a run
+      // container `builtinTools` turns them on.
+      noTools: 'builtin',
+      customTools: [],
+    });
+    return { session, sessionManager, modelName: `${spec.provider}/${spec.id}`, thinking };
+  }
+}
+
+/** No response headers, or no byte of a started reply, for this long: the call is given up and retried. */
+const GATEWAY_STALL_MS = 90_000;
+
+/**
+ * The gateway's model as pi takes one. The gateway names a handle, not a model, so reasoning is offered
+ * whatever the model behind it, and the window is the deployment's when it gives one, else 200k tokens.
+ */
+function gatewayModel(id: string, contextWindow?: number) {
+  return {
+    type: 'chat' as const,
+    id,
+    name: id,
+    // The gateway is a handle (`default`), so support cannot be read off the id: reasoning is offered, and a
+    // model that takes no `reasoning_effort` has the gateway drop it (litellm `drop_params`). Off before
+    // 2026-11-06, which ran every gateway session, gpt-5.1 included, without any reasoning at all.
+    reasoning: true,
+    input: ['text' as const, 'image' as const],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    // The model's real window, when the deployment says it (gpt-6-luna takes 922k, gpt-5.1 272k): pi cuts the output
+    // budget to what fits under it, and a window smaller than the model's sent max_output_tokens: 1 on 7 Nov 2026.
+    contextWindow: contextWindow && contextWindow > 0 ? contextWindow : 200_000,
+    maxTokens: 16_384,
+  };
+}
+
+function exportState(sessionManager: SessionManager): SessionState {
+  return { harness: 'pi', version: STATE_VERSION, data: pruneSessionEntries([sessionManager.getHeader(), ...sessionManager.getEntries()]) };
+}
+
+function classifyAccountLimit(text: string): SessionResult['accountLimit'] {
+  if (RATE_LIMITED.test(text)) return { kind: 'session-limit', text };
+  if (AUTH_REFUSED.test(text)) return { kind: 'not-logged-in', text };
+  return undefined;
+}

package/src/harness/session-state.ts

@@ -0,0 +1,86 @@
+/**
+ * What a session's stored state keeps between runs. A conversation that
+ * continues over many messages carries its pi session entries from run to
+ * run, and two things made that grow without bound on 7 Nov 2026 (6.6 MB
+ * after thirty messages, and the model's output budget clamped to one token
+ * by the context estimate): pi appends a system entry listing every tool at
+ * each session start, since the MCP tools arrive after the session opens, so
+ * thirty identical copies of 66 tool definitions sat in the state; and a
+ * screenshot the agent read stayed in it as 750 KB of base64, which the
+ * token estimate counts as a quarter of a million tokens. Neither is needed
+ * after the run: the model keeps the latest tool list, and a picture it saw
+ * once is read again when it is needed.
+ *
+ * A tool-list entry is dropped only when it changes nothing: replayed in order, as pi replays them, the tools in
+ * place before it and after it are the same. The first declaration stays where it was, before the calls that use it,
+ * and a tool removed and added again keeps each step, which a model shown tool changes in place reads in order.
+ *
+ * Entries form a parent-linked chain (`id`, `parentId`); a pruned entry's
+ * children are linked to its parent, so the chain stays whole.
+ */
+
+interface Entry {
+  id?: string;
+  parentId?: string | null;
+  type?: string;
+  message?: { role?: string; sections?: unknown; toolsAdded?: unknown; toolsRemoved?: unknown; content?: unknown };
+}
+
+const KB = 1024;
+
+/** The one-line stand-in for an image the model was shown in an earlier turn. */
+export function imageStandIn(mimeType: string | undefined, bytes: number): { type: 'text'; text: string } {
+  const kind = mimeType && typeof mimeType === 'string' ? mimeType : 'image';
+  return { type: 'text', text: `[An image (${kind}, ${Math.max(1, Math.round((bytes * 3) / 4 / KB))} KB) was shown here in an earlier turn; read the file again to see it.]` };
+}
+
+/** The tools in place after a system entry, by name, as pi replays them: its removals, then its additions. */
+function withToolChanges(tools: ReadonlyMap<string, string>, m: NonNullable<Entry['message']>): Map<string, string> {
+  const next = new Map(tools);
+  for (const t of Array.isArray(m.toolsRemoved) ? (m.toolsRemoved as Array<{ name?: unknown }>) : []) if (typeof t?.name === 'string') next.delete(t.name);
+  for (const t of Array.isArray(m.toolsAdded) ? (m.toolsAdded as Array<{ name?: unknown }>) : []) if (typeof t?.name === 'string') next.set(t.name, JSON.stringify(t));
+  return next;
+}
+
+const sameTools = (a: ReadonlyMap<string, string>, b: ReadonlyMap<string, string>) => a.size === b.size && [...a].every(([name, tool]) => b.get(name) === tool);
+
+/** The entries as the next run should start from: a tool list that changes nothing dropped, pictures replaced by a line. */
+export function pruneSessionEntries<T>(entries: readonly T[]): T[] {
+  const list = entries as unknown as Entry[];
+  // An entry that only changes the tools (no prompt sections, no instruction text), and leaves them as they were, is dropped.
+  const onlyTools = (m: NonNullable<Entry['message']>) =>
+    m.sections === undefined && (m.toolsAdded !== undefined || m.toolsRemoved !== undefined) && (m.content === undefined || m.content === '' || (Array.isArray(m.content) && m.content.length === 0));
+  const drop = new Set<Entry>();
+  let tools = new Map<string, string>();
+  for (const e of list) {
+    const m = e.message;
+    if (e.type !== 'message' || !m || m.role !== 'system') continue;
+    const next = withToolChanges(tools, m);
+    if (onlyTools(m) && sameTools(tools, next)) drop.add(e);
+    tools = next;
+  }
+  const parentOf = new Map<string, string | null | undefined>();
+  for (const e of drop) if (e.id) parentOf.set(e.id, e.parentId);
+  const resolveParent = (id: string | null | undefined): string | null | undefined => {
+    let cur = id;
+    while (cur && parentOf.has(cur)) cur = parentOf.get(cur);
+    return cur;
+  };
+  const out: Entry[] = [];
+  for (const e of list) {
+    if (drop.has(e)) continue;
+    let next = e;
+    if (e.parentId && parentOf.has(e.parentId)) next = { ...e, parentId: resolveParent(e.parentId) };
+    const m = next.message;
+    if (next.type === 'message' && m?.role === 'toolResult' && Array.isArray(m.content)) {
+      const content = (m.content as Array<Record<string, unknown>>).map((block) =>
+        block && typeof block === 'object' && block.type === 'image' && typeof block.data === 'string'
+          ? imageStandIn(typeof block.mimeType === 'string' ? block.mimeType : undefined, block.data.length)
+          : block,
+      );
+      if (content.some((b, i) => b !== (m.content as unknown[])[i])) next = { ...next, message: { ...m, content } };
+    }
+    out.push(next);
+  }
+  return out as unknown as T[];
+}

package/src/harness/stall-guard.ts

@@ -0,0 +1,97 @@
+/**
+ * A fetch for the model gateway that ends a stalled request instead of sitting on it.
+ *
+ * Pi retries a model call that fails, but a call that never answers is not a failure to it: nothing
+ * bounds the wait but Node's own 300-second header limit and the run's 30-minute limit. On 8 Nov 2026
+ * a Teams reply sat five minutes before its first model call for exactly that reason, with no progress
+ * lines, since there was nothing to narrate. This fetch aborts when the response headers take longer
+ * than `headersMs`, or when a reply that has started sends nothing for `bodyMs`, and throws an error
+ * whose words pi's retry classifier accepts ("connection lost", "stream was interrupted"), so the next
+ * attempt follows at once.
+ */
+export interface StallGuardOptions {
+  /** How long to wait for the response headers. */
+  headersMs: number;
+  /** How long a started reply may go without a byte. */
+  bodyMs: number;
+}
+
+export type FetchLike = typeof globalThis.fetch;
+
+export class StalledRequestError extends Error {
+  constructor(
+    readonly phase: 'headers' | 'body',
+    waitedMs: number,
+  ) {
+    super(
+      phase === 'headers'
+        ? `gateway stalled: no response headers in ${Math.round(waitedMs / 1000)} s (connection lost)`
+        : `gateway stalled: no bytes for ${Math.round(waitedMs / 1000)} s mid-reply (stream was interrupted)`,
+    );
+    this.name = 'StalledRequestError';
+  }
+}
+
+export function stallGuardedFetch(inner: FetchLike, options: StallGuardOptions): FetchLike {
+  return async (input, init) => {
+    const controller = new AbortController();
+    let stalled: StalledRequestError | undefined;
+    const outer = init?.signal;
+    if (outer?.aborted) controller.abort(outer.reason);
+    else outer?.addEventListener('abort', () => controller.abort(outer.reason), { once: true });
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const arm = (phase: 'headers' | 'body', ms: number) => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        stalled = new StalledRequestError(phase, ms);
+        controller.abort(stalled);
+      }, ms);
+      (timer as { unref?: () => void }).unref?.();
+    };
+    const translate = (err: unknown): never => {
+      if (stalled) throw stalled;
+      throw err;
+    };
+
+    arm('headers', options.headersMs);
+    let response: Response;
+    try {
+      response = await inner(input, { ...init, signal: controller.signal });
+    } catch (err) {
+      clearTimeout(timer);
+      return translate(err);
+    }
+    if (!response.body) {
+      clearTimeout(timer);
+      return response;
+    }
+    // The reply has started: every chunk re-arms the watchdog; the stream ends it.
+    arm('body', options.bodyMs);
+    const reader = response.body.getReader();
+    const watched = new ReadableStream<Uint8Array>({
+      async pull(ctrl) {
+        let next: ReadableStreamReadResult<Uint8Array>;
+        try {
+          next = await reader.read();
+        } catch (err) {
+          clearTimeout(timer);
+          ctrl.error(stalled ?? err);
+          return;
+        }
+        if (next.done) {
+          clearTimeout(timer);
+          ctrl.close();
+          return;
+        }
+        arm('body', options.bodyMs);
+        ctrl.enqueue(next.value);
+      },
+      cancel(reason) {
+        clearTimeout(timer);
+        return reader.cancel(reason);
+      },
+    });
+    return new Response(watched, { status: response.status, statusText: response.statusText, headers: response.headers });
+  };
+}