@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.10

package/src/pi/tool/mcp.ts

@@ -9,10 +9,26 @@ interface McpCallResult {
   isError?: boolean;
 }
 
+export interface PiDiscoveredMcpTool {
+  readonly serverId: string;
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+  readonly annotations?: { readonly title?: string } & Record<string, unknown>;
+}
+
+interface PiMcpCandidatePolicy {
+  readonly owner: string;
+  readonly modelName: string;
+  readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
+  readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+}
+
 /**
  * Pi 的 MCP 适配器所需的最小 Host 能力。
  *
- * `PreparedAssembly` 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
+ * Tool Surface 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
  * 提供同样的服务器状态快照、工具目录和调用能力，不要在这里复制连接状态。
  *
  * 这里沿用 MCP 的官方术语：Host 是承载 Agent 的应用，Client 是 Host 内连接
@@ -43,7 +59,8 @@ export interface PiMcpHost {
      * 参数和中止信号必须原样交给 Agents SDK，避免另造一套传输生命周期。
      */
     callTool(
-      ...args: Parameters<MCPClientManager["callTool"]>
+      params: Parameters<MCPClientManager["callTool"]>[0],
+      options?: { signal?: AbortSignal },
     ): Promise<unknown>;
   };
 }
@@ -200,16 +217,76 @@ function errorMessage(result: McpCallResult): string {
     : "MCP tool call failed";
 }
 
