@springbrand/agent-runtime 0.2.0-alpha.67 → 0.2.0-alpha.69

package/src/pi/tool/compiler.ts

@@ -1,5 +1,5 @@
 import type {
-  AgentOptions,
+  AgentLoopConfig,
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
@@ -88,7 +88,7 @@ const governanceState = Symbol("PiToolGovernanceState");
 
 /** 向 Pi Agent 提供工具后置钩子，并为编译器保留同一 Turn 的治理状态。 */
 export interface PiToolGovernance {
-  readonly afterToolCall: NonNullable<AgentOptions["afterToolCall"]>;
+  readonly afterToolCall: NonNullable<AgentLoopConfig["afterToolCall"]>;
   readonly wrapUpRequested: () => boolean;
   readonly [governanceState]: PiToolGovernanceState;
 }

package/src/pi/tool/core-host.ts

@@ -1,5 +1,6 @@
 import {
   createWorkspaceStateBackend,
+  STATE_TYPES,
   type StateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
@@ -9,7 +10,10 @@ import {
   type ProxyToolOutput,
 } from "@cloudflare/codemode";
 import { createBrowserTools } from "@cloudflare/think/tools/browser";
-import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
+import {
+  createExecuteRuntime,
+  type CreateExecuteToolOptions,
+} from "@cloudflare/think/tools/execute";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
 import type { ToolSet } from "ai";
@@ -18,7 +22,11 @@ import type {
   RuntimeCodeExecutionPort,
   WorkspacePort,
 } from "../../kernel/bindings";
-import { WorkspaceStateConnector } from "./workspace-state-connector";
+import {
+  WorkspaceStateConnector,
+  WORKSPACE_PAGING_INSTRUCTIONS,
+  WORKSPACE_STATE_TYPES,
+} from "./workspace-state-connector";
 import type { RuntimeCodeExecutionFactory } from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
@@ -346,7 +354,10 @@ export function createWorkspaceCodeExecutionFactory(options: {
             },
           )
         : undefined;
-      const createPort = (innerResults: AgentToolResult<unknown>[]) => {
+      const createPort = (
+        innerResults: AgentToolResult<unknown>[],
+        stateOptions: Pick<CreateExecuteToolOptions, "state" | "connectors">,
+      ) => {
         let nestedCallOrdinal = 0;
         const { tool } = createExecuteRuntime({
           ctx: options.ctx,
@@ -358,7 +369,7 @@ export function createWorkspaceCodeExecutionFactory(options: {
             onResult: (value) => innerResults.push(value),
           }),
           timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-          ...(workspaceState ? { connectors: [workspaceState] } : state ? { state } : {}),
+          ...stateOptions,
           name: "execute",
         });
         return toCodeExecutionPort(
@@ -370,10 +381,21 @@ export function createWorkspaceCodeExecutionFactory(options: {
           ),
         );
       };
-      const description = createPort([]).description;
+      // Inherit the complete official state description; custom connectors otherwise lose its hints.
+      const description = createPort([], state ? { state } : {}).description;
       return {
-        description: `${description}\n\n${SPRINGBRAND_CODE_MODE_POLICY}`,
-        execute: (input) => createPort([]).execute(input),
+        description: [
+          description,
+          ...(state ? [
+            "## Workspace type reference\nOnly methods exposed by connector discovery are callable.\n\n```ts\n" +
+              (workspaceState ? WORKSPACE_STATE_TYPES : STATE_TYPES) + "\n```",
+          ] : []),
+          ...(workspaceState ? [WORKSPACE_PAGING_INSTRUCTIONS] : []),
+          SPRINGBRAND_CODE_MODE_POLICY,
+        ].join("\n\n"),
+        execute: (input) => createPort(
+          [], workspaceState ? { connectors: [workspaceState] } : state ? { state } : {},
+        ).execute(input),
       };
     },
   };

package/src/pi/tool/mcp.ts

@@ -1,4 +1,3 @@
-import type { MCPClientManager } from "agents/mcp/client";
 import type { RuntimeMcpServer } from "../../kernel/profile";
 import type { PiToolCandidate } from "./compiler";
 import { createPiDeclaredToolCandidate } from "./declared";
@@ -51,7 +50,8 @@ export interface PiMcpHost {
     }>;
   };
   /** 提供原始工具发现，以及对指定 MCP Server 的一次工具调用。 */
-  readonly mcp: Pick<MCPClientManager, "listTools"> & {
+  readonly mcp: {
+    listTools(filter?: { serverId: string[]; state: 'ready' }): PiDiscoveredMcpTool[];
     /**
      * 调用一个已发现的 MCP 工具。
      *
@@ -59,7 +59,7 @@ export interface PiMcpHost {
      * 参数和中止信号必须原样交给 Agents SDK，避免另造一套传输生命周期。
      */
     callTool(
-      params: Parameters<MCPClientManager["callTool"]>[0],
+      params: { serverId: string; name: string; arguments?: Record<string, unknown> },
       options?: { signal?: AbortSignal },
     ): Promise<unknown>;
   };
@@ -68,8 +68,12 @@ export interface PiMcpHost {
 // 作用：给一个远端 MCP 工具生成 Pi 模型可见的稳定名称。
 // 调用：候选工厂在映射每个已发现工具时调用。
 // 原因：服务器前缀隔离同名工具，去掉连字符则保持现有 Pi 工具名格式。
-function modelVisibleName(serverId: string, toolName: string): string {
-  return `tool_${serverId.replace(/-/g, "")}_${toolName}`;
+async function modelVisibleName(serverId: string, toolName: string): Promise<string> {
+  const name = `tool_${serverId.replace(/-/g, "")}_${toolName}`;
+  if (/^[A-Za-z0-9_-]{1,64}$/.test(name)) return name;
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify([serverId, toolName])));
+  const hash = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
+  return `mcp_${toolName.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 26)}_${hash.slice(0, 32)}`;
 }
 
 // 作用：把任意 MCP 返回值尽量转换成可展示文本。
@@ -245,6 +249,9 @@ export function createPiMcpToolCandidate(
       requiredExecutionLevel: policy.requiredExecutionLevel,
       requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput,
       source: "action",
+      // Human approval must park a first-class Pi Tool, not a nested Code Mode
+      // RPC whose execution timer continues while the person is deciding.
+      exposureMode: 'direct',
       project: (reply) => {
         const result = normalizeCallResult(reply);
         if (result.isError) throw new Error(errorMessage(result));
@@ -279,16 +286,17 @@ export function createPiMcpToolCandidate(
  *
  * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
  */
-export function createPiMcpToolCandidates(
+export async function createPiMcpToolCandidates(
   host: PiMcpHost,
   configured: readonly RuntimeMcpServer[],
-): PiToolCandidate[] {
+): Promise<PiToolCandidate[]> {
   // TODO(待确认)：Runtime 配置目前只 trim URL，而 agents@0.19.0 会用
   // new URL(url).href 保存连接地址；`https://x` 与 `https://x/`
   // 可能因此精确匹配失败。
   const configuredUrls = new Set(
-    configured.map((server) => server.url),
+    configured.filter(server => !server.id).map((server) => server.url),
   );
+  const configuredIds = new Map(configured.filter(server => server.id).map(server => [server.id!, server.url]));
   const selectedUrls = new Set<string>();
   const selectedServerIds: string[] = [];
 
@@ -297,24 +305,24 @@ export function createPiMcpToolCandidates(
   )) {
     if (
       server.state !== "ready" ||
-      !configuredUrls.has(server.server_url) ||
-      selectedUrls.has(server.server_url)
+      !(configuredIds.get(serverId) === server.server_url || configuredUrls.has(server.server_url)) ||
+      (!configuredIds.has(serverId) && selectedUrls.has(server.server_url))
     ) {
       continue;
     }
-    selectedUrls.add(server.server_url);
+    if (!configuredIds.has(serverId)) selectedUrls.add(server.server_url);
     selectedServerIds.push(serverId);
   }
   if (selectedServerIds.length === 0) return [];
 
   const selectedIds = new Set(selectedServerIds);
-  return host.mcp
+  return Promise.all(host.mcp
     .listTools({
       serverId: selectedServerIds,
       state: "ready",
     })
     .filter((tool) => selectedIds.has(tool.serverId))
-    .map((mcpTool) => createPiMcpToolCandidate(
+    .map(async (mcpTool) => createPiMcpToolCandidate(
       mcpTool,
       (args, signal) => host.mcp.callTool(
         {
@@ -326,10 +334,10 @@ export function createPiMcpToolCandidates(
       ),
       {
         owner: `mcp:${mcpTool.serverId}`,
-        modelName: modelVisibleName(mcpTool.serverId, mcpTool.name),
+        modelName: await modelVisibleName(mcpTool.serverId, mcpTool.name),
         // Remote MCP annotations are untrusted; all user-configured methods
         // retain the existing high-risk approval policy.
         requiredExecutionLevel: "high",
       },
-    ));
+    )));
 }

package/src/pi/tool/subagent.ts

@@ -82,9 +82,6 @@ async function recordSubagentResult(
       runId: run.runId,
       subagentRunId: run.runId,
       parentRunId: lifecycle.parentRunId,
-      ...(lifecycle.accountId ? { accountId: lifecycle.accountId } : {}),
-      ...(lifecycle.rateVersion !== undefined ? { rateVersion: lifecycle.rateVersion } : {}),
-      ...(lifecycle.slotIdentity ? { slotIdentity: lifecycle.slotIdentity } : {}),
       kind: "subagent",
       status,
       usage: run.usage,
@@ -157,9 +154,6 @@ export function subagentPiToolCandidates(
               parentRunId: lifecycle.parentRunId,
               submissionId: lifecycle.submissionId,
               ...(reserved ? { subagentRunId: reserved.runId } : {}),
-              ...(lifecycle.accountId ? { accountId: lifecycle.accountId } : {}),
-              ...(lifecycle.rateVersion !== undefined ? { rateVersion: lifecycle.rateVersion } : {}),
-              ...(lifecycle.slotIdentity ? { slotIdentity: lifecycle.slotIdentity } : {}),
             }
           : undefined;
         const run = lifecycle && reserved
@@ -239,9 +233,6 @@ export function subagentPiToolCandidates(
               parentRunId: lifecycle.parentRunId,
               submissionId: lifecycle.submissionId,
               ...(reserved ? { subagentRunId: reserved.runId } : {}),
-              ...(lifecycle.accountId ? { accountId: lifecycle.accountId } : {}),
-              ...(lifecycle.rateVersion !== undefined ? { rateVersion: lifecycle.rateVersion } : {}),
-              ...(lifecycle.slotIdentity ? { slotIdentity: lifecycle.slotIdentity } : {}),
             }
           : {}),
       };

package/src/pi/tool/workspace-state-connector.ts

@@ -1,3 +1,4 @@
+import { STATE_TYPES } from "@cloudflare/shell";
 import type { StateBackend } from "@cloudflare/shell/workers";
 import { StateConnector } from "@cloudflare/shell/workers";
 import type { ConnectorTools } from "@cloudflare/codemode";
@@ -11,6 +12,25 @@ type WorkspaceFilePage =
   | { kind: "csv"; size: number; nextOffset: number | null; columns: string[] | null; rows: string[][] };
 `;
 
+export const WORKSPACE_STATE_TYPES = `${READ_FILE_PAGE_TYPES}\n${STATE_TYPES.replace(
+  /\n\};$/u,
+  '\n  /** CSV pages have columns and rows; never data. Omit offset first, then pass nextOffset until null. */\n  readFilePage(args: { path: string; offset?: number }): Promise<WorkspaceFilePage | null>;\n};',
+)}`;
+
+export const WORKSPACE_PAGING_INSTRUCTIONS = `For CSV files, do not make a separate probe read or return page contents. Inspect columns and aggregate rows in the same execution with this loop shape:
+
+let page = await state.readFilePage({ path });
+if (!page || page.kind !== "csv") throw new Error("CSV not found");
+const columns = page.columns;
+for (;;) {
+  // Aggregate page.rows here. Do not return raw rows.
+  if (page.nextOffset === null) break;
+  page = await state.readFilePage({ path, offset: page.nextOffset });
+}
+return summary;
+
+CSV pages use page.columns and page.rows; never page.data or page.content. Only the first page has columns. Do not use console.log to inspect a page; explicitly return the final summary.`;
+
 type PagedWorkspacePort = WorkspacePort & {
   readFilePage: NonNullable<WorkspacePort["readFilePage"]>;
 };
@@ -28,19 +48,7 @@ export class WorkspaceStateConnector extends StateConnector {
     const base = super.instructions();
     return `${base}
 
-For CSV files, do not make a separate probe read or return page contents. Inspect columns and aggregate rows in the same execution with this loop shape:
-
-let page = await state.readFilePage({ path });
-if (!page || page.kind !== "csv") throw new Error("CSV not found");
-const columns = page.columns;
-for (;;) {
-  // Aggregate page.rows here. Do not return raw rows.
-  if (page.nextOffset === null) break;
-  page = await state.readFilePage({ path, offset: page.nextOffset });
-}
-return summary;
-
-CSV pages use page.columns and page.rows; never page.data or page.content. Only the first page has columns. Do not use console.log to inspect a page; explicitly return the final summary.`;
+${WORKSPACE_PAGING_INSTRUCTIONS}`;
   }
 
   protected override tools(): ConnectorTools {
@@ -51,7 +59,7 @@ CSV pages use page.columns and page.rows; never page.data or page.content. Only
       readFile: {
         ...readFile,
         description:
-          `Read a small non-CSV file as text. CSV and files over ${WORKSPACE_DIRECT_TEXT_READ_MAX_BYTES} bytes must use readFilePage.`,
+          `${readFile.description} CSV and files over ${WORKSPACE_DIRECT_TEXT_READ_MAX_BYTES} bytes must use readFilePage.`,
         execute: async (args, context) => {
           const path = requiredPath(args, "readFile");
           const file = await this.workspace.stat(path);
@@ -95,12 +103,7 @@ CSV pages use page.columns and page.rows; never page.data or page.content. Only
   }
 
   override async getTypeScriptTypes(): Promise<string> {
-    const types = await super.getTypeScriptTypes();
-    const addition = [
-      "  /** CSV pages have columns and rows; never data. Omit offset first, then pass nextOffset until null. */",
-      "  readFilePage(args: { path: string; offset?: number }): Promise<WorkspaceFilePage | null>;",
-    ].join("\n");
-    return `${READ_FILE_PAGE_TYPES}\n${types.replace(/\n\};$/u, `\n${addition}\n};`)}`;
+    return WORKSPACE_STATE_TYPES;
   }
 }
 

package/src/runtime-agent.ts

@@ -96,6 +96,11 @@ interface RuntimeAgentDefinitionBase<
   /** 必须等于 Worker 导出名（Wrangler `class_name`）。 */
   readonly name: string;
 
+  /** Refresh Host-owned inputs before a new Submission is pinned. Never runs on continuation/recovery. */
+  readonly beforeSubmission?: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+  ) => Promise<boolean>;
+
   readonly load: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     requestedRuntimeKey?: string,
@@ -444,6 +449,12 @@ export function defineRuntimeAgent<
         return this.ensureConfig();
       }
 
+      protected async prepareRuntimeForSubmission(): Promise<void> {
+        const beforeSubmission = definition.beforeSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["beforeSubmission"];
+        const changed = await beforeSubmission?.(this.createDefinitionContext());
+        await this.ensureConfig(undefined, changed === true);
+      }
+
       // 作用：加载默认 Runtime，或切换到调用方指定的 key。
       // 调用：RPC 控制面在业务配置需要刷新时调用。
       // 原因：复用 `ensureConfig`，让手动重载遵守和首次启动相同的原子规则。

package/src/runtime-assembler.ts

@@ -1,6 +1,7 @@
 import type { SkillSource } from "agents/skills";
 import type {
   RuntimeGatewayPort,
+  RuntimeMcpHost,
   RuntimeMemoryPort,
   RuntimePlatformPort,
   RuntimeProviderPort,
@@ -95,6 +96,7 @@ export interface RuntimeAssemblyInput {
   readonly skills: readonly RuntimeSkillContribution[];
   readonly connectors: readonly RuntimeMcpServer[];
   readonly gateway?: RuntimeGatewayPort;
+  readonly managedMcp?: RuntimeMcpHost;
   readonly extensions: readonly RuntimeExtensionContribution[];
   readonly subagents?: RuntimeSubagentPort;
   readonly schedule?: RuntimeSchedulePort;
@@ -368,6 +370,7 @@ class RuntimeBuilder {
   private provider?: RuntimeProviderPort;
   private platform?: RuntimePlatformPort;
   private gateway?: RuntimeGatewayPort;
+  private managedMcp?: RuntimeMcpHost;
   private workspace?: WorkspacePort;
   private codeExecution?: RuntimeCodeExecutionFactory;
   private sandbox?: RuntimeSandboxPort;
@@ -416,6 +419,10 @@ class RuntimeBuilder {
     for (const skill of input.skills) this.addSkill(skill);
     for (const connector of input.connectors) this.addConnector(connector);
     this.gateway = input.gateway;
+    this.managedMcp = input.managedMcp;
+    for (const server of input.managedMcp?.servers ?? []) {
+      this.addConnector({ ...server, hostManaged: true });
+    }
     for (const { name, extension } of input.extensions) {
       this.addExtension(name, extension);
     }
@@ -478,13 +485,15 @@ class RuntimeBuilder {
 
   private addConnector(server: RuntimeMcpServer): void {
     const name = requiredName(server.name, "Connector");
-    if (this.connectors.has(name)) {
+    const identity = server.id ?? name;
+    if (this.connectors.has(identity)) {
       throw new Error(`Duplicate Runtime Connector: ${name}`);
     }
     if (!server.url.trim()) {
       throw new Error(`Runtime Connector "${name}" URL must not be empty`);
     }
-    this.connectors.set(name, Object.freeze({
+    this.connectors.set(identity, Object.freeze({
+      ...server,
       name,
       url: server.url.trim(),
     }));
@@ -644,6 +653,7 @@ class RuntimeBuilder {
       platform: Object.freeze({ ...this.platform }),
       ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
       ...(this.gateway ? { gateway: this.gateway } : {}),
+      ...(this.managedMcp ? { mcp: this.managedMcp } : {}),
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: this.memory }
@@ -805,6 +815,7 @@ export async function assembleRuntimeSnapshot<
         ? [...BUILT_IN_RUNTIME_SKILLS, ...resources.skills]
         : resources.skills,
     connectors: resources.connectors.servers,
+    managedMcp: resources.connectors.managed,
     ...(resources.connectors.gateway
       ? { gateway: resources.connectors.gateway }
       : {}),

package/src/runtime-definition.ts

@@ -2,6 +2,7 @@ import type { SkillSource } from "agents/skills";
 import type { ExecutionLevel } from "./lib/execution-level";
 import type {
   RuntimeGatewayPort,
+  RuntimeMcpHost,
   RuntimePlatformPort,
   RuntimeProviderPort,
   RuntimeSkillScriptPolicy,
@@ -79,6 +80,7 @@ export type { RuntimeAgentContext, RuntimeAssemblyContext } from "./runtime-agen
 export interface ResolvedConnectors {
   readonly servers: readonly RuntimeMcpServer[];
   readonly gateway?: RuntimeGatewayPort;
+  readonly managed?: RuntimeMcpHost;
   readonly degradations: readonly RuntimeDegradation[];
 }