@springbrand/agent-runtime 0.3.0-alpha.17 → 0.3.0-alpha.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.17",
+  "version": "0.3.0-alpha.19",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/agent.ts

@@ -71,7 +71,7 @@ import type {
 } from "@earendil-works/pi-ai";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { openCloudflareSession } from "../../session";
-import { openSessionHarness, prepareSubmissionOperation } from "../../harness";
+import { ModelRecovery, openSessionHarness, prepareSubmissionOperation } from "../../harness";
 import type { SessionHarness } from "../../harness";
 import {
   compileHarnessTools,
@@ -789,10 +789,13 @@ export abstract class AgentRuntimeKernel<
       (key) => this.ensureRuntimeVersion(key),
     );
     const activeRuntime = this.requireRuntime();
+    // A fresh provider Session per Submission keeps one failing upstream route from pinning later turns.
+    const recovery = new ModelRecovery(submissionId);
     const harnessInput = this.pi.harnessInputs(
       activeRuntime.pi,
       submission.assemblyDescriptor,
       {
+          modelSessionId: () => recovery.sessionId(),
           assertRequestAllowed: () => {
             const current = this.db.submissions.find(submissionId);
             if (current?.abortReason || current?.unattendedFailure) throw new Error(current.abortReason ?? current.unattendedFailure!);
@@ -875,6 +878,7 @@ export abstract class AgentRuntimeKernel<
       streamOptions: { maxRetries: 0 },
       compaction: harnessInput.compaction,
       toolExecution: "parallel",
+      recovery,
       beforeTool: (call, _api, context) => gate.beforeTool({ toolName: call.name, toolCallId: call.id, args: call.arguments }, context),
       afterResponse: (message) => {
         for (const part of message.content) if (part.type === "toolCall") part.arguments = prepareToolInput(part.name, part.arguments) as JsonObject;
@@ -883,6 +887,7 @@ export abstract class AgentRuntimeKernel<
     this.activeHarness = runtime;
     let stream: Awaited<ReturnType<typeof bindHarnessStream>> | undefined;
     let deactivate = () => {};
+    let released = false;
     try {
 
       if ((submission.abortReason || submission.unattendedFailure) && runtime.openOperation) {
@@ -985,6 +990,7 @@ export abstract class AgentRuntimeKernel<
             idempotent: true,
           });
         }
+        released = true;
         return this.db.submissions.find(submissionId)!;
       }
       const record = outcome.outcome;
@@ -1025,6 +1031,14 @@ export abstract class AgentRuntimeKernel<
       deactivate();
       if (this.activeHarness === runtime) this.activeHarness = undefined;
       await runtime.close(BACKGROUND_CONTEXT).catch(() => undefined);
+      if (released) {
+        // Pi closes the Harness on release and drops undelivered stream frames; the
+        // canonical transcript gives a paused question or approval its complete input.
+        this.broadcast(json({
+          type: MessageType.CF_AGENT_CHAT_MESSAGES,
+          messages: await this.getMessages(),
+        }));
+      }
     }
   }
 
@@ -1058,7 +1072,7 @@ export abstract class AgentRuntimeKernel<
   /** Start the native resume handshake from Pi's current lane snapshot. */
   async onConnect(connection: Connection): Promise<void> {
     this.conversation.disconnect(connection);
-    await this.conversation.resume(connection);
+    await this.conversation.connect(connection);
   }
 
   async onClose(connection: Connection, code: number, reason: string, wasClean: boolean): Promise<void> {

package/src/adapter/cloudflare/subagent/definition.ts

@@ -424,6 +424,16 @@ export abstract class CloudflareSubAgent<
           const progress = progressFor(event);
           if (progress) this.persistProgress(runId, progress);
         },
+        // Live frames can stop short of the last response; the canonical entries are the billed total.
+        onEntries: (entries) => {
+          const canonical = emptySubagentUsage();
+          for (const entry of entries) {
+            const message = entry.model?.[0];
+            if (message?.role === "assistant") addSubagentUsage(canonical, message.usage);
+          }
+          Object.assign(usage, canonical);
+          this.persistUsage(runId, usage);
+        },
       });
       publish(projection.finish({ status: "completed", endedAt: Date.now() }));
       this.completeRun(runId, output, usage);

