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

package/src/harness/session-harness.ts

@@ -1,481 +1,305 @@
 import {
-  AgentHarness,
-  type AgentMessage,
-  type AgentHarness as PiAgentHarness,
-  type AgentHarnessOptions,
-  type AgentLane,
-  type DriveOutcome,
-  type DriveOptions,
-  type OpenOperation,
-  type OperationRequest,
-} from "@earendil-works/pi-agent-core";
-import type { Context } from "@earendil-works/pi-agent-core/harness/context";
-import type { Entry, SettledAssistantMessage } from "@earendil-works/pi-agent-core/harness/session";
+  Harness, GenerationTask, ToolTask, AgentDoc,
+} from "@earendil-works/pi-durable";
 import {
-  isModelStreamStallMessage,
-  isOpenRouterServerToolTimeout,
-  isRecoverableAssistantError,
-} from "../models";
+  createRegistry, defineExtension, hook, section, watchEvents,
+  type ConversationRetryPolicy, type AgentEventStream, type CompactionPolicy, type Conversation,
+  type EntryId, type EntryRecord, type GenerationHooks, type Harness as NativeHarness,
+  type SettledSubmissionRecord, type Storage, type Submission,
+  type ToolHooks, type ToolRegistration,
+} from "@earendil-works/pi-durable";
+import type { Context } from "@earendil-works/chord";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import type { Api, Message, Model, Models, ModelThinkingLevel, UserMessage } from "@earendil-works/pi-ai";
+import { RuntimeConversation } from "../session";
 import { projectToolOutputForModel } from "../context/memory/budget/gate";
+import type { ArtifactRef } from "../lib/artifacts";
+import {
+  DEFAULT_MAX_WRAP_UP_MODEL_TURNS, TOOL_FAILURE_WRAP_UP_INSTRUCTION, ModelRecovery, ToolGovernance,
+  artifactManifestMessage, artifactRefFromMessage,
+} from "./governance";
+
+const DEFAULT_WRAP_UP_INSTRUCTION = "Finish this request now without using tools. Summarize the completed work and any remaining limitation.";
 
 export interface SessionHarnessLimits {
-  /** Complete model turns committed before one Worker instance releases. */
   modelTurnsPerSlice?: number;
-  /** Complete working turns allowed before the no-tool final response. */
   maxModelTurns?: number;
-  /** Maximum text turns allowed after the working or Tool failure budget. */
+  /** Text turns allowed after the working or Tool failure budget before the Submission is stopped. */
   maxWrapUpModelTurns?: number;
   wrapUpInstruction?: string;
 }
