@springbrand/agent-runtime 0.2.0-alpha.43 → 0.2.0-alpha.45

package/src/pi/runtime-adapter/index.ts

@@ -2,13 +2,13 @@ import {
   PreparedPiTurnAdapter,
   type CreatePreparedPiTurnOptions,
 } from "./execution";
-export { RetryableModelError } from "./execution";
+export { ContextOverflowError, RetryableModelError } from "./execution";
 import {
   uiUserMessageToPi,
 } from "../message";
 import type { UIMessage } from "ai";
 import { createModels, type MutableModels } from "@earendil-works/pi-ai";
-import { configurePiModels, createPiModels, resolvePiApiKey } from "./models";
+import { configurePiModels, createPiModels } from "./models";
 export {
   MODEL_STREAM_STALL_TIMEOUT_MS,
   modelRequestUrl,
@@ -120,12 +120,6 @@ export class PiRuntimeAdapter {
     return uiUserMessageToPi(input, privateContext);
   }
 
-  resolveApiKey(
-    ...args: Parameters<typeof resolvePiApiKey>
-  ): ReturnType<typeof resolvePiApiKey> {
-    return resolvePiApiKey(...args);
-  }
-
   /**
    * 加载并预检一份可供后续准入使用的 Prepared Runtime。
    *

package/src/pi/runtime-adapter/models.ts

@@ -111,6 +111,38 @@ export type PiGenerationLifecycleObserver = (
   event: PiGenerationLifecycleEvent,
 ) => void;
 
+export function structuredOutputStream(
+  streamFn: StreamFn,
+  model: Model<Api>,
+  schema: Record<string, unknown>,
+): StreamFn | undefined {
+  if (
+    model.api !== "anthropic-messages" ||
+    !model.provider.startsWith("model-api-openrouter-messages-")
+  ) return undefined;
+
+  return (activeModel, context, options) =>
+    streamFn(activeModel, context, {
+      ...options,
+      onPayload: async (payload, payloadModel) => {
+        const value = await options?.onPayload?.(payload, payloadModel) ?? payload;
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          throw new Error("Structured model payload must be an object");
+        }
+        const current = (value as Record<string, unknown>).output_config;
+        return {
+          ...value,
+          output_config: {
+            ...(current && typeof current === "object" && !Array.isArray(current)
+              ? current
+              : {}),
+            format: { type: "json_schema", schema },
+          },
+        };
+      },
+    });
+}
+
 export function isModelStreamStallMessage(message?: string): message is string {
   return message === MODEL_STREAM_STALL_MESSAGE ||
     message?.startsWith(MODEL_STREAM_STALL_DETAILS_PREFIX) === true;
@@ -534,8 +566,8 @@ export function withProviderRetry(
 }
 
 // 找出部署把这个模型放在哪个端点，并保留该端点在配置中的位置。
-// resolvePiModel 和 resolvePiApiKey 在组装运行快照、发起模型请求前调用它，调用方只需传部署配置和 modelId。
-// 这里复用同一条查找路径，避免模型与密钥落到不同端点；同一 modelId 若配置多次会取第一个，是否应改为拒绝重复配置仍待确认。
+// resolvePiModel 在组装运行快照前调用它，调用方只需传部署配置和 modelId。
+// 同一 modelId 若配置多次会取第一个，是否应改为拒绝重复配置仍待确认。
 function endpointFor(
   provider: RuntimeProviderPort,
   modelId: string,
@@ -585,6 +617,20 @@ function piApiFor(protocol: RuntimeModelProtocol) {
   }
 }
 
+function anthropicMessagesModelForOpenRouter(
+  modelId: string,
+): Model<"anthropic-messages"> | undefined {
+  if (!modelId.startsWith("anthropic/")) return;
+  const anthropicModelId = modelId
+    .slice("anthropic/".length)
+    .replace(/:batch$/, "")
+    .replace(/-fast$/, "")
+    .replaceAll(".", "-");
+  return CATALOGS["anthropic-messages"].find(
+    (model) => model.id === anthropicModelId,
+  );
+}
+
 // 把部署声明的模型改造成可由对应自定义端点执行的 Pi 模型。
 // resolvePiModel 为单个运行快照调用它，configurePiModels 则在注册端点时为端点中的每个 modelId 调用它。
 // Pi 的内置 OpenAI、Anthropic provider 提供上下文窗口、费用和推理能力等元数据；这里保留这些元数据，但以部署协议、provider 标识和 baseURL 覆盖内置路由，未知模型会在初始化阶段直接报错，而不是拖到请求阶段。
@@ -602,10 +648,10 @@ function configuredModel(
     );
   }
   const {
-    api: _api,
+    api: catalogApi,
     provider: _provider,
     baseUrl: _baseUrl,
-    compat,
+    compat: catalogCompat,
     headers: catalogHeaders,
     ...metadata
   } = catalogModel;
@@ -614,17 +660,24 @@ function configuredModel(
     ...endpoint.headers,
   };
   const openRouterProviderPin = endpoint.openRouterProviderPins?.[modelId];
-  const supportsStrictTools = modelId.startsWith("anthropic/claude-");
+  const configuredApi = apiFor(endpoint.protocol);
+  // OpenRouter uses dotted versions and optional transport suffixes while the
+  // Anthropic catalog uses dashed base model ids.
+  const anthropicMessagesCompat = endpoint.protocol === "openrouter-messages"
+    ? anthropicMessagesModelForOpenRouter(modelId)?.compat
+    : undefined;
   return {
     ...metadata,
-    api: apiFor(endpoint.protocol),
+    api: configuredApi,
     provider: providerId(endpoint, index),
     baseUrl: endpoint.baseURL,
     ...(endpoint.protocol === "openrouter-messages"
       ? {
           compat: {
+            ...anthropicMessagesCompat,
             supportsEagerToolInputStreaming: false,
-            supportsStrictTools,
+            supportsStrictTools:
+              anthropicMessagesCompat?.supportsStrictTools ?? false,
             supportsToolReferences: true,
             openRouterRouting: {
               require_parameters: true,
@@ -637,7 +690,9 @@ function configuredModel(
             },
           },
         }
-      : {}),
+      : catalogApi === configuredApi && catalogCompat
+        ? { compat: catalogCompat }
+        : {}),
     ...(Object.keys(headers).length > 0 ? { headers } : {}),
   };
 }
@@ -661,24 +716,6 @@ export function resolvePiModel(
   return configuredModel(endpoint, index, modelId);
 }
 
-/**
- * 取出负责指定模型的部署端点密钥。
- *
- * Runtime 在创建一次模型执行或压缩上下文前调用它；辅助的标题生成器也在请求 Pi 时使用它。
- * 调用方应传入与 {@link resolvePiModel} 相同的 provider 和 modelId，并只把返回值用于当前请求。
- *
- * 它与模型解析共用 endpointFor，确保密钥和模型总是选择同一个端点，也让未配置的模型在密钥离开部署边界前失败。
- * 不要另写按协议选密钥的分支，否则同协议的多个端点会拿错凭据。
- *
- * @throws 当部署未配置该 modelId 时抛出错误。
- */
-export function resolvePiApiKey(
-  provider: RuntimeProviderPort,
-  modelId: string,
-): string {
-  return endpointFor(provider, modelId).endpoint.apiKey;
-}
-
 /**
  * 用当前部署端点完整重建一个已有的 Pi 模型集合。
  *

package/src/pi/runtime-adapter/transcript.ts

@@ -440,7 +440,7 @@ export class PiRuntimeTranscript {
   /**
    * 在 Pi 请求模型前按 Runtime 阈值压缩当前上下文，并把压缩 entry 写回 Session。
    *
-   * `AgentRuntimeKernel.transformPiContext` 作为 Pi 的 `transformContext` 调用它，并提供本次固定的模型、密钥和取消信号。
+   * `AgentRuntimeKernel.transformPiContext` 作为 Pi 的 `transformContext` 调用它，并提供本次固定的模型和取消信号。
    *
    * 方法先逐条核对调用参数与耐久分支；不一致或压缩不可用时保留原消息，避免把漂移的内存上下文提交成新的规范分支。
    */
@@ -448,8 +448,8 @@ export class PiRuntimeTranscript {
     messages: AgentMessage[],
     options: {
       compactAfterTokens: number;
+      force?: boolean;
       model: Model<Api>;
-      apiKey: string;
       signal?: AbortSignal;
       submissionId?: string;
       onCompactionPersisted?: (event: RuntimeModelUsageEvent) => void;
@@ -474,11 +474,14 @@ export class PiRuntimeTranscript {
     const result = await compactPiContext({
       branch,
       compactAfterTokens: options.compactAfterTokens,
+      force: options.force,
       models: this.models,
       model: options.model,
-      apiKey: options.apiKey,
       signal: options.signal,
     });
+    if (options.force && !result.didCompact) {
+      throw new Error("Forced context compaction did not reduce the model input");
+    }
     if (result.compactionEntry) {
       // 整对象写入:assembly 侧已经造好了完整的 compaction 条目,这里不再拆成位置
       // 参数。旧写法拆 5 个参数喂 pi 的 Session.appendCompaction,pi 0.81 把它加到

package/src/pi/tool/base.ts

@@ -2,7 +2,12 @@ import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
-import { Type, type Static, type TSchema } from "@earendil-works/pi-ai";
+import {
+  StringEnum,
+  Type,
+  type Static,
+  type TSchema,
+} from "@earendil-works/pi-ai";
 import { estimateStringTokens } from "agents/experimental/memory/utils";
 import type { RuntimeMemoryPort } from "../../kernel/bindings";
 import type { RuntimeMemoryProfile } from "../../kernel/profile";
@@ -145,11 +150,7 @@ const updatePlanParameters = Type.Object({
     text: Type.String({
       description: "The step, phrased as a short imperative.",
     }),
-    status: Type.Union([
-      Type.Literal("pending"),
-      Type.Literal("in_progress"),
-      Type.Literal("done"),
-    ], {
+    status: StringEnum(["pending", "in_progress", "done"] as const, {
       description:
         'Current status. Use "done" for a finished step; never use "completed".',
     }),
@@ -214,18 +215,12 @@ export function normalizeUpdatePlanArguments(
 }
 
 const setContextParameters = Type.Object({
-  label: Type.Union([
-    Type.Literal("memory"),
-    Type.Literal("preferences"),
-  ], {
+  label: StringEnum(["memory", "preferences"] as const, {
     description:
       "Context block to update: memory for durable facts and active context, preferences for tone and workflow choices.",
   }),
   content: Type.String({ description: "Text to store in the selected context block." }),
-  action: Type.Optional(Type.Union([
-    Type.Literal("replace"),
-    Type.Literal("append"),
-  ], {
+  action: Type.Optional(StringEnum(["replace", "append"] as const, {
     description: 'Whether to replace the block or append to it. Defaults to "replace".',
   })),
 }, { additionalProperties: false });
@@ -318,7 +313,7 @@ export function basePiToolCandidates(
         name: "update_plan",
         label: "Update plan",
         description:
-          "Maintain the user-visible plan for the current task. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
+          "Maintain the user-visible plan for the current task. Required input: steps. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
         parameters: updatePlanParameters,
         prepareArguments: normalizeUpdatePlanArguments,
         async execute(_toolCallId, input) {

package/src/pi/tool/compiler.ts

@@ -66,7 +66,7 @@ export interface PiToolCandidate {
    * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
    */
   readonly alwaysRequiresApproval?: boolean;
-  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. */
+  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
   readonly retry?: "idempotent" | "non-idempotent";
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];

package/src/pi/tool/core.ts

@@ -196,6 +196,7 @@ export function listExtensionsPiToolCandidate(
   return {
     owner: "core:extensions",
     requiredExecutionLevel: "low",
+    retry: "idempotent",
     tool,
   };
 }
@@ -278,6 +279,7 @@ export function codeExecutionPiToolCandidate(
   return {
     owner: "core:codemode",
     requiredExecutionLevel: "safe",
+    retry: "idempotent",
     outputBudget: { kind: "structure" },
     source: "codemode",
     summary: "Run JavaScript with network and configured connector access",

package/src/pi/tool/schedule.ts

@@ -92,7 +92,7 @@ function candidate<T extends TSchema>(
   options: Partial<
     Pick<
       PiToolCandidate,
-      "alwaysRequiresApproval" | "exposureMode" | "owner" | "requiredExecutionLevel" | "summary"
+      "alwaysRequiresApproval" | "exposureMode" | "owner" | "requiredExecutionLevel" | "retry" | "summary"
     >
   > = {},
 ): PiToolCandidate {
@@ -106,6 +106,7 @@ function candidate<T extends TSchema>(
       ? { alwaysRequiresApproval: true }
       : {}),
     ...(options.summary ? { summary: options.summary } : {}),
+    ...(options.retry ? { retry: options.retry } : {}),
   };
 }
 
@@ -138,17 +139,20 @@ export function schedulePiToolCandidates(
         summary: "Create a scheduled task",
       },
     ),
-    candidate({
-      name: "list_schedules",
-      label: "List schedules",
-      description:
-        "List the user's existing scheduled tasks. Call this when the user asks what they have scheduled, or before cancelling one — you need the id, and the user will refer to a task by what it does, not by its id.",
-      parameters: noParameters,
-      async execute(_toolCallId, _input, signal) {
-        signal?.throwIfAborted();
-        return result({ schedules: await schedule.list() });
+    candidate(
+      {
+        name: "list_schedules",
+        label: "List schedules",
+        description:
+          "List the user's existing scheduled tasks. Call this when the user asks what they have scheduled, or before cancelling one — you need the id, and the user will refer to a task by what it does, not by its id.",
+        parameters: noParameters,
+        async execute(_toolCallId, _input, signal) {
+          signal?.throwIfAborted();
+          return result({ schedules: await schedule.list() });
+        },
       },
-    }),
+      { retry: "idempotent" },
+    ),
     candidate({
       name: "update_schedule",
       label: "Update schedule",

package/src/pi/tool/skill.ts

@@ -534,6 +534,9 @@ export async function skillPiToolCandidates(
       ...(name === "activate_skill"
         ? { exposureMode: "direct" as const }
         : { exposureMode: "codemode" as const }),
+      ...(name === "activate_skill" || name === "read_skill_resource"
+        ? { retry: "idempotent" as const }
+        : {}),
       tool: adapted,
     };
   });

package/src/pi/tool/subagent.ts

@@ -182,6 +182,7 @@ export function subagentPiToolCandidates(
       owner: `subagent:${type.name}`,
       exposureMode: "direct",
       requiredExecutionLevel: "safe",
+      retry: "idempotent",
       tool,
     };
   });
@@ -265,6 +266,7 @@ export function subagentPiToolCandidates(
     owner: "subagent:background",
     exposureMode: "direct",
     requiredExecutionLevel: "low",
+    retry: "idempotent",
     summary: "Dispatch a background sub-agent",
     source: "action",
     tool: background,

package/src/pi/tool/time.ts

@@ -11,6 +11,7 @@ export function getTimePiToolCandidate(owner = "utilities"): PiToolCandidate {
   return {
     owner,
     requiredExecutionLevel: "safe",
+    retry: "idempotent",
     source: "action",
     summary: "Get the current server time as an ISO string.",
     tool: {

package/src/pi/tool/web-search/api.ts

@@ -707,6 +707,12 @@ async function callOpenAIStream(
         tools: isOpenRouter
             ? [{ type: "openrouter:web_search", parameters: { max_uses: 10 } }]
             : [{ type: "web_search" }],
+        ...(isOpenRouter
+            ? {
+                max_output_tokens: Math.min(model.maxTokens, OPENROUTER_MAX_OUTPUT_TOKENS),
+                reasoning: { effort: "none" },
+            }
+            : {}),
         ...(!isOpenRouter
             ? {
                 include: isCodex
@@ -1108,6 +1114,8 @@ export function applyCitations(text: string, groundingMetadata: any): { text: st
 
 const PROVIDER_ERROR_MAX_LENGTH = 2_048;
 const NATIVE_TIMEOUT_MS = 60_000;
+const OPENROUTER_MAX_OUTPUT_TOKENS = 4_096;
+export const WEB_SEARCH_MODEL = "deepseek/deepseek-v4-flash";
 
 export interface WebSearchOptions {
     endpoint: RuntimeModelEndpoint;

package/src/pi/tool/web-search/web-search.ts

@@ -121,6 +121,7 @@ export function webSearchPiToolCandidate(
     owner: "runtime-base",
     exposureMode: "direct",
     requiredExecutionLevel: "safe",
+    retry: "idempotent",
     source: "action",
     tool,
   };

package/src/pi/tool/workspace-sandbox.ts

@@ -402,6 +402,7 @@ export function workspacePiToolCandidates(
     {
       owner: "workspace",
       requiredExecutionLevel: "safe" as const,
+      retry: "idempotent" as const,
       // read 是大输出外置协议的**出口**：溢出结果的提示语指向它。出口自己再外置，
       // 就会变成 read → 新 artifact → read 的死循环，模型只能靠猜逃出去。
       // 分页上限由 `pageReadResult` 自己保证，不需要外置也不会撑爆一轮。
@@ -411,6 +412,7 @@ export function workspacePiToolCandidates(
     ...[write, edit, list, find, grep, remove].map((tool) => ({
       owner: "workspace",
       requiredExecutionLevel: "safe" as const,
+      retry: "idempotent" as const,
       tool,
     })),
   ];
@@ -621,6 +623,7 @@ export function sandboxPiToolCandidates(
     {
       owner: "sandbox",
       requiredExecutionLevel: "safe",
+      retry: "idempotent",
       tool: processLogs,
     },
     {

package/src/runtime-agent.ts

@@ -301,6 +301,7 @@ export interface RuntimeAgentControls {
     requestId?: string,
     reason?: string,
   ): Promise<{ ok: boolean }>;
+  stopAllSubmissions(reason?: string): Promise<{ ok: boolean }>;
 }
 
 export interface RuntimeAgentConfigControls<Command, Change> {
@@ -525,6 +526,10 @@ export function defineRuntimeAgent<
         return super.stopTurn(requestId, reason);
       }
 
+      stopAllSubmissions(reason?: string): Promise<{ ok: boolean }> {
+        return super.stopAllSubmissions(reason);
+      }
+
       protected override async prepareAgentToolRun(
         input: unknown,
       ): Promise<string> {
@@ -922,6 +927,10 @@ export function defineRuntimeAgent<
     callableContext,
   );
   callable()(GeneratedRuntimeAgent.prototype.stopTurn, callableContext);
+  callable()(
+    GeneratedRuntimeAgent.prototype.stopAllSubmissions,
+    callableContext,
+  );
 
   return GeneratedRuntimeAgent as unknown as RuntimeAgentClass<
     Env,

package/src/runtime-assembler.ts

@@ -58,7 +58,7 @@ import {
   codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
-import { createWebSearch } from "./pi/tool/web-search";
+import { createWebSearch, WEB_SEARCH_MODEL } from "./pi/tool/web-search";
 import { subagentPiToolCandidates } from "./pi/tool/subagent";
 import { resolvePiModel } from "./pi/runtime-adapter/models";
 import {
@@ -170,7 +170,7 @@ interface ToolSurfaceInput {
   readonly hostTools: readonly PiToolCandidate[];
   readonly skills: readonly RuntimeSkillSourceBinding[];
   readonly enabledSubagents: readonly string[];
-  readonly webSearch: Parameters<typeof basePiToolCandidates>[0];
+  readonly webSearch?: Parameters<typeof basePiToolCandidates>[0];
   readonly extensions: readonly RuntimeExtensionConfig[];
   readonly policy?: RuntimeToolSurfacePolicy;
 }
@@ -581,14 +581,20 @@ class RuntimeBuilder {
           : `Model is configured by multiple endpoints: ${profile.model}`,
       );
     }
-    const resolvedModel = resolvePiModel(provider, profile.model);
-    const endpoint = endpoints[0]!;
-    const webSearch = createWebSearch({
-      endpoint,
-      model: profile.model,
-      maxTokens: resolvedModel.maxTokens,
-      reasoning: resolvedModel.reasoning,
-    });
+    const webSearchEndpoint = provider.endpoints.find((endpoint) =>
+      endpoint.models.includes(WEB_SEARCH_MODEL)
+    );
+    const webSearch = webSearchEndpoint
+      ? (() => {
+          const webSearchModel = resolvePiModel(provider, WEB_SEARCH_MODEL);
+          return createWebSearch({
+            endpoint: webSearchEndpoint,
+            model: WEB_SEARCH_MODEL,
+            maxTokens: webSearchModel.maxTokens,
+            reasoning: webSearchModel.reasoning,
+          });
+        })()
+      : undefined;
     const skillSources = [...this.skillSources.values()];
     const toolSurface = await createToolSurface({
       ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
@@ -606,7 +612,7 @@ class RuntimeBuilder {
       ],
       skills: skillSources,
       enabledSubagents: [...this.enabledSubagents],
-      webSearch,
+      ...(webSearch ? { webSearch } : {}),
       extensions: [...this.extensions.values()],
       ...(this.toolPolicy ? { policy: this.toolPolicy } : {}),
     });