package/src/adapter/cloudflare/subagent/runner.ts

@@ -1,5 +1,5 @@
 import type { StreamFn } from "@earendil-works/pi-agent-core";
-import type { AgentEvent as HarnessEvent, Storage as Session, ToolRegistration } from "@earendil-works/pi-durable";
+import type { AgentEvent as HarnessEvent, AgentEventStream, EntryRecord, Storage as Session, ToolRegistration } from "@earendil-works/pi-durable";
 import {
   awaitWithContext,
   BACKGROUND_CONTEXT,
@@ -38,8 +38,21 @@ export interface CloudflareSubAgentRun {
   tools?: ToolRegistration<any, any>[];
   signal?: AbortSignal;
   timeoutMs?: number;
-  /** Native operation events for projections that must survive model retries. */
+  /** Native operation events for live projections; they may stop short of the final frame. */
   onEvent?: (event: HarnessEvent, signal: AbortSignal) => void | Promise<void>;
+  /** This operation's canonical entries after each settle or release, the source of its final usage. */
+  onEntries?: (entries: readonly EntryRecord[]) => void | Promise<void>;
+}
+
+/** The first failed Tool result among an operation's canonical entries. */
+function toolFailureOf(entries: readonly EntryRecord[]): { name: string; error: string } | undefined {
+  for (const entry of entries) {
+    const result = entry.model?.[0];
+    if (result?.role !== "toolResult" || !result.isError) continue;
+    const diagnostics = (entry.data as { diagnostics?: Array<{ severity: string; message: string }> } | undefined)?.diagnostics;
+    return { name: result.toolName, error: diagnostics?.find((item) => item.severity === "error")?.message ?? toolErrorText(result) };
+  }
+  return undefined;
 }
 
 function textOf(message: AssistantMessage): string {
@@ -129,7 +142,13 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
     compaction: { enabled: false, reserveTokens: 1, keepRecentTokens: 1 },
   } satisfies Omit<SessionHarnessOptions, "storage">;
   let runtime: SessionHarness | undefined;
+  let events: AgentEventStream | undefined;
   let toolFailure: { name: string; error: string } | undefined;
+  const operationEntries = async (active: SessionHarness): Promise<EntryRecord[]> => {
+    const submission = await active.submissionFor(operationId, BACKGROUND_CONTEXT);
+    const entries = await active.entries(BACKGROUND_CONTEXT);
+    return submission?.entry === undefined ? [] : entries.filter((entry) => entry.id >= submission.entry!);
+  };
 
   let timedOut = false;
   const timeout = setTimeout(() => {
@@ -148,15 +167,9 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
         if (runtime.openOperation && runtime.openOperation.operationId !== operationId) {
           throw new Error("SubAgent Session has an unrelated open operation");
         }
-        const watch = await runtime.watch(context);
-        watch.start(async (events) => {
-          for (const event of events) {
-            await run.onEvent?.(event, signal);
-            if (event.type === "tool_execution_end") {
-              const result = event.entry?.model?.[0];
-              if (result?.role === "toolResult" && result.isError) toolFailure ??= { name: event.toolName, error: ((event.entry?.data as { diagnostics?: Array<{ severity: string; message: string }> } | undefined)?.diagnostics?.find((item) => item.severity === "error")?.message ?? toolErrorText(result)) };
-            }
-          }
+        events = await runtime.watch(context);
+        events.start(async (batch) => {
+          for (const event of batch) await run.onEvent?.(event, signal);
         });
       }
       const result = await runtime.run(
@@ -168,12 +181,18 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
           : undefined,
         context,
       );
+      await events?.stop();
+      events = undefined;
       if (result.kind === "released") {
         await runtime.close(BACKGROUND_CONTEXT);
         runtime = undefined;
         continue;
       }
       settled = result;
+      // Pi's stop may drop the last frames; failures and usage come from the canonical record.
+      const owned = await operationEntries(runtime);
+      toolFailure = toolFailureOf(owned);
+      await run.onEntries?.(owned);
       break;
     }
     if (timedOut) throw new Error("SubAgent run timed out");
@@ -215,6 +234,7 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
       await runtime.abort(BACKGROUND_CONTEXT).catch(() => undefined);
       await runtime.run(undefined, BACKGROUND_CONTEXT).catch(() => undefined);
     }
+    await events?.stop();
     await runtime?.close(BACKGROUND_CONTEXT).catch(() => undefined);
   }
 }

