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

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

@@ -10,7 +10,7 @@ import type {
 import type { RuntimeProfile } from "../../kernel/profile";
 import type { ExecutionLevel } from "../../lib/execution-level";
 import type { RuntimeSnapshot } from "../../runtime-assembler";
-import type { PiRuntimeAssembly } from "../assembly";
+import type { FinalizedPiToolSurface, PiRuntimeAssembly } from "../assembly";
 import {
   assemblePiSystemContext,
   assemblePiExtensions,
@@ -77,7 +77,7 @@ interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
   readonly context: readonly PiExtensionContextContribution[];
   readonly degradations: PiExtensionAssembly["degradations"];
-  readonly toolSurface: readonly PiToolCandidate[];
+  readonly toolSurface: FinalizedPiToolSurface;
 }
 
 /**
@@ -193,6 +193,7 @@ export interface PreparedPiRuntimeState {
   readonly snapshot: RuntimeSnapshot;
   readonly assembly: PreparedPiAssembly;
   readonly candidates: readonly PiToolCandidate[];
+  readonly codeExecutionCandidates: readonly PiToolCandidate[];
 }
 
 // #endregion
@@ -208,6 +209,7 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "bind_resource",
   "delete",
   "edit",
+  "execute",
   "find",
   "get_time",
   "grep",
@@ -446,7 +448,7 @@ export async function preparePiRuntime(
   owner: object,
 ): Promise<PreparedPiRuntime> {
   const assembly = await preparePiAssembly(options);
-  const candidates = assembly.toolSurface;
+  const candidates = assembly.toolSurface.candidates;
   return Object.freeze(new PreparedRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([
@@ -460,6 +462,9 @@ export async function preparePiRuntime(
       snapshot: options.snapshot,
       assembly,
       candidates: Object.freeze([...candidates]),
+      codeExecutionCandidates: Object.freeze([
+        ...assembly.toolSurface.codeExecutionCandidates,
+      ]),
     }),
   ));
 }

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

@@ -25,6 +25,7 @@ import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
 import { ChatStreamStalledError } from "agents/chat";
 import {
+  codeExecutionPiToolCandidate,
   compilePiTools,
   createPiToolGovernance,
   normalizeUpdatePlanArguments,
@@ -522,6 +523,8 @@ export interface PiTurnDurability {
 export interface CreatePreparedPiTurnOptions {
   readonly prepared: PreparedPiRuntime;
   readonly pinnedDescriptor: string;
+  /** 同一 Session 的所有 Submission 共用的稳定 Provider 路由身份。 */
+  readonly modelSessionId: string;
   readonly submission: {
     readonly id: string;
     readonly requestId: string;
@@ -542,6 +545,25 @@ export interface CreatePreparedPiTurnOptions {
   readonly durability: PiTurnDurability;
   /** Reports paired model-generation lifecycle facts to the Runtime owner. */
   readonly onGeneration?: PiGenerationLifecycleObserver;
+  /** Reports Code Mode child Tool starts without adding Pi recovery state. */
+  readonly onNestedToolStarted?: (input: Readonly<{
+    parentToolCallId: string;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    occurredAt: number;
+  }>) => void;
+  /** Reports Code Mode child Tool outcomes without adding Pi settlements. */
+  readonly onNestedToolFinished?: (input: Readonly<{
+    parentToolCallId: string;
+    toolCallId: string;
+    toolName: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs: number;
+    output?: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
+    error?: unknown;
+    occurredAt: number;
+  }>) => void;
   /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
   readonly toolExecutors?: Readonly<Record<
     string,
@@ -665,6 +687,8 @@ export class PreparedPiTurnAdapter {
     });
     const bindCandidate = (
       candidate: PiToolCandidate,
+      toolCallIdPrefix?: string,
+      recordRecoveryAttempt = true,
     ): PiToolCandidate => ({
       ...candidate,
       tool: {
@@ -673,6 +697,9 @@ export class PreparedPiTurnAdapter {
         // 实时运行由 PiCore 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
         // 顺序不能随便调整：门禁先于结果复用，审批可能生成结果，不确定的非幂等工作不能重放。
         execute: async (toolCallId, input, signal, onUpdate) => {
+          if (toolCallIdPrefix) {
+            toolCallId = `${toolCallIdPrefix}:${toolCallId}`;
+          }
           const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
             ? await candidate.requiredExecutionLevelForInput(input)
             : candidate.requiredExecutionLevel;
@@ -783,25 +810,93 @@ export class PreparedPiTurnAdapter {
             }
             return responded.result;
           }
-          const retry = piToolRetryPolicy(candidate);
-          const firstAttempt = options.durability.appendToolInput({
-            toolCallId,
+          if (recordRecoveryAttempt) {
+            const retry = piToolRetryPolicy(candidate);
+            const firstAttempt = options.durability.appendToolInput({
+              toolCallId,
+              toolName: candidate.tool.name,
+              input,
+              retry,
+            });
+            if (!firstAttempt && retry === "non-idempotent") {
+              throw new Error(
+                `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
+              );
+            }
+          }
+          const execute = options.toolExecutors?.[candidate.tool.name] ??
+            candidate.tool.execute;
+          if (recordRecoveryAttempt || !toolCallIdPrefix) {
+            return execute(toolCallId, input, signal, onUpdate);
+          }
+          const startedAt = Date.now();
+          const telemetryToolCallId = toolCallId;
+          options.onNestedToolStarted?.({
+            parentToolCallId: toolCallIdPrefix,
+            toolCallId: telemetryToolCallId,
             toolName: candidate.tool.name,
             input,
-            retry,
+            occurredAt: startedAt,
           });
-          if (!firstAttempt && retry === "non-idempotent") {
-            throw new Error(
-              `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
-            );
+          try {
+            const output = await execute(toolCallId, input, signal, onUpdate);
+            const occurredAt = Date.now();
+            options.onNestedToolFinished?.({
+              parentToolCallId: toolCallIdPrefix,
+              toolCallId: telemetryToolCallId,
+              toolName: candidate.tool.name,
+              outcome: "completed",
+              durationMs: occurredAt - startedAt,
+              output,
+              occurredAt,
+            });
+            return output;
+          } catch (error) {
+            const occurredAt = Date.now();
+            options.onNestedToolFinished?.({
+              parentToolCallId: toolCallIdPrefix,
+              toolCallId: telemetryToolCallId,
+              toolName: candidate.tool.name,
+              outcome: signal?.aborted ? "cancelled" : "failed",
+              durationMs: occurredAt - startedAt,
+              error,
+              occurredAt,
+            });
+            throw error;
           }
-          const execute = options.toolExecutors?.[candidate.tool.name] ??
-            candidate.tool.execute;
-          return execute(toolCallId, input, signal, onUpdate);
         },
       },
     });
-    this.candidates = state.candidates.map(bindCandidate);
+    this.candidates = state.candidates.map((candidate) => {
+      if (candidate.tool.name !== "execute") return bindCandidate(candidate);
+      const factory = state.snapshot.bindings.codeExecution;
+      if (!factory) {
+        throw new Error("Prepared Code Mode Tool requires a Runtime factory");
+      }
+      return bindCandidate({
+        ...candidate,
+        tool: {
+          ...candidate.tool,
+          execute: (toolCallId, input, signal, onUpdate) => {
+            const runtimeCandidate = codeExecutionPiToolCandidate(
+              factory.create(state.codeExecutionCandidates.map((inner) =>
+                // Code Mode owns replay of its connector calls. Pi persists
+                // only the parent execute attempt/result; recording an inner
+                // input without a Pi settlement creates an orphan recovery
+                // action that cannot be found on the direct Tool surface.
+                bindCandidate(inner, toolCallId, false)
+              )),
+            );
+            return runtimeCandidate.tool.execute(
+              toolCallId,
+              input,
+              signal,
+              onUpdate,
+            );
+          },
+        },
+      });
+    });
     this.turn = new PiTurnAdapter({
       pi: {
         model: state.snapshot.pi.model,
@@ -812,7 +907,7 @@ export class PreparedPiTurnAdapter {
         state.snapshot.bindings.provider,
         state.snapshot.pi.model.id,
       ),
-      modelSessionId: options.submission.requestId,
+      modelSessionId: options.modelSessionId,
       ...(options.onGeneration ? { onGeneration: options.onGeneration } : {}),
       canonicalMessages: options.canonicalMessages,
       // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实

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

@@ -614,6 +614,7 @@ function configuredModel(
     ...endpoint.headers,
   };
   const openRouterProviderPin = endpoint.openRouterProviderPins?.[modelId];
+  const supportsStrictTools = modelId.startsWith("anthropic/claude-");
   return {
     ...metadata,
     api: apiFor(endpoint.protocol),
@@ -623,15 +624,17 @@ function configuredModel(
       ? {
           compat: {
             supportsEagerToolInputStreaming: false,
+            supportsStrictTools,
             supportsToolReferences: true,
-            ...(openRouterProviderPin
-              ? {
-                  openRouterRouting: {
+            openRouterRouting: {
+              require_parameters: true,
+              ...(openRouterProviderPin
+                ? {
                     order: [openRouterProviderPin],
                     allow_fallbacks: false,
-                  },
-                }
-              : {}),
+                  }
+                : {}),
+            },
           },
         }
       : {}),

package/src/pi/runtime-adapter/openrouter-messages.ts

@@ -10,6 +10,8 @@ import {
 
 type Payload = Record<string, unknown>;
 
+const STRUCTURED_OUTPUTS_BETA = "structured-outputs-2025-11-13";
+
 function record(value: unknown): Payload | undefined {
   return value !== null && typeof value === "object"
     ? value as Payload
@@ -56,9 +58,11 @@ function decoratePayload(
   return {
     ...body,
     ...(sessionId ? { session_id: sessionId } : {}),
-    ...(model.compat?.openRouterRouting
-      ? { provider: model.compat.openRouterRouting }
-      : {}),
+    provider: {
+      ...record(body.provider),
+      ...model.compat?.openRouterRouting,
+      require_parameters: true,
+    },
     ...(deferred.length > 0
       ? {
           tools: [
@@ -90,6 +94,9 @@ function openRouterOptions(
     apiKey: undefined,
     headers: {
       ...headers,
+      ...(model.compat?.supportsStrictTools === true
+        ? { "x-anthropic-beta": STRUCTURED_OUTPUTS_BETA }
+        : {}),
       ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
       "x-api-key": null,
     },

package/src/pi/tool/base.ts

@@ -31,7 +31,7 @@ const askUserQuestion = Type.Object({
     description:
       "Whether the user may add free text. Defaults to false with options and true without options.",
   })),
-});
+}, { additionalProperties: false });
 
 const askUserParameters = Type.Object({
   questions: Type.Array(askUserQuestion, {
@@ -40,7 +40,7 @@ const askUserParameters = Type.Object({
     description:
       "All user decisions needed to continue. Ask them together in one call.",
   }),
-});
+}, { additionalProperties: false });
 
 /**
  * `ask_user` 的客户端响应体。
@@ -52,8 +52,8 @@ const askUserResponse = Type.Object({
   answers: Type.Array(Type.Object({
     selections: Type.Array(Type.String()),
     text: Type.Optional(Type.String()),
-  })),
-});
+  }, { additionalProperties: false })),
+}, { additionalProperties: false });
 
 type AskUserInput = Static<typeof askUserParameters>;
 type AskUserResponse = Static<typeof askUserResponse>;
@@ -138,7 +138,7 @@ const suggestFollowupsParameters = Type.Object({
     maxItems: 4,
     description: "2-4 concrete, distinct follow-up directions.",
   }),
-});
+}, { additionalProperties: false });
 
 const updatePlanParameters = Type.Object({
   steps: Type.Array(Type.Object({
@@ -153,11 +153,11 @@ const updatePlanParameters = Type.Object({
       description:
         'Current status. Use "done" for a finished step; never use "completed".',
     }),
-  }), {
+  }, { additionalProperties: false }), {
     description:
       "The complete, ordered plan. Overwrites any previously reported plan.",
   }),
-});
+}, { additionalProperties: false });
 
 type UpdatePlanArguments = Static<typeof updatePlanParameters>;
 
@@ -183,13 +183,32 @@ export function normalizeUpdatePlanArguments(
     return input as UpdatePlanArguments;
   }
   const value = input as Record<string, unknown>;
-  if (!Array.isArray(value.steps)) return input as UpdatePlanArguments;
+  let steps = value.steps;
+  if (typeof steps === "string") {
+    try {
+      steps = JSON.parse(steps);
+    } catch {
+      return input as UpdatePlanArguments;
+    }
+  }
+  if (!Array.isArray(steps)) return input as UpdatePlanArguments;
   return {
     ...value,
-    steps: value.steps.map((step) => {
+    steps: steps.map((step) => {
       if (step === null || typeof step !== "object") return step;
       const s = step as Record<string, unknown>;
-      return { ...s, status: normalizeStepStatus(s.status) };
+      const { step: stepAlias, title: titleAlias, ...rest } = s;
+      const alias = typeof stepAlias === "string" ? stepAlias : titleAlias;
+      const text = typeof rest.text === "string"
+        ? rest.text
+        : typeof alias === "string"
+        ? alias
+        : undefined;
+      return {
+        ...rest,
+        ...(text === undefined ? {} : { text }),
+        status: normalizeStepStatus(s.status),
+      };
     }),
   } as UpdatePlanArguments;
 }
@@ -209,7 +228,7 @@ const setContextParameters = Type.Object({
   ], {
     description: 'Whether to replace the block or append to it. Defaults to "replace".',
   })),
-});
+}, { additionalProperties: false });
 
 function result<T>(details: T): AgentToolResult<T> {
   return {
@@ -223,7 +242,10 @@ function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidate {
     owner: "runtime-base",
     requiredExecutionLevel: "safe",
     source: "action",
-    tool,
+    tool: {
+      ...tool,
+      constrainedSampling: { type: "json_schema", strict: "prefer" },
+    } as AgentTool<T>,
   };
 }
 
@@ -278,7 +300,8 @@ export function basePiToolCandidates(
         },
       },
     },
-    candidate({
+    {
+      ...candidate({
         name: "suggest_followups",
         label: "Suggest follow-ups",
         description:
@@ -288,7 +311,10 @@ export function basePiToolCandidates(
           return result({ noted: true, count: input.items.length });
         },
       }),
-    candidate({
+      exposureMode: "direct",
+    },
+    {
+      ...candidate({
         name: "update_plan",
         label: "Update plan",
         description:
@@ -303,6 +329,8 @@ export function basePiToolCandidates(
           });
         },
       }),
+      exposureMode: "direct",
+    },
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];
 }

package/src/pi/tool/compiler.ts

@@ -43,11 +43,15 @@ export interface PiToolInteractionSpec {
 }
 
 /** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
+export type ToolExposureMode = "direct" | "codemode" | "both";
+
 export interface PiToolCandidate {
   readonly owner: string;
   readonly tool: AgentTool<any, any>;
   /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
   readonly deferLoading?: true;
+  /** Omitted means visible both directly and through Code Mode. */
+  readonly exposureMode?: ToolExposureMode;
   /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
   /** Trusted parameter-level policy, evaluated before approval or dispatch. */
@@ -306,12 +310,21 @@ function governedTool(
   candidate: PiToolCandidate,
   options: CompilePiToolsOptions,
 ): AgentTool<any, any> {
-  const execute = candidate.tool.execute;
+  const tool = candidate.tool.constrainedSampling === false
+    ? candidate.tool
+    : {
+        ...candidate.tool,
+        constrainedSampling: candidate.tool.constrainedSampling ?? {
+          type: "json_schema" as const,
+          strict: "prefer" as const,
+        },
+      };
+  const execute = tool.execute;
   const state = options.governance?.[governanceState];
   const settle = options.settle;
 
   return {
-    ...candidate.tool,
+    ...tool,
     ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
     // 执行一次完整的受治理 Pi 工具调用。
     // Pi 工具循环选中编译后的工具时调用，调用方应传入稳定 toolCall id 供结算去重。