@springbrand/agent-runtime 0.2.0-alpha.42 → 0.2.0-alpha.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.42",
+  "version": "0.2.0-alpha.44",
   "type": "module",
   "files": [
     "src",

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

@@ -29,9 +29,6 @@ const READONLY_WORKSPACE_TOOLS = new Set([
   "grep",
 ]);
 const DENIED_TOOLS = [
-  // SubAgents have no approval channel; keep the restored high-risk Workspace
-  // shell on the main Agent surface, matching the pre-Pi behavior.
-  "bash",
   "run_agent",
   "subagents",
   "fanout",
@@ -46,11 +43,11 @@ const executeParameters = Type.Object({
     description:
       "JavaScript to run. Return the final value. The sandbox provides fetch and state.*.",
   }),
-});
+}, { additionalProperties: false });
 
 const fetchParameters = Type.Object({
   url: Type.String({ minLength: 1, maxLength: 8_192 }),
-});
+}, { additionalProperties: false });
 
 function result(details: unknown): AgentToolResult<unknown> {
   let text: string;

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

@@ -55,14 +55,6 @@ const DEFAULT_MEMORY: RuntimeMemoryProfile = Object.freeze({
 });
 
 const WORKSPACE_TOOL_NAMES = [
-  "read",
-  "write",
-  "edit",
-  "list",
-  "find",
-  "grep",
-  "delete",
-  "bash",
   "execute",
 ] as const;
 
@@ -157,6 +149,7 @@ export async function prepareWorkspace<Env extends Cloudflare.Env>(
       loader: platform.loader,
       outbound: platform.outbound(),
       workspace: workspace.value,
+      workspaceAccessMode: "write",
     }),
     degradations: workspace.degradations,
   };

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

@@ -12,7 +12,6 @@ import { schedulePiToolCandidates } from "../../../pi/tool/schedule";
 import { workspaceRevisionPiToolCandidate } from "../../../pi/tool/workspace-revision";
 import {
   sandboxPiToolCandidates,
-  workspacePiToolCandidates,
 } from "../../../pi/tool/workspace-sandbox";
 import type { RuntimeCodeExecutionFactory } from "../../../kernel/bindings";
 import type { ToolAssemblyResult } from "../../../runtime-definition";
