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

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