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

package/src/config/ports.ts

@@ -1,16 +1,17 @@
+export type { RuntimeSchedulePreparation } from "../submission/contracts";
 import type { RuntimeModelInputModality } from "./profile";
 import type { SkillSource } from "agents/skills";
-import type { ScheduleSpec } from "../submission/contracts";
+import type { ScheduleSpec, RuntimeSchedulePreparation } from "../submission/contracts";
 import type { RuntimeActivityProjection } from "../conversation/state";
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
   RuntimeSubagentUsageMetrics,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 export type { RuntimeModelInputModality } from "./profile";
 export type {
   RuntimeEventConfirmation,
@@ -21,7 +22,7 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 
 // #region Workspace 端口
 
@@ -669,16 +670,25 @@ export interface RuntimeScheduleAgentSummary {
  * 让 Runtime 通过 Host 管理当前用户的定时任务。
  *
  * @remarks
- * Schedule Plugin 在装配时把它交给基础工具，模型在用户要求创建、查询或取消时调用。
+ * Host 提供准备与提交操作；Runtime 在现有持久化审批中固定候选并等待用户确认。
  *
- * 任务归属和持久化留在 Host，Runtime 只传递 `ScheduleSpec` 和窄结果。
+ * 任务事实、候选版本、授权检查和保存幂等由 Host 持有，不存放凭据。
  */
+export interface RuntimeScheduleConfirmationPort {
+  /** Read-only preparation; bind the full candidate and authorization to this stable intent. */
+  prepare(request: RuntimeScheduleUpdate & { intentId: string; id?: string }): Promise<RuntimeSchedulePreparation>;
+  /** Atomically check candidate/version, live authorization and quotas. Replay must return the same task. */
+  commit(prepared: RuntimeSchedulePreparation, context: { intentId: string; signal: AbortSignal }): Promise<{ id: string }>;
+}
+
 export interface RuntimeSchedulePort {
+  /** Required for chat creation/editing. Legacy management callers retain their CRUD contract. */
+  confirmation?: RuntimeScheduleConfirmationPort;
   /**
    * 创建一条定时任务并返回它的 ID。
    *
    * @remarks
-   * `schedule` 工具在把用户的时间与提示词组成 `ScheduleSpec` 后调用。
+   * 保留给既有宿主管理调用者；聊天 `schedule` 只经 confirmation.commit 保存。
    *
    * Host 在该边界内绑定用户与会话，Runtime 不携带业务归属 ID。
    */
@@ -940,6 +950,8 @@ export interface RuntimeBrowserPort {
 export type RuntimeModelProtocol =
   | "openai-chat"
   | "openrouter-messages"
+  | "openrouter-chat"
+  | "openrouter-responses"
   | "anthropic-messages"
   | "google-generative-ai"
   | "openai-codex-responses";
@@ -953,6 +965,31 @@ export type RuntimeModelProtocol =
  *
  * 凭据只留在 Port 对象，不进入 `RuntimeProfile` 或持久状态；术语见 `../index.ts`。
  */
+export type RuntimeModelThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+export interface RuntimeModelMetadata {
+  readonly name: string;
+  readonly reasoning: boolean;
+  readonly contextWindow: number;
+  readonly maxTokens: number;
+  readonly cost: Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  }>;
+  readonly thinkingLevelMap?: Readonly<
+    Partial<Record<RuntimeModelThinkingLevel, string | null>>
+  >;
+}
+
 export interface RuntimeModelEndpoint {
   protocol: RuntimeModelProtocol;
   /** Resolved credential; never enters RuntimeProfile or persisted state. */
@@ -967,6 +1004,9 @@ export interface RuntimeModelEndpoint {
   >;
   /** OpenRouter upstream provider pins keyed by model ID; pinned requests never fall back. */
   openRouterProviderPins?: Readonly<Record<string, string>>;
+  /** OpenRouter provider ordering; omitted keeps OpenRouter's default routing. */
+  openRouterProviderSort?: "price" | "throughput" | "latency";
+  modelMetadata?: Readonly<Record<string, RuntimeModelMetadata>>;
 }
 
 /**
@@ -1020,6 +1060,16 @@ export interface RuntimePlatformPort {
     requiredExecutionLevel: ExecutionLevel;
     signal: AbortSignal;
   }): Promise<void>;
+  /**
+   * Match a pinned scheduled-task grant against the concrete Tool operation
+   * and recheck the Host-owned live account authorization.
+   *
+   * This callback must fail closed by throwing a user-safe, specific reason.
+   * It is called before dispatch and again at the effect boundary so a grant
+   * revocation cannot be hidden by an earlier decision.
+   */
+  /** @deprecated Scheduled execution is authorized locally by execution level. */
+  authorizeUnattendedExecution?(request: unknown): Promise<void>;
 }
 
 /**

package/src/config/{pinning.ts → prepared-runtime.ts}

@@ -1,4 +1,3 @@
-import { sha256Hex } from "../lib/artifacts";
 import type {
   RuntimeBindings,
   RuntimeGatewaySession,
@@ -9,7 +8,6 @@ import type {
   RuntimeExtensionPermissions,
 } from "../context/extension/contracts";
 import type { RuntimeProfile } from "./profile";
-import type { ExecutionLevel } from "../lib/execution-level";
 import type { RuntimeSnapshot } from "./assembler";
 import type { FinalizedPiToolSurface, PiRuntimeAssembly } from "../context";
 import {
@@ -28,29 +26,8 @@ import {
   type PiToolCandidate,
 } from "../tools";
 
-export interface RuntimeAssemblyPin {
-  readonly revision: string;
-  readonly descriptor: string;
-}
-
-/** A saved pin is reusable only with its original Runtime key and intact descriptor. */
-export async function validateRuntimeAssemblyPin(
-  runtimeKey: string,
-  pin: RuntimeAssemblyPin,
-): Promise<boolean> {
-  if (!runtimeKey) {
-    throw new Error("Cannot safely recover a pinned Submission without its original Runtime key");
-  }
-  if (!pin.revision && !pin.descriptor) return false;
-  if (!pin.revision || !pin.descriptor) throw new Error("Submission assembly pin is incomplete");
-  if (pin.revision !== await sha256Hex(pin.descriptor)) {
-    throw new Error("Pinned Runtime assembly descriptor is invalid");
-  }
-  return true;
-}
-
 /**
- * 本文件负责准备 Pi 的扩展与工具，并为每次提交固定可恢复的运行描述。
+ * 本文件负责准备当前 Pi 的扩展、工具与系统上下文。
  *
  * @remarks
  * 核心术语见本目录入口 `./index.ts`，这里不重复定义。
@@ -93,8 +70,8 @@ interface PreparePiAssemblyOptions {
   ) => Fetcher;
 }
 
-// 暴露后续准备和固定阶段会读取的扩展装配结果。
-// preparePiRuntime 读取工具与降级，pinPiRuntime 读取上下文贡献。
+// 暴露后续准备和执行阶段会读取的扩展装配结果。
+// preparePiRuntime 读取工具与降级，assembleCurrentPiContext 读取上下文贡献。
 // 访问器直接代理扩展装配，避免维护会漂移的副本。
 interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
@@ -133,10 +110,10 @@ export interface PreparePiRuntimeOptions {
 }
 
 /**
- * 表示已经准备好、但尚未固定到某次提交的 Pi 配置。
+ * 表示已准备好供当前执行使用的 Pi 配置。
  *
  * @remarks
- * Runtime 在配置完成后保存这个句柄，并在提交准入或创建 Turn 时传回。
+ * Runtime 在配置完成后保存这个句柄，并在创建 Turn 时传回。
  *
  * 公开形状只给出版本描述和加载降级，调用方不会直接拿到可变的装配状态。
  */
@@ -147,21 +124,25 @@ export interface PreparedPiRuntime {
 }
 
 /**
- * 提供把一次提交固定到当前 Runtime 所需的值。
+ * 当前执行切片读取系统上下文所需的值。
  *
  * @remarks
- * Runtime 在写入提交前的准入阶段把它交给 `HarnessRuntimeConfig.pin`。
+ * Runtime 在打开或恢复 Harness 前把它交给 `HarnessRuntimeConfig.harnessInputs`。
  *
  * 扩展没有可读上下文时不需要读取函数，所以该端口保持可选。
  */
-export interface PinPiRuntimeOptions {
+export interface CurrentPiContextOptions {
   readonly prepared: PreparedPiRuntime;
-  readonly baseRevision: string;
   /**
-   * 读取一个扩展要写入固定系统提示词的上下文。
+   * Whether this Submission may inherit automatic hot and cold Memory context.
+   * Scheduled task input is intentionally isolated from those sources.
+   */
+  readonly includeMemory?: boolean;
+  /**
+   * 读取一个扩展对当前系统提示词的上下文贡献。
    *
    * @remarks
-   * pinPiRuntime 在准入阶段为已加载扩展声明的上下文贡献调用它。
+   * 每次装配 Harness 输入时为已加载扩展读取当前上下文。
    *
    * 本模块不持有扩展上下文存储，所以读取端口必须留在 Host。
    */
@@ -170,40 +151,6 @@ export interface PinPiRuntimeOptions {
   ) => Promise<string | null>;
 }
 
-/**
- * 返回已经固定到一次提交的描述和上下文降级。
- *
- * @remarks
- * Runtime 在准入时持久化描述，并在创建 Turn 时传回。
- *
- * 固定这些值可让恢复继续使用当时已经准入的配置。
- */
-export interface PinnedPiRuntime {
-  readonly descriptor: string;
-  readonly degradations: readonly RuntimeDegradation[];
-}
-
-/**
- * 描述一条已存提交可以恢复到哪份 Pi 配置。
- *
- * @remarks
- * `HarnessRuntimeConfig.harnessInputs` 在打开或恢复 operation 前读取这个 JSON 结构。
- *
- * 基础版本作为准入时元数据保留，创建 Turn 时不与当前 Runtime 比较。
- */
-export interface PinnedPiRuntimeDescriptor {
-  readonly version: 1;
-  readonly baseRevision: string;
-  readonly model: string;
-  readonly provider: string;
-  readonly thinking: RuntimeSnapshot["pi"]["thinkingLevel"];
-  readonly systemPrompt: string;
-  readonly executionLevel: ExecutionLevel;
-  readonly deny: readonly string[];
-  readonly tools: readonly ReturnType<typeof describeTools>[number][];
-  readonly [key: string]: unknown;
-}
-
 /**
  * 保存创建 Pi Turn 所需的内部准备结果。
  *
@@ -249,9 +196,20 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       description: candidate.tool.description ?? candidate.tool.label,
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
+      ...(candidate.confirmation ? { confirmation: true } : {}),
       ...(candidate.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
         : {}),
+      ...(candidate.unattendedExecution
+        ? {
+            unattendedExecution: {
+              capability: candidate.unattendedExecution.capability,
+              operation: candidate.unattendedExecution.operation,
+              objectConstrained:
+                candidate.unattendedExecution.objectForInput !== undefined,
+            },
+          }
+        : {}),
       ...(candidate.deferLoading ? { deferLoading: true } : {}),
       ...(candidate.source ? { source: candidate.source } : {}),
       retry: piToolRetryPolicy(candidate),
@@ -267,10 +225,25 @@ function describeRuntime(
   candidates: readonly PiToolCandidate[],
   loadedExtensions: readonly PiLoadedExtension[],
 ): string {
+  const model = snapshot.pi.model;
+  const openRouterRouting = model.compat && "openRouterRouting" in model.compat
+    ? model.compat.openRouterRouting
+    : undefined;
   return JSON.stringify({
     version: 1,
-    model: snapshot.pi.model.id,
-    provider: snapshot.pi.model.provider,
+    model: model.id,
+    provider: model.provider,
+    modelConfig: {
+      api: model.api,
+      name: model.name,
+      reasoning: model.reasoning,
+      input: model.input,
+      contextWindow: model.contextWindow,
+      maxTokens: model.maxTokens,
+      cost: model.cost,
+      ...(model.thinkingLevelMap ? { thinkingLevelMap: model.thinkingLevelMap } : {}),
+      ...(openRouterRouting ? { openRouterRouting } : {}),
+    },
     thinking: snapshot.pi.thinkingLevel,
     systemPrompt: snapshot.pi.systemPrompt,
     executionLevel: snapshot.profile.executionLevel,
@@ -314,7 +287,7 @@ class PreparedRuntime implements PreparedPiRuntime {
   ) {}
 
   // 在调用方证明适配器身份后返回内部准备状态。
-  // readPreparedPiRuntime 在固定配置或创建 Turn 前调用它。
+  // readPreparedPiRuntime 在创建 Turn 前调用它。
   // 公开接口没有可信的来源字段，所以这里必须比较对象身份。
   read(owner: object): PreparedPiRuntimeState {
     if (owner !== this.owner) {
@@ -330,7 +303,7 @@ class PreparedRuntime implements PreparedPiRuntime {
  * 为创建它的 HarnessRuntimeConfig 打开准备句柄。
  *
  * @remarks
- * 固定配置和创建 Turn 都会先调用它，再读取快照、装配结果或工具候选。
+ * 创建 Turn 前调用它，读取快照、装配结果或工具候选。
  *
  * 具体类检查与 owner 检查一起拒绝伪造句柄和跨适配器复用。
  */
@@ -344,42 +317,6 @@ export function readPreparedPiRuntime(
   return prepared.read(owner);
 }
 
-/**
- * 读取已存的固定描述。
- *
- * @remarks
- * `HarnessRuntimeConfig.harnessInputs` 在新建或恢复 Pi operation 前调用它。
- *
- * Prepared Runtime 提供当前执行能力，descriptor 仅保留 Submission 固定的 Turn 字段。
- */
-export function readPinnedPiRuntime(
-  prepared: PreparedPiRuntime,
-  owner: object,
-  descriptorBody: string,
-): {
-  readonly state: PreparedPiRuntimeState;
-  readonly descriptor: PinnedPiRuntimeDescriptor;
-} {
-  const state = readPreparedPiRuntime(prepared, owner);
-  let value: unknown;
-  try {
-    value = JSON.parse(descriptorBody);
-  } catch {
-    throw new Error("Pinned Runtime assembly descriptor is invalid");
-  }
-  if (!value || typeof value !== "object") {
-    throw new Error("Pinned Runtime assembly descriptor is invalid");
-  }
-  const descriptor = value as PinnedPiRuntimeDescriptor;
-  if (
-    descriptor.version !== 1 ||
-    typeof descriptor.systemPrompt !== "string"
-  ) {
-    throw new Error("Pinned Runtime assembly descriptor is invalid");
-  }
-  return { state, descriptor };
-}
-
 // #endregion
 
 // #region 扩展与工具装配
@@ -431,7 +368,7 @@ async function preparePiAssembly(
 
 // #endregion
 
-// #region Runtime 准备与提交固定
+// #region Runtime 准备与当前上下文
 
 /**
  * 为一份已校验的 Runtime 快照准备扩展和工具状态。
@@ -468,34 +405,33 @@ export async function preparePiRuntime(
 }
 
 /**
- * 把请求时的上下文和执行档位固定到一次提交的描述中。
+ * 从当前 Runtime 装配模型要用的系统上下文。
  *
  * @remarks
- * Runtime 在持久化提交并启动 Turn 前的准入阶段调用它。
+ * Runtime 每次打开或恢复 Harness 前调用它。
  *
- * 此时重建上下文可避免把动态记忆和扩展上下文写进 Pi 消息，同时让恢复继续使用已准入的结果。
+ * 重新读取动态记忆和扩展上下文，不从旧 Submission 描述恢复配置。
  */
-export async function pinPiRuntime(
-  options: PinPiRuntimeOptions,
+export async function assembleCurrentPiContext(
+  options: CurrentPiContextOptions,
   owner: object,
-): Promise<PinnedPiRuntime> {
+): Promise<{ systemPrompt: string; degradations: readonly RuntimeDegradation[] }> {
   const state = readPreparedPiRuntime(options.prepared, owner);
   const { snapshot, assembly } = state;
+  const includeMemory = options.includeMemory !== false;
   const context = await assemblePiSystemContext({
     baseSystemPrompt: snapshot.pi.systemPrompt,
-    memory: snapshot.profile.memory,
-    memoryPort: snapshot.bindings.memory,
-    workspace: snapshot.bindings.workspace,
+    memory: includeMemory
+      ? snapshot.profile.memory
+      : { ...snapshot.profile.memory, enabled: false },
+    memoryPort: includeMemory ? snapshot.bindings.memory : undefined,
+    workspace: includeMemory ? snapshot.bindings.workspace : undefined,
     skills: snapshot.bindings.skills.sources,
     extensionContexts: assembly.context,
     readExtensionContext: options.readExtensionContext,
   });
   return Object.freeze({
-    descriptor: JSON.stringify({
-      ...JSON.parse(options.prepared.revisionDescriptor),
-      systemPrompt: context.systemPrompt,
-      baseRevision: options.baseRevision,
-    }),
+    systemPrompt: context.systemPrompt,
     degradations: context.degradations,
   });
 }

package/src/config/public-contracts.ts

@@ -17,7 +17,7 @@ export * from "../conversation/message";
 export * from "../submission/contracts";
 export * from "../conversation/state";
 export * from "../lib/execution-level";
-export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace-versioning";
+export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace/versioning";
 export type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -27,4 +27,4 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";

package/src/config/runtime-config.ts

@@ -1,4 +1,5 @@
 export interface RuntimeConfigUpdateResult<Change> {
   readonly change: Change;
-  readonly runtime: "unchanged" | "reloaded" | "reload-failed";
+  /** Deferred changes are persisted but activated at the next execution slice. */
+  readonly runtime: "unchanged" | "reloaded" | "deferred" | "reload-failed";
 }

package/src/context/assembly.ts

@@ -1,4 +1,4 @@
-import { estimateStringTokens } from "agents/experimental/memory/utils";
+import { estimateStringTokens } from "../lib/token-estimate";
 import type { RuntimeMemoryPort } from "../config/ports";
 import type { RuntimeDegradation } from "../config/degradation";
 import type { RuntimeMemoryProfile } from "../config/profile";

package/src/context/extension/assembly.ts

@@ -12,8 +12,8 @@ import type {
 import type { RuntimeDegradation } from "../../config/degradation";
 import { withRuntimeLoadTimeout } from "../../config/runtime-load";
 import { sanitizeExtensionName } from "../../lib/extension-name";
-import type { PiToolCandidate } from "../../tools/compiler";
-import { createPiDeclaredToolCandidate } from "../../tools/declared";
+import type { PiToolCandidate } from "../../tools/runtime/contracts";
+import { createPiDeclaredToolCandidate } from "../../tools/adapters/declared";
 
 export interface PiExtensionContextContribution {
   readonly extensionName: string;

package/src/context/memory/budget/gate.ts

@@ -1,4 +1,5 @@
 import {
+  artifactId,
   type ArtifactRef,
   serializeOutput,
   sha256Hex,
@@ -29,7 +30,7 @@ import {
 /**
  * 持久化单个字符串叶子的上限。
  *
- * MUST ≥ 单页 read 的上限（见 `workspace-sandbox.ts` 的 `READ_PAGE_MAX_CHARS`），
+ * MUST ≥ 单页 read 的上限（见 `tools/workspace/index.ts` 的 `READ_PAGE_MAX_CHARS`），
  * 否则持久记录会比模型当轮看到的内容还少，会话恢复后出现凭空缺页。
  */
 export const STORAGE_LEAF_MAX_CHARS = 64 * 1024;
@@ -161,11 +162,26 @@ export async function spillDurableToolOutput(
       text,
       ext === "json" ? "application/json" : "text/plain",
     );
+    if (!options.workspace.stat || !options.workspace.readFileBytes) {
+      throw new Error("Workspace artifact verification is unavailable");
+    }
+    const stat = await options.workspace.stat(path);
+    const expectedBytes = new TextEncoder().encode(text).byteLength;
+    if (!stat || stat.type !== "file" || stat.size !== expectedBytes) {
+      throw new Error("Workspace artifact failed size verification");
+    }
+    const stored = await options.workspace.readFileBytes(path);
+    if (!stored || new TextDecoder().decode(stored) !== text) {
+      throw new Error("Workspace artifact failed content verification");
+    }
     return {
       kind: "artifact_ref",
+      artifactId: artifactId(hash),
       path,
-      bytes: new TextEncoder().encode(text).byteLength,
-      hash: hash.slice(0, 16),
+      bytes: expectedBytes,
+      hash,
+      workspaceRevision: stat.contentVersion ?? `${stat.updatedAt}:${stat.size}`,
+      availability: "available",
       preview: text.slice(0, PREVIEW_CHARS),
       // 出口指令必须是可执行的：只说“去 read 这个路径”会诱导模型整读，而整读一个
       // 刚刚因为过大被外置的文件毫无意义。这里明确要求分页，并告知 read 会返回