@springbrand/agent-runtime 0.1.0

package/src/pi/tool/subagent.ts

@@ -0,0 +1,148 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import { z } from "zod";
+import type { RuntimeSubagentPort } from "../../kernel/bindings";
+import { AGENT_TYPES } from "../../layers/orchestration/subagents/agent-types/registry";
+import { serializeOutput } from "../../lib/artifacts";
+import type { PiToolCandidate } from "./compiler";
+
+const BACKGROUND_MAX_BUDGET_MS = 10 * 60 * 1_000;
+
+// 作用：把 SubAgent 的结构化值包装成 Pi 可读的工具结果。
+// 调用：前台执行、前台失败和后台派发成功后调用。
+// 原因：模型读取序列化文本，Runtime 事件继续保留原始 details，
+// 避免两套结果格式漂移。
+function result(details: unknown, modelValue = details): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: serializeOutput(modelValue).text }],
+    details,
+  };
+}
+
+// 作用：为没有正常完成的前台 SubAgent 生成稳定失败值。
+// 调用：AgentType 工具发现 run 状态不是 completed 或没有 output 时调用。
+// 原因：子任务失败是一次已完成的工具结果而不是适配器异常，
+// 保留状态能让主 Agent 决定后续动作。
+function failure(agentType: string, status: string, error?: string) {
+  // TODO(待确认)：Host 当前没有把 Agents SDK 的 retryable、reason 和
+  // childStillRunning 投影进 RuntimeSubagentPort，
+  // 主 Agent 无法据此区分可重试中断。
+  return {
+    ok: false as const,
+    agentType,
+    status,
+    error: error ?? "sub-agent did not complete",
+  };
+}
+
+/**
+ * 把已启用的 SubAgent 类型转换成 Pi 候选工具。
+ *
+ * Worker 的 SubAgent Plugin 在绑定执行端口后调用它。调用方应传入该 Runtime
+ * 快照启用的类型名称；未注册名称会被忽略，没有端口或没有有效类型时不公开工具。
+ *
+ * 这里的 “AgentType” 是注册表中的输入 Schema、说明和显示名称，“前台执行”
+ * 会等待子任务结果，“后台派发”只返回 runId，并由 Host 通过通知把最终结果送回
+ * 当前会话。注册表同时生成工具 Schema 和再次校验后台 input，不能改成两份定义。
+ *
+ * `Host`、`Pi`、`Port`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
+ */
+export function subagentPiToolCandidates(
+  subagents: RuntimeSubagentPort | undefined,
+  enabledSubagents: readonly string[],
+): PiToolCandidate[] {
+  if (!subagents) return [];
+  const types = [...new Set(enabledSubagents)].flatMap((name) => {
+    const type = AGENT_TYPES.byName[name];
+    return type ? [type] : [];
+  });
+  if (types.length === 0) return [];
+
+  // TODO(待确认)：RuntimeSubagentPort.run 目前不接收 AbortSignal；两个 execute
+  // 只能在启动前拒绝已取消调用，
+  // 开始后的子任务可能无法跟随父工具取消。
+  const candidates = types.map((type): PiToolCandidate => {
+    const tool: AgentTool<any, unknown> = {
+      name: type.name,
+      label: type.displayName,
+      description: type.description,
+      parameters: z.toJSONSchema(
+        type.inputSchema,
+      ) as AgentTool["parameters"],
+      // 作用：运行一种已启用的前台 SubAgent，
+      // 并把完成或失败状态返回主 Agent。
+      // 调用：Pi 选择对应 AgentType 工具并通过其 Schema 校验后调用。
+      // 原因：执行细节留给 RuntimeSubagentPort；
+      // 适配层只固定类型名并统一结果语义。
+      async execute(_toolCallId, input, signal) {
+        signal?.throwIfAborted();
+        const run = await subagents.run(
+          type.name,
+          input as Record<string, unknown>,
+        );
+        if (run.status !== "completed" || run.output === undefined) {
+          return result(failure(type.name, run.status, run.error));
+        }
+        return result(run.output);
+      },
+    };
+    return {
+      owner: `subagent:${type.name}`,
+      authorized: true,
+      requiredExecutionLevel: "safe",
+      tool,
+    };
+  });
+
+  const typeNames = types.map(({ name }) => name) as [string, ...string[]];
+  const parameters = z.object({
+    agentType: z.enum(typeNames),
+    input: z.record(z.string(), z.unknown()),
+  });
+  const background: AgentTool<any, unknown> = {
+    name: "dispatch_background",
+    label: "Dispatch background SubAgent",
+    description:
+      "Dispatch a bounded sub-agent job in the background. Returns a runId; " +
+      "the structured result is injected into this chat when complete.",
+    parameters: z.toJSONSchema(parameters) as AgentTool["parameters"],
+    // 作用：派发一个有时间预算的后台 SubAgent，并立即返回运行标识。
+    // 调用：Pi 需要子任务异步进行、不应阻塞当前 Turn 时调用。
+    // 原因：先用具体 AgentType Schema 复核嵌套 input，
+    // 再把 detached 和通知语义交给 Host，避免后台入口绕过类型约束。
+    async execute(_toolCallId, value, signal) {
+      signal?.throwIfAborted();
+      const input = value as z.infer<typeof parameters>;
+      const parsed = AGENT_TYPES.byName[input.agentType]!.inputSchema.safeParse(
+        input.input,
+      );
+      if (!parsed.success) {
+        throw new Error(
+          `SubAgent input failed schema validation: ${parsed.error.message}`,
+        );
+      }
+      const run = await subagents.run(
+        input.agentType,
+        parsed.data as Record<string, unknown>,
+        {
+          detached: true,
+          maxBudgetMs: BACKGROUND_MAX_BUDGET_MS,
+          notifySource: "dispatch-background",
+        },
+      );
+      return result({
+        runId: run.runId,
+        status: run.status,
+        agentType: input.agentType,
+      });
+    },
+  };
+  candidates.push({
+    owner: "subagent:background",
+    authorized: true,
+    requiredExecutionLevel: "low",
+    summary: "Dispatch a background sub-agent",
+    source: "action",
+    tool: background,
+  });
+  return candidates;
+}