@@ -34,7 +33,6 @@ export function assembleUniversalAgentTools(options: {
 }): ToolAssemblyResult {
   const tools = [
     ...(options.hostTools ?? []),
-    ...(options.workspace ? workspacePiToolCandidates(options.workspace) : []),
     ...(options.workspaceRevisions
       ? [workspaceRevisionPiToolCandidate(options.workspaceRevisions)]
       : []),

package/src/adapter/cloudflare/workspace/scoped-workspace.ts

@@ -2,6 +2,7 @@ import type {
   WorkspaceAdminPort,
   WorkspaceFileInfo,
   WorkspacePort,
+  WorkspaceStreamWriteOptions,
   WorkspaceQuota,
   WorkspaceUsage,
 } from "../../../kernel/bindings";
@@ -216,6 +217,18 @@ export class ScopedWorkspace implements WorkspacePort, WorkspaceAdminPort {
     );
   }
 
+  async writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    options?: WorkspaceStreamWriteOptions,
+  ) {
+    return this.parent.writeFileStream(
+      await this.guardedPhysical(path, true),
+      content,
+      options,
+    );
+  }
+
   async writeFileBytesIfUnchanged(
     path: string,
     data: Uint8Array,
@@ -363,6 +376,8 @@ export function createWorkspacePortFacade(
       workspace.writeFile(path, content, mimeType),
     writeFileBytes: (path, data, mimeType) =>
       workspace.writeFileBytes(path, data, mimeType),
+    writeFileStream: (path, content, options) =>
+      workspace.writeFileStream(path, content, options),
     appendFile: (path, content, mimeType) =>
       workspace.appendFile(path, content, mimeType),
     exists: (path) => workspace.exists(path),

package/src/index.ts

@@ -93,6 +93,7 @@ export type {
   CompilePiToolsOptions,
   PiToolCandidate,
   SettledPiToolCall,
+  ToolExposureMode,
 } from "./pi/tool";
 export { basePiToolCandidates } from "./pi/tool";
 export { createPiDeclaredToolCandidate } from "./pi/tool";

package/src/kernel/bindings.ts

@@ -92,6 +92,11 @@ export interface WorkspacePort {
     data: Uint8Array | ArrayBuffer,
     mimeType?: string,
   ): Promise<void>;
+  writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    options?: WorkspaceStreamWriteOptions,
+  ): Promise<{ path: string; bytes: number }>;
   /**
    * 把文本追加到文件末尾。
    *
@@ -205,6 +210,11 @@ export interface WorkspacePort {
   glob(pattern: string): Promise<WorkspaceFileInfo[]>;
 }
 
+export interface WorkspaceStreamWriteOptions {
+  contentLength?: number;
+  mediaType?: string;
+}
+
 /**
  * 向 Runtime 提供已组装的 Workspace Code Mode 执行能力。
  *
@@ -845,6 +855,10 @@ export interface RuntimeTurnEventsPort {
     readonly submissionId: string;
     readonly approvalExecutionId: string;
   }): Promise<void>;
+  /**
+   * 至少一次投当前 Session Activity；Host 应按 revision 幂等处理重试。
+   * Runtime 恢复时会略过已过时的 revision，避免重放旧 working 状态。
+   */
   onActivityChanged?(
     projection: RuntimeActivityProjection,
   ): Promise<void>;

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

@@ -173,13 +173,13 @@ export async function spillDurableToolOutput(
       // 出口指令必须是可执行的，而且必须只承诺模型真的拿得到的东西：Provider 只把
       // Tool 结果的 content 发给模型，所以这里不能引用只存在于 details 的字段。
       // 溢出产物是 JSON，一个大字符串叶子会整块挤在一行上，而按行分页追不回被行宽
-      // 截断的内容 —— 那种情况要走 grep / bash，不能让模型以为 read 一定够用。
+      // 截断的内容 —— 那种情况要走 state.searchText，不能让模型以为分页读取一定够用。
       note:
         "Output was large and has been saved to the Workspace file above. " +
-        "Read it in pages with read(path, offset, limit) — do not read it whole; " +
+        "Read it in pages inside execute with state.readFile — do not read it whole; " +
         "each page ends with a footer telling you the line range and the next offset. " +
         "This file is JSON, so a single large value can sit on one very long line: " +
-        "if a page reports that lines were cut short, use grep or bash on the path instead.",
+        "if a page reports that lines were cut short, use state.searchText on the path instead.",
     };
   } catch {
     return null;

package/src/layers/orchestration/temporary-agent/workspace.ts

@@ -83,6 +83,8 @@ export function createTemporaryAgentWorkspace(
     // 原因：二进制写入必须与文本写入使用同一 Memory 禁止，不能留下第二条写入路径。
     writeFileBytes: async (path, data, mimeType) =>
       workspace.writeFileBytes(allowed(path), data, mimeType),
+    writeFileStream: async (path, content, options) =>
+      workspace.writeFileStream(allowed(path), content, options),
     // 作用：在一个允许的文件末尾追加文本。
     // 调用：临时 Agent 需要增量写入时通过 Workspace Tool 调用。
     // 原因：追加也是写操作，必须在委托前拦截 Memory 路径。

package/src/lib/prompt.ts

@@ -55,7 +55,7 @@ export const TOOLS =
   TOOL_ROUTING +
   " Relatedness, repetition, or multiple calls never overrides this availability rule. " +
   "When every required Tool is available inside execute, use one execute for repeated or related calls, branching, or repetition. Inside execute, " +
-  "use state.* for workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
+  "use state.* for workspace file operations, tools.* for other host capabilities, and sequential calls for repeated or durable operations. " +
   "Top-level-only Tools remain Direct even when called repeatedly. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
   "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
@@ -65,11 +65,7 @@ export const TOOLS =
   "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
   "published /workspace outputs survive. Use Code Mode for computation, multi-step data work, and the " +
   "raw or customized network cases described above; every response and failure it sees is visible to you. " +
-  "bash is a shell over the workspace filesystem only " +
-  "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
-  "When execute is present, make related file changes in one execute with state.*. " +
-  "Use read for one existing Workspace file, write to create or replace one file, and edit for one localized change. " +
-  "Use bash only when a single shell workflow must coordinate multiple Workspace files; do not use it for a single-file read, write, or edit. " +
+  "Every Workspace filesystem operation goes through execute and state.*; no Workspace file methods exist under tools.*. " +
   "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "prioritize verification, saving durable results, and the final response. " +
   "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
@@ -104,8 +100,7 @@ export const BROWSER =
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
 export const FILES =
   "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
-  "'<file>.md' (structured markdown). Policy: to summarize/quote/search one file, read or grep the .md; when execute is present, " +
-  "read or search multiple files through state.* in one execute instead of repeated top-level file Tool calls. " +
+  "'<file>.md' (structured markdown). Policy: to summarize, quote, or search files, use state.* inside execute. " +
   "To compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
   "the ORIGINAL file — converted markdown tables are not for computation, and large spreadsheets may " +
   "have no .md at all. For formats without a companion .md (e.g. pptx: unzip and read ppt/slides/*.xml; " +

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

@@ -523,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;
@@ -653,7 +655,6 @@ export class PreparedPiTurnAdapter {
   private readonly turn: PiTurnAdapter;
   private readonly abortController = new AbortController();
   private readonly candidates: readonly PiToolCandidate[];
-  private nestedToolOrdinal = 0;
   private assistantOrdinal: number;
   private readonly encoder: PiChunkEncoder;
   private readonly steerMessageIds: string[] = [];
@@ -829,7 +830,7 @@ export class PreparedPiTurnAdapter {
             return execute(toolCallId, input, signal, onUpdate);
           }
           const startedAt = Date.now();
-          const telemetryToolCallId = `${toolCallId}:${++this.nestedToolOrdinal}`;
+          const telemetryToolCallId = toolCallId;
           options.onNestedToolStarted?.({
             parentToolCallId: toolCallIdPrefix,
             toolCallId: telemetryToolCallId,
@@ -906,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>;
 
@@ -197,7 +197,8 @@ export function normalizeUpdatePlanArguments(
     steps: steps.map((step) => {
       if (step === null || typeof step !== "object") return step;
       const s = step as Record<string, unknown>;
-      const { step: alias, ...rest } = s;
+      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"
@@ -227,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 {
@@ -241,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>,
   };
 }
 
@@ -307,7 +311,7 @@ export function basePiToolCandidates(
           return result({ noted: true, count: input.items.length });
         },
       }),
-      direct: true,
+      exposureMode: "direct",
     },
     {
       ...candidate({
@@ -325,7 +329,7 @@ export function basePiToolCandidates(
           });
         },
       }),
-      direct: true,
+      exposureMode: "direct",
     },
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];

package/src/pi/tool/compiler.ts

@@ -43,15 +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;
-  /** Keep this Tool Direct-only instead of also offering it through Code Mode. */
-  readonly direct?: true;
-  /** Offer this Tool only through Code Mode, never as a top-level Tool. */
-  readonly codeExecutionOnly?: 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. */
@@ -310,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 供结算去重。