package/src/config/harness-runtime.ts

@@ -91,7 +91,7 @@ export class HarnessRuntimeConfig {
     prepared: PreparedPiRuntime,
     pinnedDescriptor: string,
     request: {
-      readonly modelSessionId?: string;
+      readonly modelSessionId?: string | (() => string);
       readonly onGeneration?: PiGenerationLifecycleObserver;
       readonly assertRequestAllowed?: () => void;
       readonly onCompactionGeneration?: PiGenerationLifecycleObserver;

package/src/conversation/harness-resume.ts

@@ -54,21 +54,28 @@ export class HarnessConversationBridge {
       await this.send(session.connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE, id: session.source.requestId, body: JSON.stringify(chunk), done: false, ...(replay ? { replay: true, continuation: false } : {}) });
     }
   }
-  async resume(connection: Connection, probeId?: string): Promise<void> {
+  /**
+   * A socket just opened: offer the live stream if one exists, otherwise only
+   * sync messages. Like Cloudflare's AIChatAgent, an idle connect sends no
+   * STREAM_RESUME_NONE. The client answers its own resume probe from the
+   * reply that carries its probeId; an unsolicited, probe-less "none" arriving
+   * first consumes that pending probe without clearing the client's
+   * server-streaming state, which leaves a reconnected Chat stuck streaming
+   * after a Turn that ended while it was offline.
+   */
+  connect(connection: Connection): Promise<void> {
+    return this.resume(connection, undefined, false);
+  }
+  /** Answer a client's stream-resume request; `announceIdle` is false only for {@link connect}. */
+  async resume(connection: Connection, probeId?: string, announceIdle = true): Promise<void> {
     this.disconnect(connection);
     const source = this.active;
-    if (!source) {
-      await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: await this.host.history.browserMessages() });
-      await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUME_NONE, reason: STREAM_RESUME_NONE_REASONS.IDLE, ...(probeId ? { probeId } : {}) });
-      return;
-    }
+    if (!source) return this.idle(connection, probeId, announceIdle);
     const watch = await source.runtime.watch(BACKGROUND_CONTEXT);
-    if (this.active !== source) { await watch.stop(); return this.resume(connection, probeId); }
+    if (this.active !== source) { await watch.stop(); return this.resume(connection, probeId, announceIdle); }
     if (!watch.snapshot.run) {
       await watch.stop();
-      await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: await this.host.history.browserMessages() });
-      await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUME_NONE, reason: STREAM_RESUME_NONE_REASONS.IDLE, ...(probeId ? { probeId } : {}) });
-      return;
+      return this.idle(connection, probeId, announceIdle);
     }
     const messages = await this.host.history.browserSnapshot(watch.snapshot, source.submissionId);
     const replay = this.replayMessage(messages, source.submissionId);
@@ -77,6 +84,15 @@ export class HarnessConversationBridge {
     await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: replay ? messages.filter((message) => message.id !== replay.id) : messages });
     await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUMING, id: source.requestId, ...(probeId ? { probeId } : {}) });
   }
