@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/{runtime-agent-context.ts → config/agent-context.ts}

@@ -3,12 +3,12 @@ import type {
   ChatCapableAgentClass,
   RunAgentToolOptions,
 } from "agents";
-import type { ExecutionLevel } from "./lib/execution-level";
-import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
+import type { ExecutionLevel } from "../lib/execution-level";
+import type { RuntimeConfigUpdateResult } from "./runtime-config";
 import type {
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "./layers/orchestration/temporary-agent/core";
+} from "../tools/subagent/temporary/core";
 
 /**
  * 描述 Agent 寻址路径中的一级父子节点。

package/src/{runtime-assembler.ts → config/assembler.ts}

@@ -1,3 +1,4 @@
+import { schedulePiToolCandidates } from "../tools/schedule";
 import type { SkillSource } from "agents/skills";
 import type {
   RuntimeGatewayPort,
@@ -14,7 +15,7 @@ import type {
   RuntimeBindings,
   RuntimeSkillScriptPolicy,
   WorkspacePort,
-} from "./kernel/bindings";
+} from "./ports";
 import {
   freezeRuntimeProfile,
   type RuntimeDenyPolicy,
@@ -22,24 +23,21 @@ import {
   type RuntimeMemoryProfile,
   type RuntimeProfile,
   type ThinkingEffort,
-} from "./kernel/profile";
-import type { RuntimeExtensionConfig } from "./kernel/extensions";
-import type { RuntimeDegradation } from "./kernel/degradation";
+} from "./profile";
+import type { RuntimeExtensionConfig } from "../context/extension/contracts";
+import type { RuntimeDegradation } from "./degradation";
 import {
   EXECUTION_LEVELS,
   type ExecutionLevel,
-} from "./lib/execution-level";
+} from "../lib/execution-level";
 import {
   createPiRuntimeAssembly,
   type FinalizedPiToolSurface,
   type PiToolSurface,
   type PiRuntimeAssembly,
-} from "./pi/assembly/snapshot";
+} from "./assembly-snapshot";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type {
-  PiToolCandidate,
-  ToolExposureMode,
-} from "./pi/tool/compiler";
+import type { PiToolCandidate, ToolExposureMode } from "../tools/runtime/contracts";
 import type {
   AssembleRuntimeSnapshotInput,
   RuntimeSettings,
@@ -48,36 +46,30 @@ import type {
   RuntimeSkillBodyTransform,
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
-} from "./runtime-definition";
-import type { RuntimeCodeExecutionFactory } from "./kernel/bindings";
-import {
-  basePiToolCandidates,
-  memoryPiToolCandidate,
-} from "./pi/tool/base";
-import {
-  BROWSER_EXECUTE_TOOL_NAME,
-  browserExecutionPiToolCandidate,
-  codeExecutionPiToolCandidate,
-} from "./pi/tool/core";
-import { skillPiToolCandidates } from "./pi/tool/skill";
-import { createWebSearch, WEB_SEARCH_MODEL } from "./pi/tool/web-search";
-import { subagentPiToolCandidates } from "./pi/tool/subagent";
-import { resolvePiModel } from "./pi/runtime-adapter/models";
+} from "./definition";
+import type { RuntimeCodeExecutionFactory } from "./ports";
+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 { subagentPiToolCandidates } from "../tools/subagent";
+import { resolvePiModel } from "../models";
 import {
   normalizeAgentTelemetryBinding,
   type AgentTelemetryBinding,
-} from "./telemetry/contract";
-import { BUILT_IN_RUNTIME_SKILLS } from "./skills";
+} from "../telemetry/contract";
+import { BUILT_IN_RUNTIME_SKILLS } from "../skills";
 
 /** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
-export type { RuntimeDegradation } from "./kernel/degradation";
+export type { RuntimeDegradation } from "./degradation";
 export type {
   RuntimeExtensionContribution,
   RuntimeProfileContribution,
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
-} from "./runtime-definition";
+} from "./definition";
 
 /** Host Planner 与 Runtime Assembler 之间的一次性内部 seam。 */
 export interface RuntimeAssemblyInput {
@@ -127,6 +119,7 @@ export interface RuntimeSnapshot {
  */
 export interface RuntimeCandidate {
   readonly snapshot: RuntimeSnapshot;
+  readonly runtimeKey?: string;
   readonly commitGuards: readonly (() => Promise<void>)[];
   readonly admission?: RuntimeSubmissionAdmissionHook;
   readonly telemetry?: AgentTelemetryBinding;
@@ -263,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}`);
           }
@@ -293,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
@@ -315,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),
@@ -324,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),
           ]),
@@ -631,6 +629,7 @@ class RuntimeBuilder {
         : {}),
       hostTools: [
         ...this.hostTools,
+        ...(this.schedule ? schedulePiToolCandidates(this.schedule) : []),
         ...subagentPiToolCandidates(
           this.subagents,
           [...this.enabledSubagents],

package/src/{kernel/runtime-assembly.ts → config/assembly-projection.ts}

@@ -1,7 +1,7 @@
-import type { RuntimeSnapshot } from "../runtime-assembler";
-import type { PreparedPiRuntime } from "../pi/runtime-adapter";
-import type { RuntimeAssemblyView } from "./runtime-assembly-view";
-export type * from "./runtime-assembly-view";
+import type { RuntimeSnapshot } from "./assembler";
+import type { PreparedPiRuntime } from "./harness-runtime";
+import type { RuntimeAssemblyView } from "./assembly-view";
+export type * from "./assembly-view";
 
 /**
  * Serializable view of the Runtime Snapshot currently installed on a Session facet.

package/src/{pi/assembly/snapshot.ts → config/assembly-snapshot.ts}

@@ -11,14 +11,14 @@ import type {
   RuntimeMcpServer,
   RuntimeProfile,
   ThinkingEffort,
-} from "../../kernel/profile";
+} from "./profile";
 import type {
   RuntimeExtensionConfig,
-} from "../../kernel/extensions";
-import type { RuntimeProviderPort } from "../../kernel/bindings";
-import { assembleSystemPrompt } from "../../lib/prompt";
-import { resolvePiModel } from "../runtime-adapter/models";
-import type { PiToolCandidate } from "../tool/compiler";
+} from "../context/extension/contracts";
+import type { RuntimeProviderPort } from "./ports";
+import { assembleSystemPrompt } from "../lib/prompt";
+import { resolvePiModel } from "../models";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 
 /**
  * 收集完动态 Extension/MCP 候选后，一次性生成最终 Tool Surface。

package/src/{runtime-definition.ts → config/definition.ts}

@@ -1,5 +1,5 @@
 import type { SkillSource } from "agents/skills";
-import type { ExecutionLevel } from "./lib/execution-level";
+import type { ExecutionLevel } from "../lib/execution-level";
 import type {
   RuntimeGatewayPort,
   RuntimeMcpHost,
@@ -8,21 +8,21 @@ import type {
   RuntimeSkillScriptPolicy,
   RuntimeSubmissionAdmissionHook,
   RuntimeTurnEventsPort,
-} from "./kernel/bindings";
+} from "./ports";
 import type {
   RuntimeDenyPolicy,
   RuntimeMcpServer,
   RuntimeMemoryProfile,
   ThinkingEffort,
-} from "./kernel/profile";
-import type { RuntimeExtensionConfig } from "./kernel/extensions";
-import type { RuntimeDegradation } from "./kernel/degradation";
-import type { PiToolCandidate } from "./pi/tool/compiler";
+} from "./profile";
+import type { RuntimeExtensionConfig } from "../context/extension/contracts";
+import type { RuntimeDegradation } from "./degradation";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeAgentContext,
   RuntimeAgentPlanningContext,
-} from "./runtime-agent-context";
-import type { AgentTelemetryBinding } from "./telemetry/contract";
+} from "./agent-context";
+import type { AgentTelemetryBinding } from "../telemetry/contract";
 
 /** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
 export interface ToolSurfaceSelectionPolicy {
@@ -33,10 +33,10 @@ export interface ToolSurfaceSelectionPolicy {
 
 /** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
 export interface RuntimeToolBindings {
-  readonly workspace?: import("./kernel/bindings").WorkspacePort;
-  readonly codeExecution?: import("./kernel/bindings").RuntimeCodeExecutionFactory;
-  readonly memory?: import("./kernel/bindings").RuntimeMemoryPort;
-  readonly subagents?: import("./kernel/bindings").RuntimeSubagentPort;
+  readonly workspace?: import("./ports").WorkspacePort;
+  readonly codeExecution?: import("./ports").RuntimeCodeExecutionFactory;
+  readonly memory?: import("./ports").RuntimeMemoryPort;
+  readonly subagents?: import("./ports").RuntimeSubagentPort;
 }
 
 /** Host 一次装配原子提交的 Tool candidates 与 Runtime 绑定。 */
@@ -75,7 +75,7 @@ export interface RuntimeToolSurfacePolicy extends ToolSurfaceSelectionPolicy {
   readonly denyPolicy?: RuntimeDenyPolicy;
 }
 
-export type { RuntimeAgentContext, RuntimeAssemblyContext } from "./runtime-agent-context";
+export type { RuntimeAgentContext, RuntimeAssemblyContext } from "./agent-context";
 
 export interface ResolvedConnectors {
   readonly servers: readonly RuntimeMcpServer[];

package/src/config/harness-runtime.ts

@@ -0,0 +1,190 @@
+import {
+  createModels,
+  lazyStream,
+  type MutableModels,
+} from "@earendil-works/pi-ai";
+import {
+  configurePiModels,
+  createPiModels,
+  withProviderBoundary,
+  type PiGenerationLifecycleObserver,
+} from "../models";
+export {
+  MODEL_STREAM_STALL_TIMEOUT_MS,
+  modelRequestUrl,
+  readModelStreamStallDetails,
+} from "../models";
+import {
+  pinPiRuntime,
+  preparePiRuntime,
+  readPinnedPiRuntime,
+  readPreparedPiRuntime,
+  type PinPiRuntimeOptions,
+  type PinnedPiRuntime,
+  type PreparePiRuntimeOptions,
+  type PreparedPiRuntime,
+} from "./pinning";
+import { refreshModelGuidance } from "./model-guidance";
+
+/**
+ * Runtime 通过这个配置入口准备、固定并读取 Harness 的模型、提示和工具输入。
+ *
+ * @remarks
+ * Runtime、Pi、Turn、Tool Candidate 和 canonical transcript 等核心术语见包入口 `../../index.ts`。
+ * 本适配器只补充以下局部术语。
+ *
+ * - Prepared Runtime 是配置加载期产生的不透明句柄。
+ *   它包含已加载 Extension、Tool candidate 和快照，但 Runtime 只能读取 revision descriptor 与 degradation。
+ * - revision descriptor 是影响执行行为的已排序 JSON 描述。
+ *   Runtime 会对它取哈希，用来识别当前 Prepared Runtime 的基础版本。
+ * - Pinned Runtime 是 Submission 准入时固定的描述符。
+ *   它在 Prepared Runtime 基础上加入动态 system context、approval mode 和 base revision。
+ * 调用方：`AgentRuntimeKernel` 在配置加载、请求准入与打开 SessionHarness 前调用这些粗粒度能力。
+ *
+ * 执行位置仍由 `SessionHarness` 拥有，消息读写和投影由 `ConversationHistory` 拥有。
+ */
+export class HarnessRuntimeConfig {
+  private readonly owner = {};
+  private readonly models: MutableModels;
+  private readonly managesModels: boolean;
+
+  /**
+   * 创建一个持有独立 Pi 模型目录的 Runtime 适配器。
+   *
+   * @remarks
+   * 调用方：生产 Runtime 使用零参数构造，测试或专用宿主可以注入已经配置好的模型目录。
+   *
+   * 实现理由：适配器只管理自己创建的目录；注入目录的生命周期和配置权仍属于注入方。
+   * 不要让 `activate()` 重配注入目录，否则会覆盖调用方准备的 provider 和模型替身。
+   */
+  constructor(options: { models?: MutableModels } = {}) {
+    this.models = options.models ?? createModels();
+    this.managesModels = !options.models;
+  }
+
+  /**
+   * 加载并预检一份可供后续准入使用的 Prepared Runtime。
+   *
+   * @remarks
+   * 调用方：Runtime 的 `initConfig()` 在取得新快照后调用，再用返回的 revision descriptor 判断是否可以切换配置。
+   *
+   * 实现理由：Extension 加载、Tool candidate 汇总和 Tool 编译预检在配置切换前一次完成。
+   * 返回值绑定当前 Adapter 的 owner，不能交给另一个 Adapter 创建 Turn。
+   */
+  prepare(
+    options: PreparePiRuntimeOptions,
+  ): Promise<PreparedPiRuntime> {
+    if (this.managesModels) {
+      createPiModels(options.snapshot.bindings.provider);
+    }
+    return preparePiRuntime(options, this.owner);
+  }
+
+  hasTool(prepared: PreparedPiRuntime, name: string): boolean {
+    return readPreparedPiRuntime(prepared, this.owner).candidates.some(
+      (candidate) => candidate.tool.name === name,
+    );
+  }
+
+  /** Read the immutable inputs consumed by the Session AgentHarness. */
+  harnessInputs(
+    prepared: PreparedPiRuntime,
+    pinnedDescriptor: string,
+    request: {
+      readonly modelSessionId?: string;
+      readonly onGeneration?: PiGenerationLifecycleObserver;
+    } = {},
+  ) {
+    const { state, descriptor } = readPinnedPiRuntime(
+      prepared,
+      this.owner,
+      pinnedDescriptor,
+    );
+    const pinnedModel = state.snapshot.pi.model;
+    let models!: MutableModels;
+    models = new Proxy(this.models, {
+      get: (target, property) => {
+        if (property === "getModel") {
+          return (provider: string, modelId: string) =>
+            provider === pinnedModel.provider && modelId === pinnedModel.id
+              ? pinnedModel
+              : target.getModel(provider, modelId);
+        }
+        if (property === "streamSimple") {
+          const stream = withProviderBoundary(
+            target.streamSimple.bind(target),
+            request.modelSessionId,
+            request.onGeneration,
+          );
+          return ((model, context, options) => lazyStream(model, async () => {
+            options?.signal?.throwIfAborted();
+            const refreshed = await refreshModelGuidance(state.candidates, context);
+            options?.signal?.throwIfAborted();
+            return stream(model, refreshed, options);
+          })) satisfies typeof stream;
+        }
+        if (property === "completeSimple") {
+          return target.completeSimple.bind(models);
+        }
+        const value = Reflect.get(target, property, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+    return {
+      models,
+      model: state.snapshot.pi.model,
+      thinkingLevel: state.snapshot.pi.thinkingLevel,
+      systemPrompt: descriptor.systemPrompt,
+      candidates: state.candidates,
+      workspace: state.snapshot.bindings.workspace,
+      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),
+        keepRecentTokens: Math.min(
+          20_000,
+          Math.floor(state.snapshot.pi.model.contextWindow * 0.15),
+        ),
+      },
+    } as const;
+  }
+
+  /**
+   * 用已经通过加载检查的快照启用当前部署声明的模型目录。
+   *
+   * @remarks
+   * 调用方：Runtime 的 `initConfig()` 在 Prepared Runtime 和 revision 检查成功后、发布新快照前调用。
+   *
+   * 实现理由：`prepare()` 已校验所有 endpoint 模型，这里只把同一份部署目录切换到长期 Models 实例。
+   * 注入模型目录时跳过此步骤，以保留调用方对目录的配置权。
+   */
+  activate(snapshot: PreparePiRuntimeOptions["snapshot"]): void {
+    if (this.managesModels) {
+      configurePiModels(this.models, snapshot.bindings.provider);
+    }
+  }
+
+  /**
+   * 在接受 Submission 前固定本次执行使用的动态上下文和审批模式。
+   *
+   * @remarks
+   * 调用方：Runtime 的准入流程为每个新 Submission 调用，并把 descriptor 与其哈希一起持久化。
+   *
+   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，所以把准入时的 Turn 字段保存在 descriptor 中。
+   * 不要把 pin 推迟到 Turn 启动后，否则已持久化的 Submission 将失去可验证的执行基线。
+   */
+  pin(options: PinPiRuntimeOptions): Promise<PinnedPiRuntime> {
+    return pinPiRuntime(options, this.owner);
+  }
+
+}
+
+export type {
+  PinPiRuntimeOptions,
+  PinnedPiRuntime,
+  PreparePiRuntimeOptions,
+  PreparedPiRuntime,
+} from "./pinning";

package/src/config/index.ts

@@ -0,0 +1,14 @@
+export * from "./activation";
+export * from "./agent-context";
+export * from "./assembler";
+export * from "./assembly-projection";
+export * from "./assembly-snapshot";
+export * from "./assembly-view";
+export * from "./definition";
+export * from "./degradation";
+export * from "./harness-runtime";
+export * from "./pinning";
+export * from "./ports";
+export * from "./profile";
+export * from "./runtime-config";
+export * from "./runtime-load";

package/src/config/model-guidance.ts

@@ -0,0 +1,21 @@
+import type { Context } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
+
+/** Only descriptions and guidance may vary inside a pinned Submission. */
+export async function refreshModelGuidance(
+  candidates: readonly PiToolCandidate[],
+  context: Context,
+): Promise<Context> {
+  const guidance = new Map(await Promise.all(candidates
+    .filter(candidate => candidate.modelGuidance && context.tools?.some(tool => tool.name === candidate.tool.name))
+    .map(async candidate => [candidate.tool.name, await candidate.modelGuidance!()] as const)));
+  if (!guidance.size) return context;
+  return {
+    ...context,
+    systemPrompt: [context.systemPrompt, ...new Set([...guidance.values()].map(item => item.systemPrompt).filter(Boolean))].filter(Boolean).join("\n\n"),
+    tools: context.tools?.map(tool => {
+      const prompt = guidance.get(tool.name);
+      return prompt ? { ...tool, description: prompt.description } : tool;
+    }),
+  };
+}