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

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

@@ -7,12 +7,12 @@ import {
   type FiberRecoveryContext,
   type FiberRecoveryResult,
 } from "agents";
-import type { HarnessEvent } from "@earendil-works/pi-agent-core";
+import type { AgentEvent as HarnessEvent } from "@earendil-works/pi-durable";
 import type { UIMessageChunk } from "ai";
 import {
   AGENT_TYPES,
-} from "../../../tools/subagent-types/registry";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+} from "../../../tools/subagent/types/registry";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import type {
   RuntimeProviderPort,
   WorkspacePort,
@@ -30,8 +30,8 @@ import {
   decodeSubagentCompletion,
   emptySubagentUsage,
   encodeSubagentCompletion,
-} from "../../../tools/subagent-runtime";
-import type { RuntimeSubagentUsageMetrics } from "../../../tools/subagent-authority";
+} from "../../../tools/subagent/runtime";
+import type { RuntimeSubagentUsageMetrics } from "../../../tools/subagent/authority";
 import { createCloudflareSubAgentTools } from "./tools";
 
 type RunStatus =
@@ -96,25 +96,27 @@ function stringifyJson(value: unknown): string {
 function progressFor(
   event: HarnessEvent,
 ): Omit<AgentToolProgressSnapshot, "at"> | null {
-  if (event.type === "run_start" || event.type === "run_resume") {
+  if (event.type === "run_start") {
     return { phase: "running", message: "SubAgent started" };
   }
-  if (event.type === "tool_start") {
+  if (event.type === "tool_execution_start") {
     return {
       phase: "tool",
       message: `Running ${event.toolName}`,
     };
   }
-  if (event.type === "tool_update") {
+  if (event.type === "tool_execution_update") {
     return {
       phase: "tool",
       message: `${event.toolName} is still running`,
     };
   }
-  if (event.type === "tool_end") {
+  if (event.type === "tool_execution_end") {
+    const result = event.entry?.model?.[0];
+    const isError = result?.role !== "toolResult" || result.isError;
     return {
-      phase: event.isError ? "tool-error" : "tool",
-      message: event.isError
+      phase: isError ? "tool-error" : "tool",
+      message: isError
         ? `${event.toolName} failed`
         : `${event.toolName} completed`,
     };
@@ -414,14 +416,24 @@ export abstract class CloudflareSubAgent<
         tools,
         signal,
         onEvent: (event) => {
-          if (event.type === "message_end" && event.message.role === "assistant") {
-            addSubagentUsage(usage, event.message.usage);
+          if (event.type === "message_end" && event.entry.model?.[0]?.role === "assistant") {
+            addSubagentUsage(usage, event.entry.model[0].usage);
             this.persistUsage(runId, usage);
           }
           publish(projection!.event(event));
           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,18 +1,14 @@
-import {
-  type AgentHarnessTool,
-  type HarnessEvent,
-  type Session,
-  type StreamFn,
-} from "@earendil-works/pi-agent-core";
+import type { StreamFn } from "@earendil-works/pi-agent-core";
+import type { AgentEvent as HarnessEvent, AgentEventStream, EntryRecord, Storage as Session, ToolRegistration } from "@earendil-works/pi-durable";
 import {
   awaitWithContext,
   BACKGROUND_CONTEXT,
   withAbortSignal,
-} from "@earendil-works/pi-agent-core/harness/context";
+} from "@earendil-works/chord/context";
 import type { Api, AssistantMessage, Model, Models } from "@earendil-works/pi-ai";
 import { z } from "zod";
 import { assembleSubagentPrompt } from "../../../lib/prompt";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import { structuredOutputStream } from "../../../models";
 import {
   openSessionHarness,
@@ -39,11 +35,24 @@ export interface CloudflareSubAgentRun {
   openSession(): Session | Promise<Session>;
   operationId?: string;
   /** Tools compiled by the package's single Harness adapter. */
-  tools?: AgentHarnessTool<object | undefined>[];
+  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 {
@@ -131,9 +140,15 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
     streamOptions: { maxRetries: 0 },
     toolExecution: "parallel",
     compaction: { enabled: false, reserveTokens: 1, keepRecentTokens: 1 },
-  } satisfies Omit<SessionHarnessOptions<object | undefined>, "session">;
-  let runtime: SessionHarness<object | undefined> | undefined;
+  } 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(() => {
@@ -141,61 +156,43 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
     controller.abort(new Error("SubAgent run timed out"));
   }, run.timeoutMs ?? DEFAULT_TIMEOUT_MS);
   try {
-    let settled: Awaited<ReturnType<SessionHarness<object | undefined>["run"]>>;
+    let settled: Awaited<ReturnType<SessionHarness["run"]>>;
     while (true) {
       signal.throwIfAborted();
       if (!runtime) {
         runtime = await openSessionHarness({
           ...options,
-          session: await run.openSession(),
+          storage: await run.openSession(),
         }, context);
         if (runtime.openOperation && runtime.openOperation.operationId !== operationId) {
           throw new Error("SubAgent Session has an unrelated open operation");
         }
-        const harness = runtime.harness;
-        const onEvent = run.onEvent;
-        if (onEvent) {
-          for (const type of ["run_start", "run_resume", "run_end", "turn_start", "message_start", "message_update", "message_end", "tool_start", "tool_update", "tool_end"] as const) {
-            harness.events.on(type, (event) => onEvent(event, signal));
-          }
-        }
-        harness.events.on("tool_end", (event) => {
-          if (event.isError) {
-            toolFailure ??= { name: event.toolName, error: toolErrorText(event.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(
         !runtime.openOperation
           ? {
-              kind: "prompt",
               operationId,
               prompt: taskPrompt(input.data, structuredStream ? undefined : outputSchema),
             }
           : undefined,
         context,
-        { waitForRetry: true, pollDeferred: true },
       );
+      await events?.stop();
+      events = undefined;
       if (result.kind === "released") {
         await runtime.close(BACKGROUND_CONTEXT);
         runtime = undefined;
         continue;
       }
-      if (result.kind === "waiting") {
-        const delay = result.reason === "deferred"
-          ? result.deferred.pollAfterMs ?? 1_000
-          : Math.max(0, result.notBefore - Date.now());
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        try {
-          await awaitWithContext(new Promise<void>((resolve) => {
-            timer = setTimeout(resolve, delay);
-          }), context);
-        } finally {
-          clearTimeout(timer);
-        }
-        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");
@@ -212,14 +209,9 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
     if (toolFailure) {
       throw new Error(`SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`);
     }
-    const assistant = (await runtime.lane.findEntries(
-      { type: "message", order: "newestFirst" },
-      context,
-    )).find((entry) => entry.type === "message" && entry.message.role === "assistant");
-    if (!assistant || assistant.type !== "message" || assistant.message.role !== "assistant") {
-      throw new Error("SubAgent produced no structured output");
-    }
-    const text = textOf(assistant.message);
+    const assistant = [...await runtime.entries(context)].reverse().flatMap((entry) => entry.model ?? []).find((message) => message.role === "assistant");
+    if (assistant?.role !== "assistant") throw new Error("SubAgent produced no structured output");
+    const text = textOf(assistant);
     if (!text) throw new Error("SubAgent produced no structured output");
     let output: unknown;
     try {
@@ -239,9 +231,10 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
   } finally {
     clearTimeout(timeout);
     if (signal.aborted && runtime?.openOperation) {
-      await runtime.requestAbort(operationId, BACKGROUND_CONTEXT).catch(() => undefined);
+      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/adapter/cloudflare/subagent/tools.ts

@@ -1,3 +1,4 @@
+import type { ToolRegistration } from "@earendil-works/pi-durable";
 import {
   DynamicWorkerExecutor,
   resolveProvider,
@@ -9,19 +10,18 @@ import {
 } from "@cloudflare/shell";
 import { stateToolsFromBackend } from "@cloudflare/shell/workers";
 import type {
-  AgentHarnessTool,
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { WorkspacePort } from "../../../config/ports";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import {
   compileHarnessTools,
   type CompileHarnessToolsOptions,
   type PiToolCandidate,
 } from "../../../tools";
-import { workspacePiToolCandidates } from "../../../tools/workspace-sandbox";
+import { workspacePiToolCandidates } from "../../../tools/workspace";
 
 const READONLY_WORKSPACE_TOOLS = new Set([
   "read",
@@ -221,7 +221,7 @@ export function createCloudflareSubAgentTools(options: {
   loader: WorkerLoader;
   outbound: Fetcher;
   settle: NonNullable<CompileHarnessToolsOptions["onSettlement"]>;
-}): AgentHarnessTool<object | undefined>[] {
+}): ToolRegistration<any, any>[] {
   const workspace = workspacePiToolCandidates(options.workspace).filter(
     (candidate) =>
       options.profile === "capable" ||

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -9,16 +9,16 @@ import type {
   RuntimeSubagentPort,
   WorkspacePort,
 } from "../../../config/ports";
-import { decodeSubagentCompletion } from "../../../tools/subagent-runtime";
+import { decodeSubagentCompletion } from "../../../tools/subagent/runtime";
 import type { RuntimeDegradation } from "../../../config/degradation";
 import type { RuntimeMemoryProfile } from "../../../config/profile";
-import { AGENT_TYPES } from "../../../tools/subagent-types/registry";
+import { AGENT_TYPES } from "../../../tools/subagent/types/registry";
 import type { RuntimeAgentConfigContext } from "../../../config/agent-context";
 import {
   createBrowserExecutionFactory,
   createWorkspaceCodeExecutionFactory,
   type RuntimeBrowserBinding,
-} from "../../../tools/core-host";
+} from "../../../tools/codemode/adapter";
 import {
   createCloudflareSandboxAdapter,
   type SandboxAdmission,

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -7,15 +7,13 @@ import type {
 } from "../../../config/ports";
 import type { RuntimeDegradation } from "../../../config/degradation";
 import type { RuntimeMemoryProfile } from "../../../config/profile";
-import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace-versioning";
+import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace/versioning";
 import { schedulePiToolCandidates } from "../../../tools/schedule";
-import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace-revision";
-import {
-  sandboxPiToolCandidates,
-} from "../../../tools/workspace-sandbox";
+import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace/revision";
+import { sandboxPiToolCandidates } from "../../../tools/sandbox";
 import type { RuntimeCodeExecutionFactory } from "../../../config/ports";
 import type { ToolAssemblyResult } from "../../../config/definition";
-import type { PiToolCandidate } from "../../../tools/compiler";
+import type { PiToolCandidate } from "../../../tools/runtime/contracts";
 
 export function assembleUniversalAgentTools(options: {
   hostTools?: readonly PiToolCandidate[];

package/src/adapter/cloudflare/workspace/version-control.ts

@@ -5,7 +5,7 @@ import {
   type WorkspaceRevision,
   type WorkspaceRevisionManifest,
   type WorkspaceVersionPort,
-} from "../../../tools/workspace-versioning";
+} from "../../../tools/workspace/versioning";
 import { createWorkspaceGitFs } from "./git-fs";
 
 const PAGE_SIZE = 256;

package/src/config/agent-context.ts

@@ -8,7 +8,7 @@ import type { RuntimeConfigUpdateResult } from "./runtime-config";
 import type {
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "../tools/temporary-agent/core";
+} from "../tools/subagent/temporary/core";
 
 /**
  * 描述 Agent 寻址路径中的一级父子节点。

package/src/config/assembler.ts

@@ -1,3 +1,4 @@
+import { schedulePiToolCandidates } from "../tools/schedule";
 import type { SkillSource } from "agents/skills";
 import type {
   RuntimeGatewayPort,
@@ -36,10 +37,7 @@ import {
   type PiRuntimeAssembly,
 } from "./assembly-snapshot";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type {
-  PiToolCandidate,
-  ToolExposureMode,
-} from "../tools/compiler";
+import type { PiToolCandidate, ToolExposureMode } from "../tools/runtime/contracts";
 import type {
   AssembleRuntimeSnapshotInput,
   RuntimeSettings,
@@ -50,17 +48,11 @@ import type {
   RuntimeToolSurfacePolicy,
 } from "./definition";
 import type { RuntimeCodeExecutionFactory } from "./ports";
-import {
-  basePiToolCandidates,
-  memoryPiToolCandidate,
-} from "../tools/base";
-import {
-  BROWSER_EXECUTE_TOOL_NAME,
-  browserExecutionPiToolCandidate,
-  codeExecutionPiToolCandidate,
-} from "../tools/core";
+import { basePiToolCandidates } from "../tools/assistant";
+import { memoryPiToolCandidate } from "../tools/assistant/memory";
+import { BROWSER_EXECUTE_TOOL_NAME, browserExecutionPiToolCandidate, codeExecutionPiToolCandidate } from "../tools/codemode";
 import { skillPiToolCandidates } from "../tools/skill";
-import { createWebSearch, WEB_SEARCH_MODEL } from "../tools/web-search";
+import { createWebSearch, WEB_SEARCH_MODEL } from "../tools/web/search";
 import { subagentPiToolCandidates } from "../tools/subagent";
 import { resolvePiModel } from "../models";
 import {
@@ -264,6 +256,16 @@ async function createToolSurface(
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
+          if (candidate.unattendedExecution) {
+            requiredName(
+              candidate.unattendedExecution.capability,
+              `SpringBrand Tool ${name} unattended capability`,
+            );
+            requiredName(
+              candidate.unattendedExecution.operation,
+              `SpringBrand Tool ${name} unattended operation`,
+            );
+          }
           if (tools.has(name)) {
             throw new Error(`Duplicate Runtime SpringBrand Tool: ${name}`);
           }
@@ -294,17 +296,12 @@ async function createToolSurface(
             typeof candidate.tool.execute === "function",
         );
         const codeExecutionCandidates = Object.freeze([...mergeable]);
-        const codeExecutionToolNames = new Set(
-          codeExecutionCandidates.map(({ tool }) => tool.name),
-        );
         const codeExecution = input.codeExecution.create(
           codeExecutionCandidates,
         );
-        const topLevelOnly = directVisible.filter(
-          ({ tool }) => !codeExecutionToolNames.has(tool.name),
-        );
+        const directToolNames = new Set(directVisible.map(({ tool }) => tool.name));
         const routeList = (deferred: boolean) => {
-          const matches = topLevelOnly.filter((candidate) =>
+          const matches = directVisible.filter((candidate) =>
             (defersTool?.(candidate.tool.name) === true) === deferred
           );
           return matches.length > 0
@@ -316,8 +313,9 @@ async function createToolSurface(
         };
         const routeGuidance = [
           "## Tool routing",
-          "Top-level deferred Tools are not callable through `tools.*`. Use Provider Tool Search with their exact name, then call them directly.",
+          "For top-level deferred Tools, use Provider Tool Search with their exact name, then call them directly.",
           "Top-level immediate Tools are already available outside execute; call them directly.",
+          "Only Code Mode Tools listed below are callable inside execute through tools.<name>. Tools marked execute-only are not registered as top-level Tools.",
           "",
           "## Top-level deferred Tools",
           routeList(true),
@@ -325,21 +323,20 @@ async function createToolSurface(
           "## Top-level immediate Tools",
           routeList(false),
           "",
+          "## Code Mode Tools",
+          codeExecutionCandidates.length > 0
+            ? codeExecutionCandidates.map(({ tool }) =>
+                `- \`tools.${tool.name}\` — ${directToolNames.has(tool.name) ? "also available as a top-level Tool" : "execute-only"}`
+              ).join("\n")
+            : "- None.",
+          "",
         ].join("\n");
-        const materializeGuidance = codeExecutionCandidates.some(
-            ({ tool }) => tool.name === "materialize_skill_resource",
-          )
-          ? "Skill resource copying is available only inside execute through " +
-            "`tools.materialize_skill_resource({ name, path, destination })`; " +
-            "no Direct Tool is registered for it. " +
-            "Copy multiple resources sequentially in one execute so durable replay preserves call order.\n\n"
-          : "";
         return Object.freeze({
           candidates: Object.freeze([
             classify(codeExecutionPiToolCandidate({
               ...codeExecution,
               description:
-                routeGuidance + "\n" + materializeGuidance + codeExecution.description,
+                routeGuidance + "\n" + codeExecution.description,
             })),
             ...directVisible.map(classify),
           ]),
@@ -586,6 +583,9 @@ class RuntimeBuilder {
             ? { headers: Object.freeze({ ...endpoint.headers }) }
             : {}),
           models: Object.freeze([...endpoint.models]),
+          ...(endpoint.openRouterProviderPins
+            ? { openRouterProviderPins: Object.freeze({ ...endpoint.openRouterProviderPins }) }
+            : {}),
           ...(endpoint.modelInputModalities
             ? {
                 modelInputModalities: Object.freeze(Object.fromEntries(
@@ -595,6 +595,22 @@ class RuntimeBuilder {
                 )),
               }
             : {}),
+          ...(endpoint.modelMetadata
+            ? {
+                modelMetadata: Object.freeze(Object.fromEntries(
+                  Object.entries(endpoint.modelMetadata).map(([modelId, metadata]) => [
+                    modelId,
+                    Object.freeze({
+                      ...metadata,
+                      cost: Object.freeze({ ...metadata.cost }),
+                      ...(metadata.thinkingLevelMap
+                        ? { thinkingLevelMap: Object.freeze({ ...metadata.thinkingLevelMap }) }
+                        : {}),
+                    }),
+                  ]),
+                )),
+              }
+            : {}),
         }),
       )),
     });
@@ -632,6 +648,7 @@ class RuntimeBuilder {
         : {}),
       hostTools: [
         ...this.hostTools,
+        ...(this.schedule ? schedulePiToolCandidates(this.schedule) : []),
         ...subagentPiToolCandidates(
           this.subagents,
           [...this.enabledSubagents],

package/src/config/assembly-snapshot.ts

@@ -18,7 +18,7 @@ import type {
 import type { RuntimeProviderPort } from "./ports";
 import { assembleSystemPrompt } from "../lib/prompt";
 import { resolvePiModel } from "../models";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 
 /**
  * 收集完动态 Extension/MCP 候选后，一次性生成最终 Tool Surface。

package/src/config/definition.ts

@@ -17,7 +17,7 @@ import type {
 } from "./profile";
 import type { RuntimeExtensionConfig } from "../context/extension/contracts";
 import type { RuntimeDegradation } from "./degradation";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeAgentContext,
   RuntimeAgentPlanningContext,

package/src/config/harness-runtime.ts

@@ -1,5 +1,6 @@
 import {
   createModels,
+  lazyStream,
   type MutableModels,
 } from "@earendil-works/pi-ai";
 import {
@@ -23,6 +24,7 @@ import {
   type PreparePiRuntimeOptions,
   type PreparedPiRuntime,
 } from "./pinning";
+import { refreshModelGuidance } from "./model-guidance";
 
 /**
  * Runtime 通过这个配置入口准备、固定并读取 Harness 的模型、提示和工具输入。
@@ -89,8 +91,10 @@ export class HarnessRuntimeConfig {
     prepared: PreparedPiRuntime,
     pinnedDescriptor: string,
     request: {
-      readonly modelSessionId?: string;
+      readonly modelSessionId?: string | (() => string);
       readonly onGeneration?: PiGenerationLifecycleObserver;
+      readonly assertRequestAllowed?: () => void;
+      readonly onCompactionGeneration?: PiGenerationLifecycleObserver;
     } = {},
   ) {
     const { state, descriptor } = readPinnedPiRuntime(
@@ -100,6 +104,19 @@ export class HarnessRuntimeConfig {
     );
     const pinnedModel = state.snapshot.pi.model;
     let models!: MutableModels;
+    const requestStream = (observer = request.onGeneration) => {
+      const stream = withProviderBoundary(
+        this.models.streamSimple.bind(this.models), request.modelSessionId, observer,
+      );
+      return ((model, context, options) => lazyStream(model, async () => {
+        options?.signal?.throwIfAborted();
+        request.assertRequestAllowed?.();
+        const refreshed = await refreshModelGuidance(state.candidates, context);
+        options?.signal?.throwIfAborted();
+        request.assertRequestAllowed?.();
+        return stream(model, refreshed, options);
+      })) satisfies typeof stream;
+    };
     models = new Proxy(this.models, {
       get: (target, property) => {
         if (property === "getModel") {
@@ -108,15 +125,19 @@ export class HarnessRuntimeConfig {
               ? pinnedModel
               : target.getModel(provider, modelId);
         }
-        if (property === "streamSimple") {
-          return withProviderBoundary(
-            target.streamSimple.bind(target),
-            request.modelSessionId,
-            request.onGeneration,
-          );
-        }
+        if (property === "streamSimple") return requestStream();
         if (property === "completeSimple") {
-          return target.completeSimple.bind(models);
+          const compactionModels = new Proxy(models, {
+            get: (base, key) => {
+              if (key === "streamSimple") return requestStream((event) => {
+                request.onGeneration?.(event);
+                request.onCompactionGeneration?.(event);
+              });
+              const value = Reflect.get(base, key, base);
+              return typeof value === "function" ? value.bind(base) : value;
+            },
+          });
+          return target.completeSimple.bind(compactionModels);
         }
         const value = Reflect.get(target, property, target);
         return typeof value === "function" ? value.bind(target) : value;
@@ -132,10 +153,9 @@ export class HarnessRuntimeConfig {
       platform: state.snapshot.bindings.platform,
       compaction: {
         enabled: true,
-        // Pi compacts above contextWindow - reserveTokens. Keep the same
-        // 15% headroom within the available input budget as the pre-Harness runtime.
-        reserveTokens: Math.ceil(state.snapshot.pi.model.contextWindow -
-          (state.snapshot.pi.model.contextWindow - state.snapshot.pi.model.maxTokens) * 0.85),
+        // Pi compacts above contextWindow - reserveTokens.
+        reserveTokens: state.snapshot.pi.model.contextWindow -
+          compactionThreshold(state.snapshot.pi.model),
         keepRecentTokens: Math.min(
           20_000,
           Math.floor(state.snapshot.pi.model.contextWindow * 0.15),
@@ -180,3 +200,21 @@ export type {
   PreparePiRuntimeOptions,
   PreparedPiRuntime,
 } from "./pinning";
+
+/**
+ * Input tokens above which a Turn compacts its history.
+ *
+ * OpenRouter rejects some requests well below a model's advertised window
+ * (seen from about 393k tokens on DeepSeek V4.1 Flash and 520k-630k on GPT-6
+ * Luna), before any provider is chosen. No model waits past this cap, so long
+ * Chats compact instead of failing.
+ */
+export const MAX_COMPACTION_THRESHOLD_TOKENS = 300_000;
+
+/** 15% headroom within the input budget, capped at {@link MAX_COMPACTION_THRESHOLD_TOKENS}. */
+export function compactionThreshold(model: { contextWindow: number; maxTokens: number }): number {
+  return Math.min(
+    Math.floor((model.contextWindow - model.maxTokens) * 0.85),
+    MAX_COMPACTION_THRESHOLD_TOKENS,
+  );
+}

package/src/config/model-guidance.ts

@@ -0,0 +1,20 @@
+import { getCurrentTools, normalizeContext, type Context, type Tool, type TranscriptContext } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
+
+/** Request-only presentation; Pi remains the source of transcript and active Tool selection. */
+export async function refreshModelGuidance(candidates: readonly PiToolCandidate[], context: Context): Promise<TranscriptContext> {
+  const transcript = normalizeContext(context);
+  const active = new Set(getCurrentTools(transcript.messages).map((tool) => tool.name));
+  const byName = new Map(candidates.map((candidate) => [candidate.tool.name, candidate]));
+  const guidance = new Map(await Promise.all(candidates.filter((candidate) => active.has(candidate.tool.name) && candidate.modelGuidance)
+    .map(async (candidate) => [candidate.tool.name, await candidate.modelGuidance!()] as const)));
+  const messages = transcript.messages.map((message) => message.role !== "system" || !message.toolsAdded ? message : {
+    ...message,
+    toolsAdded: message.toolsAdded.map((tool): Tool => {
+      const candidate = byName.get(tool.name), prompt = guidance.get(tool.name);
+      return { ...tool, ...(candidate?.deferLoading ? { deferLoading: true as const } : {}), ...(prompt ? { description: prompt.description } : {}) };
+    }),
+  });
+  const sections = [...new Set([...guidance.values()].flatMap((value) => value.systemPrompt ? [value.systemPrompt] : []))];
+  return normalizeContext({ messages: sections.length ? [...messages, { role: "system", content: "", sections: { "springbrand.live-services": sections.join("\n\n") }, timestamp: 1 }] : messages });
+}