-
-export interface SessionHarnessOptions<TContext extends object | undefined>
-  extends AgentHarnessOptions<TContext> {
-  limits?: SessionHarnessLimits;
+export interface SessionHarnessOptions {
+  storage: Storage | Promise<Storage>;
+  models: Models;
+  model: Model<Api>;
+  thinkingLevel?: ModelThinkingLevel;
+  systemPrompt?: string;
+  tools?: readonly ToolRegistration<any, any>[];
+  activeToolNames?: readonly string[];
+  onDemandToolNames?: readonly string[];
   modelToolResultExemptions?: readonly string[];
-  /** Base provider Session identity, retained except after a server Tool timeout. */
-  modelSessionId?: string;
-}
-
-export type SessionHarnessRunResult = DriveOutcome | {
-  kind: "released";
-  operationId: string;
-  reason: "slice" | "budget" | "tool-failure" | "approval" | "interaction";
-};
-
-const DEFAULT_MODEL_TURNS_PER_SLICE = 30;
-const DEFAULT_MAX_MODEL_TURNS = 300;
-const DEFAULT_MAX_WRAP_UP_MODEL_TURNS = 2;
-const RECOVERY_MAX_FAILURES = 5;
-const STALL_MAX_FAILURES = 3;
-const SERVER_TOOL_TIMEOUT_MAX_FAILURES = 2;
-const DEFAULT_WRAP_UP_INSTRUCTION =
-  "Finish this request now without using tools. Summarize the completed work and any remaining limitation.";
-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 MAX_TOOL_RETRIES = 3;
-const TURN_FAILURE_CEILING = 8;
-
-function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
-  }
-  if (value !== null && typeof value === "object") {
-    return `{${Object.entries(value)
-      .filter(([, item]) => item !== undefined)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
-      .join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}
-
-function toolCallKey(toolName: string, args: unknown): string {
-  return `${toolName}\0${canonicalJson(args)}`;
-}
-
-function projectToolResultsForModel(
-  messages: readonly AgentMessage[],
-  exemptions: ReadonlySet<string>,
-): AgentMessage[] {
-  let changed = false;
-  const projected = messages.map((message) => {
-    if (
-      message.role !== "toolResult" ||
-      exemptions.has(message.toolName)
-    ) return message;
-    const payload = { content: message.content, details: message.details };
-    const next = projectToolOutputForModel(payload) as typeof payload;
-    if (next === payload) return message;
-    changed = true;
-    return { ...message, content: next.content, details: next.details };
-  });
-  return changed ? projected : [...messages];
+  toolsToActivate?: (name: string, result: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>, isError: boolean) => readonly string[];
+  compaction?: Partial<CompactionPolicy>;
+  streamOptions?: { maxRetries?: number };
+  retry?: Partial<ConversationRetryPolicy>;
+  toolExecution?: "parallel" | "sequential";
+  limits?: SessionHarnessLimits;
+  /** Per-Submission provider error classification and provider Session identity. */
+  recovery?: ModelRecovery;
+  beforeTool?: ToolHooks["beforeTool"];
+  afterResponse?: GenerationHooks["afterResponse"];
 }
 
-function deferred<T>(): {
-  promise: Promise<T>;
-  resolve(value: T): void;
-} {
-  let resolve!: (value: T) => void;
-  const promise = new Promise<T>((done) => {
-    resolve = done;
-  });
-  return { promise, resolve };
+/** Host terminal projection; native Submission records remain authoritative. */
+export interface SessionRunOutcome {
+  status: "completed" | "failed" | "aborted" | "declined";
+  endedAt: number;
+  error?: { code: string; message: string };
 }
-
-function positiveInteger(value: number | undefined, fallback: number): number {
-  const resolved = value ?? fallback;
-  if (!Number.isInteger(resolved) || resolved <= 0) {
-    throw new Error("Harness model turn limits must be positive integers");
-  }
-  return resolved;
+export type SessionHarnessRunResult =
+  | { kind: "settled"; outcome: SessionRunOutcome }
+  | { kind: "released"; operationId: string; reason: "slice" | "approval" | "interaction" };
+export interface SessionRunRequest { operationId: string; prompt?: UserMessage | string; }
+export function submissionOutcome(record: SettledSubmissionRecord): SessionRunOutcome {
+  return {
+    status: record.status === "done" ? "completed" : record.reason === "aborted" ? "aborted" : "failed",
+    endedAt: Date.now(),
+    ...(record.status === "unanswered" ? { error: { code: record.reason, message: typeof record.detail === "string" ? record.detail : record.reason } } : {}),
+  };
 }
 
-/**
- * The only adapter that owns a live Pi AgentHarness for a Session.
- *
- * Submission and Cloudflare lifecycle code may accept, drive, abort, watch, or
- * close through this object. It deliberately does not know how Host config or
- * business repositories are loaded.
- */
-export class SessionHarness<TContext extends object | undefined> {
-  private _openOperation: OpenOperation | null;
-  private readonly modelTurnsPerSlice: number;
-  private readonly maxModelTurns: number;
-  private readonly maxWrapUpModelTurns: number;
-  private readonly modelSessionId: string | undefined;
-  private readonly wrapUpInstruction: string;
-  private readonly configuredToolNames: string[];
-  private readonly modelToolResultExemptions: ReadonlySet<string>;
-  private readonly toolFailures = new Map<string, number>();
-  private totalToolFailures = 0;
-  private toolFailureWrapUp = false;
-  private toolFailureWrapUpAt: number | undefined;
-  private operationStartTip: string | null = null;
+/** The host binds its ports; Pi owns generation, Tool tasks, waiting and recovery. */
+export class SessionHarness {
+  private submission?: Submission;
+  private requestId?: string;
+  private release!: (reason: "approval" | "interaction" | "slice") => void;
   private turnsAtOpen = 0;
-  private wrappingUp = false;
-  private releaseReason:
-    | "slice"
-    | "budget"
-    | "tool-failure"
-    | "approval"
-    | "interaction"
-    | undefined;
-  private readonly releaseRequest = deferred<"approval" | "interaction">();
-  private readonly activeTools = new Set<string>();
-  private readonly toolsIdle = new Set<() => void>();
-
+  private governance = new ToolGovernance();
+  private readonly artifactRefs = new Map<string, ArtifactRef>();
+  private wrapUpStarted = false;
+  /** Completed model turns of the current Submission. */
+  private ownedTurns = 0;
+  private readonly released = new Promise<"approval" | "interaction" | "slice">((resolve) => { this.release = resolve; });
   private constructor(
-    readonly harness: PiAgentHarness<TContext>,
-    readonly lane: AgentLane,
-    openOperation: OpenOperation | null,
-    options: SessionHarnessOptions<TContext>,
-  ) {
-    this._openOperation = openOperation;
-    this.modelTurnsPerSlice = positiveInteger(
-      options.limits?.modelTurnsPerSlice,
-      DEFAULT_MODEL_TURNS_PER_SLICE,
-    );
-    this.maxModelTurns = positiveInteger(
-      options.limits?.maxModelTurns,
-      DEFAULT_MAX_MODEL_TURNS,
-    );
-    this.maxWrapUpModelTurns = positiveInteger(
-      options.limits?.maxWrapUpModelTurns,
-      DEFAULT_MAX_WRAP_UP_MODEL_TURNS,
-    );
-    this.modelSessionId = options.modelSessionId;
-    this.wrapUpInstruction = options.limits?.wrapUpInstruction ??
-      DEFAULT_WRAP_UP_INSTRUCTION;
-    this.configuredToolNames = options.activeToolNames ??
-      (options.tools ?? []).map(({ name }) => name);
-    this.modelToolResultExemptions = new Set(
-      options.modelToolResultExemptions ?? [],
-    );
-  }
+    readonly harness: NativeHarness,
+    public conversation: Conversation,
+    readonly storage: Storage,
+    private readonly options: SessionHarnessOptions,
+  ) {}
 
-  private async operationEntries(context: Context): Promise<Entry[]> {
-    const entries = await this.lane.findEntries({
-      ...(this.operationStartTip === null ? {} : { stopAtId: this.operationStartTip }),
-      type: "message",
-      order: "oldestFirst",
-    }, context);
-    return entries.filter(({ id }) => id !== this.operationStartTip);
+  get openOperation(): { operationId: string } | null {
+    return this.submission && this.requestId ? { operationId: this.requestId } : null;
   }
 
-  private async restoreToolGovernance(context: Context): Promise<void> {
-    this.toolFailures.clear();
-    this.totalToolFailures = 0;
-    this.toolFailureWrapUp = false;
-    this.toolFailureWrapUpAt = undefined;
-    let turns = 0;
-    for (const entry of await this.operationEntries(context)) {
-      if (entry.type !== "message") continue;
-      const message = entry.message;
-      if (message.role === "assistant") {
-        turns += 1;
-        continue;
-      }
-      this.recordCanonicalToolOutcome(entry);
-      if (this.toolFailureWrapUp) this.toolFailureWrapUpAt ??= turns;
+  static async open(options: SessionHarnessOptions, context: Context): Promise<SessionHarness> {
+    const storage = await options.storage;
+    const registry = createRegistry<ToolRegistration<any, any>>();
+    let runtime!: SessionHarness;
+    const exemptions = new Set(options.modelToolResultExemptions ?? []);
+    const extension = defineExtension({
+      name: "springbrand.runtime", tools: options.tools ?? [],
+      sections: [section("system", () => options.systemPrompt, { tag: false })],
+      hooks: [
+        hook(GenerationTask, {
+          beforeRequest: ({ messages }) => {
+            const projected = messages.map((message): Message => {
+              if (message.role !== "toolResult" || exemptions.has(message.toolName)) return message;
+              const next = projectToolOutputForModel({ content: message.content, details: message.details }) as Pick<typeof message, "content" | "details">;
+              return { ...message, ...next };
+            });
+            const manifest = artifactManifestMessage(runtime.artifactRefs);
+            const instruction = runtime.governance.wrapUp
+              ? TOOL_FAILURE_WRAP_UP_INSTRUCTION
+              : runtime.wrapUpStarted ? options.limits?.wrapUpInstruction ?? DEFAULT_WRAP_UP_INSTRUCTION : undefined;
+            return { messages: [
+              ...projected,
+              ...(manifest ? [manifest] : []),
+              ...(instruction ? [{ role: "user" as const, content: instruction, timestamp: 1 }] : []),
+            ] };
+          },
+          afterResponse: async (message, api, hookContext) => {
+            options.recovery?.classify(message);
+            await options.afterResponse?.(message, api, hookContext);
+          },
+          afterTools: async (_assistant, _results, _api, hookContext) => {
+            const entries = await runtime.entries(hookContext);
+            const turns = runtime.ownedTurns = (await runtime.ownedEntries(entries, hookContext)).filter((entry) => entry.kind === "pi.assistant").length;
+            const total = entries.filter((entry) => entry.kind === "pi.assistant").length;
+            const maxTurns = options.limits?.maxModelTurns ?? 300;
+            const wrapUpAt = Math.min(maxTurns, runtime.governance.wrapUpAt ?? Infinity);
+            if (turns >= wrapUpAt + (options.limits?.maxWrapUpModelTurns ?? DEFAULT_MAX_WRAP_UP_MODEL_TURNS)) {
+              // The wrap-up is still calling Tools it no longer has; end the Submission instead of looping.
+              void runtime.conversation.abort(BACKGROUND_CONTEXT).catch(() => {});
+              return;
+            }
+            if (turns >= wrapUpAt && !runtime.wrapUpStarted) {
+              runtime.wrapUpStarted = true;
+              // Tools return on the next Submission's configure; the instruction is per request, never stored.
+              await runtime.conversation.configure({ tools: [] }, hookContext);
+            }
+            if (total - runtime.turnsAtOpen >= (options.limits?.modelTurnsPerSlice ?? 30)) runtime.release("slice");
+          },
+        }),
+        hook(ToolTask, {
+          beforeTool: async (call, api, hookContext) => {
+            // Calls belong to the assistant turn after the last completed Tool round.
+            const block = runtime.governance.admit(call, runtime.ownedTurns + 1);
+            if (block !== undefined) return { block };
+            return options.beforeTool?.(call, api, hookContext);
+          },
+          afterTool: async (call, result) => {
+            runtime.governance.record(call, result.isError === true, runtime.ownedTurns + 1);
+            const ref = artifactRefFromMessage({ role: "toolResult", details: result.details });
+            if (ref) runtime.artifactRefs.set(ref.artifactId, ref);
+            const compiled = new Set(options.tools?.map((tool) => tool.name) ?? []);
+            const names = (options.toolsToActivate?.(call.name, { content: [...result.content ?? []], details: result.details }, result.isError === true) ?? [])
+              .filter((name) => compiled.has(name));
+            return names.length ? { ...result, control: { ...result.control, addTools: names } } : undefined;
+          },
+        }),
+      ],
+    });
+    registry.install(extension);
+    const harness = await Harness.open(storage, {
+      models: options.models, registry,
+      settings: {
+        stream: options.streamOptions, compaction: options.compaction, toolExecution: options.toolExecution,
+        // Read for every retry decision, after afterResponse has classified that response.
+        get retry() {
+          const retry = { maxRetries: 4, ...options.retry };
+          return options.recovery ? { ...retry, enabled: (retry.enabled ?? true) && options.recovery.retryAllowed } : retry;
+        },
+      },
+    }, context);
+    const pointer = await harness.snapshot(RuntimeConversation, context);
+    const conversation = pointer?.id ? await harness.conversation(pointer.id, context) : await harness.root(context);
+    if (!conversation) { await harness.close(context); throw new Error("The persisted Pi conversation is missing"); }
+    if (!pointer?.id) await harness.commit(async (tx) => { (await tx.doc(RuntimeConversation)).id = conversation.id; }, context);
+    runtime = new SessionHarness(harness, conversation, storage, options);
+    runtime.turnsAtOpen = (await runtime.entries(context)).filter((entry) => entry.kind === "pi.assistant").length;
+    const unfinished = (await harness.inspect(context)).submissions.filter((record) => record.conversationId === conversation.id && record.type === "input" && !record.requestId?.startsWith("steer:") && (record.status === "placed" || record.status === "queued"));
+    if (unfinished.length > 1) { await harness.close(context); throw new Error("Multiple host runs are active in one Pi conversation"); }
+    if (unfinished[0]) {
+      runtime.submission = await harness.submission(unfinished[0].id, context);
+      runtime.requestId = unfinished[0].requestId;
     }
+    await runtime.restoreGovernance(context);
+    // Harness.open is passive; install the current Config before anything resumes scheduling.
+    await runtime.applyCurrentConfiguration(context);
+    return runtime;
   }
 
-  private recordCanonicalToolOutcome(entry: Entry): void {
-    if (entry.type !== "message" || entry.message.role !== "toolResult") return;
-    const message = entry.message;
-    if (entry.toolExecution?.status === "executed") {
-      this.recordToolOutcome(message.toolName, entry.toolExecution.args, message.isError);
-    } else if (entry.toolExecution?.status === "blocked" && entry.toolExecution.args !== undefined) {
-      const key = toolCallKey(message.toolName, entry.toolExecution.args);
-      if ((this.toolFailures.get(key) ?? 0) >= MAX_TOOL_RETRIES) this.toolFailureWrapUp = true;
-    }
+  async submissionFor(requestId: string, context: Context) {
+    return this.storage.submissionByRequest(this.conversation.id, requestId, context);
   }
-
-  private recordToolOutcome(toolName: string, args: unknown, isError: boolean): void {
-    const key = toolCallKey(toolName, args);
-    if (!isError) {
-      this.toolFailures.delete(key);
-      return;
-    }
-    this.toolFailures.set(key, (this.toolFailures.get(key) ?? 0) + 1);
-    this.totalToolFailures += 1;
-    if (this.totalToolFailures >= TURN_FAILURE_CEILING) this.toolFailureWrapUp = true;
+  async entries(context: Context = BACKGROUND_CONTEXT): Promise<EntryRecord[]> {
+    const entries: EntryRecord[] = [];
+    let cursor;
+    do {
+      const page = await this.conversation.entries({ order: "ascending" }, 200, cursor, context);
+      entries.push(...page.items); cursor = page.next;
+    } while (cursor);
+    return entries;
   }
-
-  private async shouldRetry(
-    message: SettledAssistantMessage,
-    context: Context,
-    recovery: boolean,
-  ): Promise<boolean> {
-    const stalled = isModelStreamStallMessage(message.errorMessage);
-    const serverToolTimeout = isOpenRouterServerToolTimeout(message);
-    if (!recovery && !stalled && !serverToolTimeout && !isRecoverableAssistantError(message)) return false;
-    const failures = 1 + (await this.operationEntries(context)).filter((entry) =>
-      entry.type === "message" && entry.message.role === "assistant" && entry.message.stopReason === "error"
-    ).length;
-    return failures < (stalled ? STALL_MAX_FAILURES
-      : serverToolTimeout ? SERVER_TOOL_TIMEOUT_MAX_FAILURES : RECOVERY_MAX_FAILURES);
+  /** Entries of the active Submission, from its input onward. */
+  async ownedEntries(entries: readonly EntryRecord[], context: Context): Promise<EntryRecord[]> {
+    const receipt = await this.submission?.status(context);
+    return receipt?.entry ? entries.filter((entry) => entry.id >= receipt.entry!) : [...entries];
   }
-
-  private async shouldFinishRun(context: Context): Promise<boolean> {
-    const wrapUpAt = Math.min(this.maxModelTurns, this.toolFailureWrapUpAt ?? Infinity);
-    return await this.completedModelTurns(context) >= wrapUpAt + this.maxWrapUpModelTurns;
-  }
-
-  get openOperation(): OpenOperation | null {
-    return this._openOperation;
+  private async restoreGovernance(context: Context): Promise<void> {
+    const entries = await this.entries(context);
+    this.artifactRefs.clear();
+    for (const entry of entries) {
+      const message = entry.model?.[0];
+      const ref = message ? artifactRefFromMessage(message) : undefined;
+      if (ref) this.artifactRefs.set(ref.artifactId, ref);
+    }
+    this.governance = new ToolGovernance();
+    this.wrapUpStarted = false;
+    this.ownedTurns = 0;
+    if (!this.submission) return;
+    const owned = await this.ownedEntries(entries, context);
+    this.governance.restore(owned);
+    this.ownedTurns = owned.filter((entry) => entry.kind === "pi.assistant").length;
+    const wrapUpAt = Math.min(this.options.limits?.maxModelTurns ?? 300, this.governance.wrapUpAt ?? Infinity);
+    this.wrapUpStarted = this.ownedTurns >= wrapUpAt;
   }
-
-  static async open<TContext extends object | undefined>(
-    options: SessionHarnessOptions<TContext>,
-    context: Context,
-  ): Promise<SessionHarness<TContext>> {
-    const {
-      limits: _limits,
-      modelToolResultExemptions: _modelToolResultExemptions,
-      modelSessionId: _modelSessionId,
-      ...harnessOptions
-    } = options;
-    let runtime!: SessionHarness<TContext>;
-    const { harness, open } = await AgentHarness.create({
-      ...harnessOptions,
-      retry: options.retry ?? { enabled: true, maxRetries: RECOVERY_MAX_FAILURES - 1, baseDelayMs: 1_000 },
-      recoveryPolicy: async (event, policyContext) =>
-        await runtime.shouldRetry(event.message, policyContext, event.recovery) &&
-        (options.recoveryPolicy === undefined || await options.recoveryPolicy(event, policyContext)),
-      shouldFinishRun: async (event, policyContext) =>
-        await runtime.shouldFinishRun(policyContext) ||
-        (options.shouldFinishRun !== undefined && await options.shouldFinishRun(event, policyContext)),
+  watch(context: Context): Promise<AgentEventStream> { return watchEvents(this.harness, this.conversation.id, context); }
+  requestHumanRelease(reason: "approval" | "interaction"): void { this.release(reason); }
+  async fork(at: EntryId | null, context: Context): Promise<void> {
+    await this.conversation.abort(context);
+    this.submission = undefined;
+    this.requestId = undefined;
+    const created = await this.harness.commit(async (tx) => {
+      const fork = at === null ? await tx.createConversation({ ownership: { kind: "ownerless" } }) : await tx.forkConversation(this.conversation.id, at, { ownership: { kind: "ownerless" } });
+      (await tx.doc(RuntimeConversation)).id = fork.id;
+      return fork;
     }, context);
-    const foreign = open.find((operation) => operation.lane !== "main");
-    if (foreign) {
-      await harness.close(context);
-      throw new Error(`Unexpected open Harness lane: ${foreign.lane}`);
-    }
-    if (open.length > 1) {
-      await harness.close(context);
-      throw new Error("Session has multiple open operations on the main lane");
-    }
-    runtime = new SessionHarness(
-      harness,
-      await harness.lane("main", context),
-      open[0] ?? null,
-      options,
-    );
-    await runtime.install(context);
-    return runtime;
+    this.conversation = (await this.harness.conversation(created.id, context))!;
+    this.turnsAtOpen = (await this.entries(context)).filter((entry) => entry.kind === "pi.assistant").length;
   }
-
-  private async install(context: Context): Promise<void> {
-    if (this._openOperation) {
-      const watch = await this.lane.watch(context);
-      this.operationStartTip = watch.snapshot.operation?.fromTipId ?? null;
-      watch.unsubscribe();
-      await this.restoreToolGovernance(context);
-      this.turnsAtOpen = await this.completedModelTurns(context);
-      if (this.turnsAtOpen >= this.maxModelTurns) {
-        this.wrappingUp = true;
-      }
-      if (this.wrappingUp || this.toolFailureWrapUp) {
-        await this.lane.setActiveTools([], context);
-      }
+  private async applyCurrentConfiguration(context: Context): Promise<void> {
+    const names = new Set(this.options.activeToolNames ?? this.options.tools?.map((tool) => tool.name) ?? []);
+    const previous = await this.harness.snapshot(AgentDoc, this.conversation.id, context);
+    if (Array.isArray(previous?.tools)) {
+      for (const name of previous.tools) if (this.options.onDemandToolNames?.includes(name)) names.add(name);
     }
-    this.harness.hooks.on("before_request", async (event, requestContext) => {
-      if (event.step !== "assistant") return;
-      const resets = (await this.operationEntries(requestContext)).filter((entry) =>
-        entry.type === "message" && entry.message.role === "assistant" && isOpenRouterServerToolTimeout(entry.message)
-      ).length;
-      if (resets > 0) {
-        return { streamOptions: { sessionId: `${this.modelSessionId ?? event.runId}:server-tool-recovery:${resets}` } };
-      }
-      if (this.modelSessionId !== undefined) return { streamOptions: { sessionId: this.modelSessionId } };
-    });
-    this.harness.hooks.on("transform_context", (event) => {
-      const messages = projectToolResultsForModel(
-        event.messages,
-        this.modelToolResultExemptions,
-      );
-      const instruction = this.toolFailureWrapUp
-        ? TOOL_FAILURE_WRAP_UP_INSTRUCTION
-        : this.wrappingUp
-          ? this.wrapUpInstruction
-          : undefined;
-      return {
-        messages: instruction
-          ? [...messages, {
-              role: "user" as const,
-              content: instruction,
-              timestamp: 1,
-            }]
-          : messages,
-      };
-    });
-    this.harness.hooks.on("before_tool", (event) => {
-      if (this.toolFailureWrapUp) {
-        return {
-          block: {
-            reason: "This turn reached its tool failure limit. Stop calling tools now.",
-            terminate: true,
-          },
-        };
-      }
-      if (
-        (this.toolFailures.get(toolCallKey(event.toolName, event.args)) ?? 0) <
-          MAX_TOOL_RETRIES
-      ) return;
-      this.toolFailureWrapUp = true;
-      return {
-        block: {
-          reason:
-            `This exact ${event.toolName} call has already failed ${MAX_TOOL_RETRIES} times — change the input or approach instead of retrying it verbatim.`,
-        },
-      };
-    });
-    this.harness.events.on("entry_added", (event) => {
-      if (event.lane === this.lane.name) this.recordCanonicalToolOutcome(event.entry);
-    });
-    this.harness.events.on("turn_end", async (_event, eventContext) => {
-      const total = await this.completedModelTurns(eventContext);
-      if (this.toolFailureWrapUp && this.toolFailureWrapUpAt === undefined) {
-        this.toolFailureWrapUpAt = total;
-        this.releaseReason = "tool-failure";
-      } else if (this.wrappingUp || this.toolFailureWrapUp) {
-        return;
-      } else if (total >= this.maxModelTurns) {
-        this.releaseReason = "budget";
-      } else if (total - this.turnsAtOpen >= this.modelTurnsPerSlice) {
-        this.releaseReason = "slice";
-      } else {
-        return;
-      }
-      await this.harness.close(eventContext);
-    });
-    this.harness.events.on("tool_start", (event) => {
-      this.activeTools.add(event.toolCallId);
-    });
-    this.harness.events.on("tool_end", (event) => {
-      this.activeTools.delete(event.toolCallId);
-      if (this.activeTools.size === 0) {
-        for (const resolve of this.toolsIdle) resolve();
-        this.toolsIdle.clear();
-      }
-    });
-  }
-
-  /** Ask the active drive to detach after already-started parallel Tools settle. */
-  requestHumanRelease(reason: "approval" | "interaction"): void {
-    this.releaseRequest.resolve(reason);
-  }
-
-  private async waitForToolsToSettle(): Promise<void> {
-    if (this.activeTools.size === 0) return;
-    await new Promise<void>((resolve) => this.toolsIdle.add(resolve));
-  }
-
-  private async completedModelTurns(context: Context): Promise<number> {
-    return (await this.operationEntries(context)).filter((entry) =>
-      entry.type === "message" && entry.message.role === "assistant"
-    ).length;
+    await this.conversation.configure({
+      model: { provider: this.options.model.provider, modelId: this.options.model.id },
+      thinkingLevel: this.options.thinkingLevel ?? "off",
+      tools: this.wrapUpStarted || this.governance.wrapUp
+        ? []
+        : this.options.tools?.filter((tool) => names.has(tool.name)) ?? [],
+      // Wrap-up instructions belong to one Submission and are supplied by the request hook.
+      instructions: null,
+    }, context);
   }
-
-  async run(
-    request: OperationRequest | undefined,
-    context: Context,
-    driveOptions: Omit<DriveOptions, "operationId"> = {},
-  ): Promise<SessionHarnessRunResult> {
-    let operationId = this.openOperation?.operationId;
-    if (request) {
-      if (operationId) {
-        throw new Error(`Harness operation ${operationId} is already open`);
-      }
-      this.operationStartTip = await this.lane.getTipId(context);
-      this.turnsAtOpen = 0;
-      this.wrappingUp = false;
-      this.toolFailures.clear();
-      this.totalToolFailures = 0;
-      this.toolFailureWrapUp = false;
-      this.toolFailureWrapUpAt = undefined;
-      this.releaseReason = undefined;
-      await this.lane.setActiveTools(this.configuredToolNames, context);
-      const admission = await this.lane.accept(request, context);
-      if (!admission.ok) throw admission.error;
-      operationId = admission.value.operationId;
-      this._openOperation = {
-        lane: "main",
-        operationId,
-        kind: admission.value.kind,
-        startedAt: admission.value.startedAt,
-      };
+  async admit(request: SessionRunRequest, context: Context): Promise<void> {
+    if (this.submission && this.requestId !== request.operationId) throw new Error("A native Pi Submission is already active");
+    const existing = await this.submissionFor(request.operationId, context);
+    if (existing) {
+      this.requestId = request.operationId;
+      this.submission = await this.harness.submission(existing.id, context);
+    } else {
+      if (request.prompt === undefined) throw new Error("A new native Pi Submission needs input");
+      this.wrapUpStarted = false;
+      this.governance = new ToolGovernance();
+      await this.applyCurrentConfiguration(context);
+      this.requestId = request.operationId;
+      this.submission = await this.conversation.submit({ type: "input", requestId: request.operationId, content: typeof request.prompt === "string" ? request.prompt : request.prompt.content, whenBusy: "reject" }, context);
     }
-    if (!operationId) throw new Error("No Harness operation to drive");
-    try {
-      const driving = this.lane.drive({ ...driveOptions, operationId }, context);
-      const winner = await Promise.race([
-        driving.then((result) => ({ kind: "drive" as const, result })),
-        this.releaseRequest.promise.then((reason) => ({
-          kind: "release" as const,
-          reason,
-        })),
-      ]);
-      if (winner.kind === "release") {
-        this.releaseReason = winner.reason;
-        await this.waitForToolsToSettle();
-        await this.harness.close(context);
-        await driving.catch(() => undefined);
-        return { kind: "released", operationId, reason: winner.reason };
-      }
-      const result = winner.result;
-      if (!result.ok) throw result.error;
-      if (result.value.kind === "settled") {
-        this._openOperation = null;
-      }
-      return result.value;
-    } catch (error) {
-      if (
-        this.releaseReason && error instanceof Error &&
-        error.name === "HarnessClosed"
-      ) {
-        return { kind: "released", operationId, reason: this.releaseReason };
-      }
-      throw error;
-    }
-  }
-
-  async requestAbort(operationId: string, context: Context): Promise<boolean> {
-    const result = await this.lane.requestAbort(operationId, context);
-    if (!result.ok) throw result.error;
-    return result.value.newlyRequested;
+    await this.restoreGovernance(context);
   }
-
-  close(context: Context): Promise<void> {
-    return this.harness.close(context);
+  async run(request: SessionRunRequest | undefined, context: Context): Promise<SessionHarnessRunResult> {
+    if (request) await this.admit(request, context);
+    if (!this.submission || !this.requestId) throw new Error("No native Pi Submission to resume");
+    const waiting = this.submission.wait(context).then(async (record) => {
+      // One input can be answered while Pi is still working on a later steer.
+      await this.conversation.waitForIdle(context);
+      let cursor;
+      do {
+        const page = await this.storage.scanSubmissions({ conversationId: this.conversation.id, order: "descending" }, 200, cursor, context);
+        for (const next of page.items) {
+          if (next.id <= record.id) return record;
+          if (next.type === "input" && next.requestId?.startsWith("steer:") && (next.status === "done" || next.status === "unanswered")) return next as SettledSubmissionRecord;
+        }
+        cursor = page.next;
+      } while (cursor);
+      return record;
+    });
+    waiting.catch(() => {});
+    const result = await Promise.race([waiting.then((record) => ({ record })), this.released.then((reason) => ({ reason }))]);
+    if ("record" in result) {
+      this.submission = undefined;
+      return { kind: "settled", outcome: submissionOutcome(result.record) };
+    }
+    // A pending approval is before intent. Let already-started parallel effects commit before detaching.
+    const executing = (await this.harness.inspect(context)).tasks.filter(({ record }) => record.kind === "pi.tool" && record.state.status === "running" && (record.state.checkpoint as { phase?: string }).phase === "execute");
+    await Promise.all(executing.map(({ record }) => this.harness.waitForTask(record.id, context)));
+    await this.harness.close(BACKGROUND_CONTEXT);
+    return { kind: "released", operationId: this.requestId, reason: result.reason };
   }
+  async abort(context: Context): Promise<void> { await this.conversation.abort(context); }
+  async close(context: Context): Promise<void> { await this.harness.close(context); }
 }
-
-export function openSessionHarness<TContext extends object | undefined>(
-  options: SessionHarnessOptions<TContext>,
-  context: Context,
-): Promise<SessionHarness<TContext>> {
-  return SessionHarness.open(options, context);
-}
+export const openSessionHarness = SessionHarness.open;