@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

package/src/conversation/message/projection.ts

@@ -75,6 +75,35 @@ function safeInput(value: unknown): Record<string, unknown> {
   return isRecord(safe) ? safe : {};
 }
 
+export type ToolInputPreparer = (
+  toolName: string,
+  input: unknown,
+) => unknown;
+
+function safeToolInput(
+  toolName: string,
+  value: unknown,
+  prepare?: ToolInputPreparer,
+): Record<string, unknown> {
+  if (prepare) {
+    try {
+      value = prepare(toolName, value);
+    } catch {
+      // Preserve invalid provider output for the normal Tool validation path.
+    }
+  }
+  const input = safeInput(value);
+  if (toolName === "ask_user" && typeof input.questions === "string") {
+    try {
+      const questions: unknown = JSON.parse(input.questions);
+      if (Array.isArray(questions)) input.questions = questions;
+    } catch {
+      // Preserve malformed provider output for the normal unavailable state.
+    }
+  }
+  return input;
+}
+
 function contentText(result: unknown): string | undefined {
   if (!isRecord(result) || !Array.isArray(result.content)) return undefined;
   const text = result.content.flatMap((part) =>
@@ -175,6 +204,7 @@ export class PiChunkEncoder {
   private readonly startedAt?: number;
   private readonly turnId?: string;
   private readonly userMessageId?: string;
+  private readonly prepareToolInput?: ToolInputPreparer;
   private started = false;
   private finished = false;
   private firstTurnStarted = false;
@@ -194,11 +224,13 @@ export class PiChunkEncoder {
     startedAt?: number;
     turnId?: string;
     userMessageId?: string | null;
+    prepareToolInput?: ToolInputPreparer;
   }) {
     this.messageId = options.messageId;
     this.startedAt = options.startedAt;
     this.turnId = options.turnId;
     this.userMessageId = options.userMessageId ?? undefined;
+    this.prepareToolInput = options.prepareToolInput;
   }
 
   start(): UIMessageChunk[] {
@@ -277,7 +309,7 @@ export class PiChunkEncoder {
     toolName: string,
     input: unknown,
   ): UIMessageChunk[] {
-    const safe = safeInput(input);
+    const safe = safeToolInput(toolName, input, this.prepareToolInput);
     this.toolInputs.set(toolCallId, { toolName, input: safe });
     return [{
       type: "tool-input-available",
@@ -341,6 +373,23 @@ export class PiChunkEncoder {
         const chunks = this.toolInputs.has(event.toolCallId)
           ? []
           : this.toolInput(event.toolCallId, event.toolName, event.args);
+        const partialResult = isRecord(event.partialResult)
+          ? event.partialResult
+          : undefined;
+        const details = isRecord(partialResult?.details)
+          ? partialResult.details
+          : undefined;
+        const actionToolMeta = isRecord(details?.actionToolMeta)
+          ? details.actionToolMeta
+          : undefined;
+        if (actionToolMeta) {
+          chunks.push({
+            type: "data-action-tool-meta",
+            id: event.toolCallId,
+            data: { toolCallId: event.toolCallId, ...actionToolMeta },
+          });
+          return chunks;
+        }
         chunks.push({
           type: "tool-output-available",
           toolCallId: event.toolCallId,
@@ -505,18 +554,11 @@ export class PiChunkEncoder {
       streaming.deltas.length = 0;
     }
     if (update.type === "toolcall_end") {
-      const input = safeInput(update.toolCall.arguments);
-      this.toolInputs.set(toolCallId, {
-        toolName: update.toolCall.name,
-        input,
-      });
-      chunks.push({
-        type: "tool-input-available",
+      chunks.push(...this.toolInput(
         toolCallId,
-        toolName: update.toolCall.name,
-        input,
-        dynamic: true,
-      });
+        update.toolCall.name,
+        update.toolCall.arguments,
+      ));
       this.pendingToolByIndex.delete(index);
       this.toolCallIdByIndex.delete(index);
     }
@@ -553,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)
@@ -613,15 +661,7 @@ function projectedTool(
   call: ToolCall,
   approval?: PiToolApprovalView,
 ): DynamicToolUIPart {
-  const input = safeInput(call.arguments);
-  if (call.name === "ask_user" && typeof input.questions === "string") {
-    try {
-      const questions: unknown = JSON.parse(input.questions);
-      if (Array.isArray(questions)) input.questions = questions;
-    } catch {
-      // Preserve malformed provider output for the normal unavailable state.
-    }
-  }
+  const input = safeToolInput(call.name, call.arguments);
   const base = {
     type: "dynamic-tool" as const,
     toolCallId: call.id,

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/conversation/state.ts

@@ -1,6 +1,6 @@
 import type { ApprovalReceipt } from "../submission/contracts";
 import type { StoredSubmission } from "../submission/repository";
-import type { PendingApprovalSummary } from "../tools/approval/repository";
+import type { PendingApprovalSummary } from "../tools/runtime/approval/repository";
 import type { PiCanonicalUserInput } from "./message/contract";
 
 export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
@@ -68,6 +68,17 @@ export interface RuntimeTurnState {
   queued: RuntimeQueuedSubmission[];
 }
 
+/**
+ * 本 Session 当前是否拒绝普通用户输入。
+ *
+ * 定时 Run 未结束时它独占输入:宿主据此禁用输入框并显示原因。
+ * 服务端准入用同一事实拒绝消息,所以客户端状态与后端判定不会漂移。
+ */
+export interface RuntimeInputLock {
+  /** 稳定原因码,由宿主/UI 决定文案。 */
+  reason: string;
+}
+
 /**
  * 保存 Kernel 在当前会话里自己维护的审批状态。
  *
@@ -85,6 +96,8 @@ export interface RuntimeState {
   activity?: RuntimeActivityProjection;
   approvals?: ApprovalReceipt[];
   turn?: RuntimeTurnState;
+  /** 有值时普通输入被锁定,直到锁定的 Submission 进入终态。 */
+  inputLock?: RuntimeInputLock;
 }
 
 type SubmissionProjection = Pick<
@@ -103,6 +116,8 @@ export function projectRuntimeState(input: {
   readonly hasPendingInteraction: (submissionId: string) => boolean;
   readonly hasPendingSteer: (submissionId: string) => boolean;
   readonly hasRunningAgentTools: boolean;
+  /** A non-terminal scheduled Submission owns ordinary input until it ends. */
+  readonly hasUnfinishedScheduled?: boolean;
   readonly previousState: RuntimeState;
 }): { state: RuntimeState; changed: boolean } {
   const approvals: ApprovalReceipt[] = [
@@ -164,12 +179,18 @@ export function projectRuntimeState(input: {
       backgroundWork: input.hasRunningAgentTools,
       revision: (previousActivity?.revision ?? 0) + 1,
     };
+  const inputLock: RuntimeInputLock | undefined = input.hasUnfinishedScheduled
+    ? { reason: "scheduled-run" }
+    : undefined;
   const changed = input.previousState.approvals === undefined ||
     JSON.stringify(input.previousState.approvals) !== JSON.stringify(approvals) ||
     JSON.stringify(input.previousState.turn) !== JSON.stringify(turn) ||
+    JSON.stringify(input.previousState.inputLock) !== JSON.stringify(inputLock) ||
     nextActivity !== previousActivity;
   return {
-    state: changed ? { ...input.previousState, activity: nextActivity, approvals, turn } : input.previousState,
+    state: changed
+      ? { ...input.previousState, activity: nextActivity, approvals, turn, inputLock }
+      : input.previousState,
     changed,
   };
 }

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";