+  /**
+   * No Turn is running. "None" goes first: while the client still observes the
+   * stream it lost, it keeps its own partial answer over any snapshot that has
+   * no more parts, so the settled answer must arrive after it stops observing.
+   */
+  private async idle(connection: Connection, probeId: string | undefined, announceIdle: boolean): Promise<void> {
+    if (announceIdle) await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUME_NONE, reason: STREAM_RESUME_NONE_REASONS.IDLE, ...(probeId ? { probeId } : {}) });
+    await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: await this.host.history.browserMessages() });
+  }
   async acknowledge(connection: Connection, requestId: string): Promise<void> {
     const session = this.connections.get(connection.id);
     if (!session || session.source.requestId !== requestId || session.started) return;

package/src/conversation/harness-stream.ts

@@ -22,6 +22,7 @@ export class HarnessStreamProjection {
   private readonly encoder: PiChunkEncoder;
   private terminal?: AssistantMessage;
   private readonly shown = new Map<number, string>();
+  private readonly toolInputStarted = new Set<string>();
   private readonly toolOutput = new Map<string, string>();
   constructor(options: HarnessStreamOptions) { this.encoder = new PiChunkEncoder(options); }
   restore(message: UIMessage, streaming: boolean, snapshot?: SnapshotEvent): UIMessageChunk[] {
@@ -33,9 +34,15 @@ export class HarnessStreamProjection {
     for (const tool of snapshot?.tools ?? []) if (tool.output !== undefined) this.toolOutput.set(tool.callId, tool.output);
     return this.encoder.restore(message, streaming);
   }
-  private block(block: AssistantMessage["content"][number], contentIndex: number): UIMessageChunk[] {
+  private block(block: AssistantMessage["content"][number], contentIndex: number, settled = false): UIMessageChunk[] {
     if (block.type === "toolCall" && (!block.id || !block.name)) return [];
-    if (block.type === "toolCall") return this.encoder.encode({ type: "tool_execution_start", toolCallId: block.id, toolName: block.name, args: block.arguments } as LoopEvent);
+    if (block.type === "toolCall") {
+      // The encoder keeps the first input it sees, so only a settled message may publish arguments.
+      if (settled) return this.encoder.encode({ type: "tool_execution_start", toolCallId: block.id, toolName: block.name, args: block.arguments } as LoopEvent);
+      if (this.toolInputStarted.has(block.id)) return [];
+      this.toolInputStarted.add(block.id);
+      return [{ type: "tool-input-start", toolCallId: block.id, toolName: block.name, dynamic: true }];
+    }
     if (block.type !== "text" && block.type !== "thinking") return [];
     const start = block.type === "thinking"
       ? this.encoder.encode({ type: "message_update", assistantMessageEvent: { type: "thinking_start", contentIndex } } as LoopEvent)
@@ -47,7 +54,15 @@ export class HarnessStreamProjection {
     if (!delta) return start;
     return [...start, ...this.encoder.encode({ type: "message_update", assistantMessageEvent: { type: block.type === "text" ? "text_delta" : "thinking_delta", contentIndex, delta } } as LoopEvent)];
   }
-  event(event: AgentEvent): UIMessageChunk[] {
+  /**
+   * Pi emits `run_start` only when the live run changes, so a stream bound to a continued run (after an approval or a
+   * slice release) sees tool or message frames first. The encoder's start is idempotent; lead the first frames with it.
+   */
+  private started(chunks: UIMessageChunk[]): UIMessageChunk[] {
+    return chunks.length === 0 ? chunks : [...this.encoder.start(), ...chunks];
+  }
+  event(event: AgentEvent): UIMessageChunk[] { return this.started(this.frames(event)); }
+  private frames(event: AgentEvent): UIMessageChunk[] {
     switch (event.type) {
       case "run_start": return this.encoder.start();
       case "turn_start": this.terminal = undefined; this.shown.clear(); return this.encoder.encode({ type: "turn_start" } as LoopEvent);
@@ -74,14 +89,14 @@ export class HarnessStreamProjection {
         const message = event.entry.model?.[0];
         if (message?.role !== "assistant") return [];
         this.terminal = message;
-        return [...message.content.flatMap((block, index) => this.block(block, index)), ...this.encoder.encode({ type: "message_end", message }, { terminal: false })];
+        return [...message.content.flatMap((block, index) => this.block(block, index, true)), ...this.encoder.encode({ type: "message_end", message }, { terminal: false })];
       }
       default: return [];
     }
   }
-  approvalRequested(toolCallId: string, approvalId: string): UIMessageChunk[] { return this.encoder.approvalRequested(toolCallId, approvalId); }
+  approvalRequested(toolCallId: string, approvalId: string): UIMessageChunk[] { return this.started(this.encoder.approvalRequested(toolCallId, approvalId)); }
   finish(result: SessionRunOutcome): UIMessageChunk[] {
-    return this.encoder.finish({ stopReason: result.status === "aborted" ? "aborted" : result.status === "failed" ? "error" : this.terminal?.stopReason === "length" ? "length" : "stop", timestamp: result.endedAt, ...(result.error ? { errorMessage: result.error.message } : {}) });
+    return this.started(this.encoder.finish({ stopReason: result.status === "aborted" ? "aborted" : result.status === "failed" ? "error" : this.terminal?.stopReason === "length" ? "length" : "stop", timestamp: result.endedAt, ...(result.error ? { errorMessage: result.error.message } : {}) }));
   }
 }
 
@@ -92,6 +107,7 @@ export async function bindHarnessStream(runtime: SessionHarness, options: Harnes
   watch.start((events) => delivery = (async () => { for (const event of events) await options.publish(projection.event(event)); })());
   return {
     publishApprovalRequest: (toolCallId: string, approvalId: string) => options.publish(projection.approvalRequested(toolCallId, approvalId)),
+    // The Host follows the terminal frame with the canonical transcript, which completes any frame Pi's stop dropped.
     flushTerminal: async (result: SessionRunOutcome) => { await watch.stop(); await delivery; await options.publish(projection.finish(result)); },
     unsubscribe: async () => { await watch.stop(); await delivery; },
   };

package/src/conversation/history.ts

@@ -18,6 +18,30 @@ import {
   type UIUserSidecar,
 } from "./message";
 import { openCloudflareSession, RuntimeConversation } from "../session";
+import { dropLegacyPiTables } from "../session/cloudflare/migration";
+
+/**
+ * Pi Durable 1.1 has no public API that deletes a conversation; `Tx` can only create, fork and retire documents.
+ * Clear therefore deletes every record outside the newly selected conversation from the official SQLite schema
+ * version 1. A different schema version keeps the records rather than guessing at its layout.
+ */
+function deleteConversationsExcept(sql: SqlStorage, keep: number): void {
+  const schema = sql.exec<{ version: number }>("SELECT version FROM durable_schema WHERE singleton=1").toArray()[0]?.version;
+  if (schema !== 1) {
+    console.warn("[conversation-clear:degraded]", `Unsupported Pi Durable SQLite schema ${String(schema)}; previous records kept`);
+    return;
+  }
+  const documents = `SELECT id FROM documents WHERE (scope_kind='conversation' AND owner_id<>?1)
+    OR (scope_kind='task' AND owner_id IN (SELECT id FROM tasks WHERE conversation_id<>?1))`;
+  sql.exec(`DELETE FROM document_revisions WHERE document_id IN (${documents})`, keep);
+  sql.exec(`DELETE FROM record_ids WHERE id IN (${documents}
+    UNION SELECT id FROM submissions WHERE conversation_id<>?1 UNION SELECT id FROM tasks WHERE conversation_id<>?1
+    UNION SELECT id FROM entries WHERE conversation_id<>?1 UNION SELECT id FROM conversations WHERE id<>?1)`, keep);
+  sql.exec(`DELETE FROM documents WHERE id IN (${documents})`, keep);
+  for (const [table, column] of [["submissions", "conversation_id"], ["tasks", "conversation_id"], ["entries", "conversation_id"], ["conversations", "id"]]) {
+    sql.exec(`DELETE FROM ${table} WHERE ${column}<>?`, keep);
+  }
+}
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -264,7 +288,8 @@ export class ConversationHistory {
         const custom = message.role === "custom";
         const entry = await tx.appendEntry(conversationId!, {
           kind: custom ? "springbrand.custom" : message.role === "toolResult" ? "pi.tool-result" : `pi.${message.role}`,
-          ...(custom ? {} : { model: [message] }),
+          // Custom messages reach the model as user context, as Pi's convertToLlm did before the native harness.
+          model: [custom ? { role: "user", content: [...message.content], timestamp: message.timestamp } : message],
           data: JSON.parse(JSON.stringify({ displayId: id, createdAt: message.timestamp, ...(custom ? { message } : {}), ...(options.submissionId ? { submissionId: options.submissionId } : {}), ...(message.role === "toolResult" ? { diagnostics: [] } : {}) })),
         });
         if (options.userMessage) this.durability.upsertUserSidecar(String(entry.id), JSON.stringify({ id: options.userMessage.id, ...captureUIUserSidecar(options.userMessage) }));
@@ -419,10 +444,18 @@ export class ConversationHistory {
    * 两类 Transcript 数据必须一起删除，否则复用消息 ID 时可能重新读到旧附件或 UI 元数据。
    */
   async clear(): Promise<void> {
-    await this.withSession((session) => session.commit(async (tx) => {
-      const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
-      (await tx.doc(RuntimeConversation)).id = conversation.id;
-    }, BACKGROUND_CONTEXT));
+    await this.storage.transaction(() => this.withSession(async (session) => {
+      const next = await session.commit(async (tx) => {
+        const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
+        (await tx.doc(RuntimeConversation)).id = conversation.id;
+        return conversation.id;
+      }, BACKGROUND_CONTEXT);
+      deleteConversationsExcept(this.storage.sql, next);
+      await dropLegacyPiTables(this.storage, session);
+      // Entry associations name records that no longer exist.
+      this.storage.sql.exec("CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL)");
+      this.storage.sql.exec("DELETE FROM pi_session_entry_submission");
+    }));
     this.durability.clearUserSidecars();
   }
 
@@ -563,6 +596,8 @@ export class ConversationHistory {
         entry.message.role === "custom" &&
         entry.message.customType === "turn-aborted"
       ) {
+        // The marker is this stop's terminal; the no-answer fallback would add a second one.
+        if (pendingFailedSubmissionId === entry.submissionId) pendingFailedSubmissionId = undefined;
         const submission = this.durability.findSubmissionProjection(
           entry.submissionId,
         );

package/src/conversation/message/projection.ts

@@ -595,6 +595,12 @@ export class PiChunkEncoder {
           turnDurationMs: Math.max(0, message.timestamp - this.startedAt),
           turnStatus: terminal.turnStatus,
           ...(this.turnId ? { turnId: this.turnId } : {}),
+          // The browser keeps this stream copy over a history snapshot that
+          // arrives while it still observes the stream, so it must carry the
+          // user-stop marker the snapshot projects from `turn-aborted`.
+          ...(terminal.outcome === "aborted" && message.errorMessage === USER_STOP_REASON
+            ? { interruptedByUser: true }
+            : {}),
           ...((publicError ?? terminal.message) &&
               (terminal.outcome !== "aborted" ||
                 message.errorMessage !== USER_STOP_REASON)

package/src/harness/governance.ts

@@ -0,0 +1,206 @@
+import type { AssistantMessage, Message, ToolCall, ToolResultMessage } from "@earendil-works/pi-ai";
+import { isRetryableAssistantError } from "@earendil-works/pi-ai/utils/retry";
+import type { EntryRecord } from "@earendil-works/pi-durable";
+import type { ArtifactRef } from "../lib/artifacts";
+import {
+  isModelStreamStallMessage,
+  isOpenRouterServerToolTimeout,
+  isRecoverableAssistantError,
+} from "../models";
+
+export const MAX_TOOL_RETRIES = 3;
+export const TURN_FAILURE_CEILING = 8;
+export const DEFAULT_MAX_WRAP_UP_MODEL_TURNS = 2;
+export const TOOL_FAILURE_WRAP_UP_INSTRUCTION =
+  "This turn reached its tool failure limit. Stop calling tools now. Reply with a final message that explains what failed and the exact next step the user should take. Do not start new work.";
+const RECOVERY_MAX_FAILURES = 5;
+const STALL_MAX_FAILURES = 3;
+const SERVER_TOOL_TIMEOUT_MAX_FAILURES = 2;
+const ARTIFACT_MANIFEST_MAX_CHARS = 12 * 1024;
+/** Harness diagnostics for calls that never crossed the Tool effect boundary. */
+const UNEXECUTED_CODES = new Set(["blocked", "tool_unavailable", "invalid_arguments", "interrupted", "aborted"]);
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+export function toolCallKey(toolName: string, args: unknown): string {
+  return `${toolName}\0${canonicalJson(args)}`;
+}
+
+function resultCodes(entry: EntryRecord): string[] {
+  const diagnostics = (entry.data as { diagnostics?: { code?: unknown }[] } | undefined)?.diagnostics;
+  return Array.isArray(diagnostics)
+    ? diagnostics.flatMap((item) => typeof item?.code === "string" ? [item.code] : [])
+    : [];
+}
+
+/**
+ * Per-Submission Tool failure budget: an exact call that keeps failing is blocked, and too many failures in one
+ * Submission switch it to a text-only wrap-up. Counts are rebuilt from canonical entries after a restart.
+ */
+export class ToolGovernance {
+  private readonly failures = new Map<string, number>();
+  private total = 0;
+  wrapUp = false;
+  /** Completed model turns when the wrap-up began; the wrap-up then has a bounded number of text turns. */
+  wrapUpAt: number | undefined;
+
+  restore(entries: readonly EntryRecord[]): void {
+    this.failures.clear();
+    this.total = 0;
+    this.wrapUp = false;
+    this.wrapUpAt = undefined;
+    const calls = new Map<string, ToolCall>();
+    let turns = 0;
+    for (const entry of entries) {
+      const message = entry.model?.[0];
+      if (message?.role === "assistant") {
+        turns += 1;
+        for (const part of message.content) if (part.type === "toolCall") calls.set(part.id, part);
+        continue;
+      }
+      if (message?.role !== "toolResult") continue;
+      const call = calls.get(message.toolCallId);
+      if (!call) continue;
+      const codes = resultCodes(entry);
+      if (codes.some((code) => UNEXECUTED_CODES.has(code))) {
+        if (codes.includes("blocked") && this.exhausted(call)) this.startWrapUp(turns);
+        continue;
+      }
+      this.record(call, message.isError, turns);
+    }
+  }
+
+  exhausted(call: Pick<ToolCall, "name" | "arguments">): boolean {
+    return (this.failures.get(toolCallKey(call.name, call.arguments)) ?? 0) >= MAX_TOOL_RETRIES;
+  }
+
+  /** Returns a block reason, or undefined when the call may run. */
+  admit(call: Pick<ToolCall, "name" | "arguments">, turns: number): string | undefined {
+    if (this.wrapUp) return "This turn reached its tool failure limit. Stop calling tools now.";
+    if (!this.exhausted(call)) return undefined;
+    this.startWrapUp(turns);
+    return `This exact ${call.name} call has already failed ${MAX_TOOL_RETRIES} times — change the input or approach instead of retrying it verbatim.`;
+  }
+
+  record(call: Pick<ToolCall, "name" | "arguments">, isError: boolean, turns: number): void {
+    const key = toolCallKey(call.name, call.arguments);
+    if (!isError) {
+      this.failures.delete(key);
+      return;
+    }
+    this.failures.set(key, (this.failures.get(key) ?? 0) + 1);
+    this.total += 1;
+    if (this.total >= TURN_FAILURE_CEILING) this.startWrapUp(turns);
+  }
+
+  private startWrapUp(turns: number): void {
+    this.wrapUp = true;
+    this.wrapUpAt ??= turns;
+  }
+}
+
+/**
+ * Provider-error recovery the durable Harness cannot express by itself: per-class budgets, refusing deterministic
+ * failures, and a fresh provider Session after an OpenRouter server Tool timeout so retries leave a failing route.
+ * Pi only retries messages its own classifier accepts, so recoverable failures it does not recognize are labelled.
+ */
+export class ModelRecovery {
+  private failures = 0;
+  private stalls = 0;
+  private serverToolTimeouts = 0;
+  private allowed = true;
+
+  constructor(private readonly baseSessionId: string) {}
+
+  /** Provider Session identity for the next request. */
+  sessionId(): string {
+    return this.serverToolTimeouts === 0
+      ? this.baseSessionId
+      : `${this.baseSessionId}:server-tool-recovery:${this.serverToolTimeouts}`;
+  }
+
+  /** Whether the Harness may retry the response last passed to {@link classify}. */
+  get retryAllowed(): boolean {
+    return this.allowed;
+  }
+
+  /** Classify one terminal provider response before the Harness decides whether to retry it. */
+  classify(message: AssistantMessage): void {
+    if (message.stopReason !== "error") {
+      this.allowed = true;
+      return;
+    }
+    this.failures += 1;
+    const stalled = isModelStreamStallMessage(message.errorMessage);
+    const serverToolTimeout = isOpenRouterServerToolTimeout(message);
+    if (stalled) this.stalls += 1;
+    if (serverToolTimeout) this.serverToolTimeouts += 1;
+    const recoverable = stalled || serverToolTimeout || isRecoverableAssistantError(message);
+    this.allowed = recoverable && this.failures < RECOVERY_MAX_FAILURES &&
+      (!stalled || this.stalls < STALL_MAX_FAILURES) &&
+      (!serverToolTimeout || this.serverToolTimeouts < SERVER_TOOL_TIMEOUT_MAX_FAILURES);
+    if (this.allowed && !isRetryableAssistantError(message)) {
+      // Pi's classifier does not know our stall watchdog or OpenRouter's HTTP/2 upstream failure. Only a retried
+      // attempt carries the label; a final failure keeps the provider text.
+      message.errorMessage = `network error: ${message.errorMessage ?? "recoverable provider failure"}`;
+    }
+  }
+}
+
+export function artifactRefFromMessage(message: Message | Pick<ToolResultMessage, "role" | "details">): ArtifactRef | undefined {
+  if (message.role !== "toolResult" || message.details === null ||
+    typeof message.details !== "object" ||
+    (message.details as { kind?: unknown }).kind !== "artifact_ref") {
+    return undefined;
+  }
+  const ref = message.details as Partial<ArtifactRef>;
+  if (typeof ref.path !== "string" || typeof ref.hash !== "string" ||
+    typeof ref.bytes !== "number" || typeof ref.preview !== "string" ||
+    typeof ref.note !== "string") return undefined;
+  return {
+    kind: "artifact_ref",
+    artifactId: typeof ref.artifactId === "string" ? ref.artifactId : `artifact_${ref.hash.slice(0, 24)}`,
+    path: ref.path,
+    bytes: ref.bytes,
+    hash: ref.hash,
+    workspaceRevision: typeof ref.workspaceRevision === "string" ? ref.workspaceRevision : "unknown",
+    availability: ref.availability === "unavailable" ? "unavailable" : "available",
+    preview: ref.preview,
+    note: ref.note,
+  };
+}
+
+/** Lightweight pointers to spilled Tool output, so the model can reread evidence after compaction. */
+export function artifactManifestMessage(refs: ReadonlyMap<string, ArtifactRef>): Message | undefined {
+  if (refs.size === 0) return undefined;
+  const lines = [
+    "<workspace_artifact_manifest>",
+    "These are lightweight references to prior Tool output. Do not treat previews as complete. Read an available artifact with the Workspace readFile/readFilePage tool only when the current request needs its evidence.",
+  ];
+  let omitted = 0;
+  for (const ref of refs.values()) {
+    const preview = ref.preview.replace(/[\r\n]+/g, " ").slice(0, 160);
+    const line = [
+      `path=${ref.path}`,
+      ...(ref.availability === "unavailable" ? ["unavailable"] : []),
+      `preview=${preview}`,
+    ].join(" ");
+    if ([...lines, line, "</workspace_artifact_manifest>"].join("\n").length > ARTIFACT_MANIFEST_MAX_CHARS) {
+      omitted += 1;
+      continue;
+    }
+    lines.push(line);
+  }
+  if (omitted > 0) lines.push(`omitted=${omitted} additional artifact references due to manifest budget`);
+  lines.push("</workspace_artifact_manifest>");
+  return { role: "user", content: lines.join("\n"), timestamp: 1 };
+}

package/src/harness/index.ts

@@ -7,3 +7,4 @@ export type {
   SessionRunRequest,
 } from "./session-harness";
 export { prepareSubmissionOperation } from "./submission-operation";
+export { ModelRecovery } from "./governance";