@springbrand/agent-runtime 0.3.0-alpha.16 → 0.3.0-alpha.18

package/src/conversation/session-entry.ts

@@ -0,0 +1,29 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { EntryRecord } from "@earendil-works/pi-durable";
+import type { Usage } from "@earendil-works/pi-ai";
+
+/** Browser/Host projection only; Pi's EntryRecord remains the canonical record. */
+export type ProjectedSessionEntry = {
+  id: string;
+  identity: string;
+  timestamp: number;
+  submissionId?: string;
+} & ({ type: "message"; message: AgentMessage } | {
+  type: "compaction" | "branch_summary";
+  summary: string;
+  usage?: Usage;
+});
+
+export function projectSessionEntry(entry: EntryRecord): ProjectedSessionEntry {
+  const data = entry.data as { createdAt?: number; displayId?: string; submissionId?: string; message?: AgentMessage } | undefined;
+  const message = entry.model?.[0];
+  const base = { id: String(entry.id), identity: data?.displayId ?? String(entry.id), timestamp: data?.createdAt ?? message?.timestamp ?? 0, ...(data?.submissionId ? { submissionId: data.submissionId } : {}) };
+  if (entry.kind === "pi.compaction") return {
+    ...base, type: "compaction",
+    summary: message?.role === "user" ? typeof message.content === "string" ? message.content : message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("") : "",
+  };
+  return {
+    ...base, type: "message",
+    message: entry.kind === "springbrand.retained-context" ? { role: "custom", customType: entry.kind, content: [], timestamp: base.timestamp } : data?.message ?? message ?? { role: "custom", customType: entry.kind, content: [], timestamp: base.timestamp },
+  };
+}

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

@@ -3,5 +3,8 @@ export type {
   SessionHarnessLimits,
   SessionHarnessOptions,
   SessionHarnessRunResult,
+  SessionRunOutcome,
+  SessionRunRequest,
 } from "./session-harness";
 export { prepareSubmissionOperation } from "./submission-operation";
+export { ModelRecovery } from "./governance";