+/** 共享 MCP 结果投影；Gateway 与用户配置的 Remote MCP 均经过此边界。 */
+export function createPiMcpToolCandidate(
+  mcpTool: PiDiscoveredMcpTool,
+  callTool: (
+    input: Readonly<Record<string, unknown>>,
+    signal?: AbortSignal,
+  ) => Promise<unknown>,
+  policy: PiMcpCandidatePolicy,
+): PiToolCandidate {
+  const label =
+    mcpTool.title ??
+    mcpTool.annotations?.title ??
+    mcpTool.name;
+  const tool: AgentTool<any, {
+    kind: "mcp";
+    toolName: string;
+  }> = {
+    name: policy.modelName,
+    label,
+    description: mcpTool.description ?? label,
+    parameters: structuredClone(
+      mcpTool.inputSchema ?? {
+        type: "object",
+        additionalProperties: true,
+      },
+    ) as AgentTool["parameters"],
+    execute: async (_toolCallId, args, signal) => {
+      const result = normalizeCallResult(
+        await callTool(args as Record<string, unknown>, signal),
+      );
+      if (result.isError) throw new Error(errorMessage(result));
+      const structuredContent = result.structuredContent === undefined
+        ? undefined
+        : publicMcpValue(result.structuredContent);
+      const content = resultContent({ ...result, structuredContent });
+      return {
+        content,
+        details: {
+          kind: "mcp",
+          toolName: mcpTool.name,
+          output: structuredContent ?? content,
+        },
+      };
+    },
+  };
+  return {
+    owner: policy.owner,
+    tool,
+    summary: label,
+    requiredExecutionLevel: policy.requiredExecutionLevel,
+    ...(policy.requiredExecutionLevelForInput
+      ? {
+          requiredExecutionLevelForInput:
+            policy.requiredExecutionLevelForInput,
+        }
+      : {}),
+    source: "action",
+  };
+}
+
 /**
- * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
+ * 把当前已配置且 ready 的 MCP 工具转换成 Pi 候选工具。
  *
- * `PreparedAssembly.toolCandidates()` 在每次收集本轮工具时调用它。调用方应传入
+ * Tool Surface 在 Runtime 准备时调用它。调用方应传入
  * Agent Host，以及同一 Runtime 快照中的 MCP 配置；未就绪、未配置或重复 URL
  * 的连接不会进入模型工具目录。
  *
  * “候选工具”是进入 Pi 编译和统一治理前的内部描述。连接、凭据和恢复由 Host
- * 与 Agents SDK 管理；本函数只做授权快照过滤、Schema 转接和公开结果投影。
- * 远端 Server 提供的 annotations 只是提示，不是本地授权边界，所以所有动态
+ * 与 Agents SDK 管理；本函数只做动态连接状态过滤、Schema 转接和公开结果投影。
+ * 远端 Server 提供的 annotations 只是提示，不是本地审批边界，所以所有动态
  * MCP 工具继续标为高风险，不能据此绕过审批。
  *
  * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
@@ -249,71 +326,22 @@ export function createPiMcpToolCandidates(
       state: "ready",
     })
     .filter((tool) => selectedIds.has(tool.serverId))
-    .map((mcpTool): PiToolCandidate => {
-      const label =
-        mcpTool.title ??
-        mcpTool.annotations?.title ??
-        mcpTool.name;
-      const tool: AgentTool<any, {
-        kind: "mcp";
-        toolName: string;
-      }> = {
-        name: modelVisibleName(mcpTool.serverId, mcpTool.name),
-        label,
-        description: mcpTool.description ?? label,
-        parameters: structuredClone(
-          mcpTool.inputSchema ?? {
-            type: "object",
-            additionalProperties: true,
-          },
-        ) as AgentTool["parameters"],
-        // 作用：执行模型选中的远端 MCP 工具并返回公开结果。
-        // 调用：Pi 在参数校验和统一工具治理通过后调用。
-        // 原因：调用交给 Agents SDK，并在边界处统一处理错误、
-        // 私有元数据和非原生内容。
-        execute: async (_toolCallId, args, signal) => {
-          const result = normalizeCallResult(
-            await host.mcp.callTool(
-              {
-                serverId: mcpTool.serverId,
-                name: mcpTool.name,
-                arguments: args as Record<string, unknown>,
-              },
-              undefined,
-              { signal },
-            ),
-          );
-          if (result.isError) {
-            throw new Error(errorMessage(result));
-          }
-          const structuredContent =
-            result.structuredContent === undefined
-              ? undefined
-              : publicMcpValue(result.structuredContent);
-          const content = resultContent({
-            ...result,
-            structuredContent,
-          });
-          return {
-            content,
-            details: {
-              kind: "mcp",
-              toolName: mcpTool.name,
-              output: structuredContent ?? content,
-            },
-          };
+    .map((mcpTool) => createPiMcpToolCandidate(
+      mcpTool,
+      (args, signal) => host.mcp.callTool(
+        {
+          serverId: mcpTool.serverId,
+          name: mcpTool.name,
+          arguments: args,
         },
-      };
-      return {
+        { signal },
+      ),
+      {
         owner: `mcp:${mcpTool.serverId}`,
-        authorized: true,
-        tool,
-        summary: label,
-        // MCP annotations are supplied by the remote server and are not an
-        // authorization boundary. Until the Host supplies trusted per-method
-        // policy, every dynamic MCP method must take the approval path.
+        modelName: modelVisibleName(mcpTool.serverId, mcpTool.name),
+        // Remote MCP annotations are untrusted; all user-configured methods
+        // retain the existing high-risk approval policy.
         requiredExecutionLevel: "high",
-        source: "action",
-      };
-    });
+      },
+    ));
 }

package/src/pi/tool/schedule.ts

@@ -10,6 +10,10 @@ import type {
 import type { ScheduleSpec } from "../../kernel/receipts";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 const scheduleTriggerParameters = Type.Union([
   Type.Object({
@@ -71,6 +75,14 @@ const updateScheduleParameters = Type.Object({
   label: Type.Optional(Type.String()),
   timezone: Type.Optional(Type.String()),
 });
+const changeScheduleAgentParameters = Type.Object({
+  id: Type.String({
+    description: "The exact schedule id returned by `list_schedules`.",
+  }),
+  userAgentId: Type.String({
+    description: "The exact User Agent id selected by the user.",
+  }),
+});
 
 function result<T>(details: T): AgentToolResult<T> {
   return {
@@ -82,15 +94,20 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(
   tool: AgentTool<T>,
   options: Partial<
-    Pick<PiToolCandidate, "requiredExecutionLevel" | "summary">
+    Pick<
+      PiToolCandidate,
+      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
+    >
   > = {},
 ): PiToolCandidate {
   return {
-    owner: "runtime-base",
-    authorized: true,
+    owner: options.owner ?? "runtime-base",
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
     tool,
+    ...(options.alwaysRequiresApproval
+      ? { alwaysRequiresApproval: true }
+      : {}),
     ...(options.summary ? { summary: options.summary } : {}),
   };
 }
@@ -99,24 +116,30 @@ export function schedulePiToolCandidates(
   schedule: RuntimeSchedulePort,
 ): PiToolCandidate[] {
   return [
-    candidate({
-      name: "schedule",
-      label: "Schedule prompt",
-      description:
-        "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
-      parameters: scheduleParameters,
-      async execute(_toolCallId, input, signal) {
-        signal?.throwIfAborted();
-        const spec: ScheduleSpec = {
-          trigger: input.trigger,
-          job: { kind: "prompt", prompt: input.prompt },
-          label: input.label,
-          ...(input.timezone ? { tz: input.timezone } : {}),
-        };
-        const { id } = await schedule.create(spec);
-        return result({ scheduled: true, id });
+    candidate(
+      {
+        name: "schedule",
+        label: "Schedule prompt",
+        description:
+          "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
+        parameters: scheduleParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const spec: ScheduleSpec = {
+            trigger: input.trigger,
+            job: { kind: "prompt", prompt: input.prompt },
+            label: input.label,
+            ...(input.timezone ? { tz: input.timezone } : {}),
+          };
+          const { id } = await schedule.create(spec);
+          return result({ scheduled: true, id });
+        },
       },
-    }),
+      {
+        alwaysRequiresApproval: true,
+        summary: "Create a scheduled task",
+      },
+    ),
     candidate({
       name: "list_schedules",
       label: "List schedules",
@@ -194,5 +217,48 @@ export function schedulePiToolCandidates(
         summary: "Cancel a scheduled task",
       },
     ),
+    candidate(
+      {
+        name: "list_user_agents",
+        label: "List User Agents",
+        description:
+          "List the enabled User Agents available for scheduled tasks. " +
+          "Use this before changing a schedule Agent.",
+        parameters: noParameters,
+        async execute(_toolCallId, _input, signal) {
+          signal?.throwIfAborted();
+          return result({ agents: await schedule.listAgents() });
+        },
+      },
+      { owner: "schedule-host" },
+    ),
+    candidate(
+      {
+        name: "change_schedule_agent",
+        label: "Change schedule Agent",
+        description:
+          "Change which User Agent executes one scheduled task without " +
+          "changing its id or history. Call `list_schedules` and " +
+          "`list_user_agents` first and use exact ids; ask the user when " +
+          "the target is ambiguous.",
+        parameters: changeScheduleAgentParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const { ok } = await schedule.changeAgent(
+            input.id,
+            input.userAgentId,
+          );
+          return result({ updated: ok, id: input.id });
+        },
+      },
+      { owner: "schedule-host" },
+    ),
   ];
 }
+
+/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */
+export function createScheduleTools(
+  schedule: RuntimeSchedulePort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates(schedulePiToolCandidates(schedule));
+}