@springbrand/agent-runtime 0.1.3-alpha.4 → 0.1.3-alpha.6

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

@@ -0,0 +1,175 @@
+import {
+  Agent,
+  type AgentEvent,
+  type AgentTool,
+  type StreamFn,
+} from "@earendil-works/pi-agent-core";
+import type {
+  Api,
+  AssistantMessage,
+  Model,
+} from "@earendil-works/pi-ai";
+import { z } from "zod";
+import { assembleSubagentPrompt } from "../../../lib/prompt";
+import type { AgentType } from "../../../layers/orchestration/subagents/agent-types/contract";
+
+const RECURSIVE_TOOLS = new Set([
+  "run_agent",
+  "subagents",
+  "fanout",
+  "extract",
+  "dispatch_background",
+]);
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface CloudflareSubAgentRun {
+  type: AgentType;
+  input: unknown;
+  model: Model<Api>;
+  streamFn: StreamFn;
+  tools: AgentTool[];
+  getApiKey?: (provider: string) => string | undefined;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  onEvent?: (event: AgentEvent, signal: AbortSignal) => void | Promise<void>;
+}
+
+function textOf(message: AssistantMessage): string {
+  return message.content
+    .flatMap((part) => (part.type === "text" ? [part.text] : []))
+    .join("")
+    .trim();
+}
+
+function toolErrorText(result: unknown): string {
+  if (
+    typeof result === "object" &&
+    result !== null &&
+    Array.isArray((result as { content?: unknown }).content)
+  ) {
+    const text = (result as { content: unknown[] }).content
+      .flatMap((part) =>
+        typeof part === "object" &&
+        part !== null &&
+        (part as { type?: unknown }).type === "text" &&
+        typeof (part as { text?: unknown }).text === "string"
+          ? [(part as { text: string }).text]
+          : [],
+      )
+      .join("")
+      .trim();
+    if (text) return text;
+  }
+  return "tool execution failed";
+}
+
+function taskPrompt(type: AgentType, input: unknown): string {
+  return [
+    "Complete this bounded task.",
+    `Input:\n${JSON.stringify(input)}`,
+    `Return only one JSON object matching this schema:\n${JSON.stringify(z.toJSONSchema(type.outputSchema))}`,
+  ].join("\n\n");
+}
+
+export async function runCloudflareSubAgent(
+  run: CloudflareSubAgentRun,
+): Promise<unknown> {
+  const input = run.type.inputSchema.safeParse(run.input);
+  if (!input.success) {
+    throw new Error(
+      `SubAgent input failed schema validation: ${input.error.message}`,
+    );
+  }
+  for (const tool of run.tools) {
+    if (RECURSIVE_TOOLS.has(tool.name)) {
+      throw new Error(`SubAgent cannot use recursive tool "${tool.name}"`);
+    }
+  }
+  if (run.signal?.aborted) throw new Error("SubAgent run aborted");
+
+  // 这里没有审批闸,也装不了:到这一步工具已经被 compilePiTools 编译成 AgentTool,
+  // requiredExecutionLevel 只挂在编译前的 PiToolCandidate 上,这里读不到。「子 agent 不许挂需审批的工具」
+  // 这条不变量由装配处 createCloudflareSubAgentTools 的启动期断言强制执行。
+  const agent = new Agent({
+    streamFn: run.streamFn,
+    getApiKey: run.getApiKey,
+    initialState: {
+      model: run.model,
+      systemPrompt: assembleSubagentPrompt(run.type.persona),
+      thinkingLevel: run.type.model === "main" ? "medium" : "off",
+      messages: [],
+      tools: run.tools,
+    },
+  });
+  let toolFailure: { name: string; error: string } | undefined;
+  agent.subscribe(async (event, signal) => {
+    if (event.type === "tool_execution_end" && event.isError) {
+      toolFailure ??= {
+        name: event.toolName,
+        error: toolErrorText(event.result),
+      };
+    }
+    await run.onEvent?.(event, signal);
+  });
+
+  let timedOut = false;
+  const abort = () => agent.abort();
+  run.signal?.addEventListener("abort", abort, { once: true });
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    agent.abort();
+  }, run.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+  try {
+    await agent.prompt(taskPrompt(run.type, input.data));
+  } finally {
+    clearTimeout(timeout);
+    run.signal?.removeEventListener("abort", abort);
+  }
+
+  if (timedOut) throw new Error("SubAgent run timed out");
+  if (run.signal?.aborted) throw new Error("SubAgent run aborted");
+
+  const assistant = agent.state.messages
+    .slice()
+    .reverse()
+    .find(
+      (message): message is AssistantMessage => message.role === "assistant",
+    );
+  if (!assistant) throw new Error("SubAgent produced no structured output");
+  if (assistant.stopReason === "aborted") {
+    throw new Error("SubAgent run aborted");
+  }
+  if (assistant.stopReason === "error") {
+    if (toolFailure) {
+      throw new Error(
+        `SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`,
+      );
+    }
+    throw new Error(
+      `SubAgent model failed: ${assistant.errorMessage ?? "unknown provider error"}`,
+    );
+  }
+  if (toolFailure) {
+    throw new Error(
+      `SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`,
+    );
+  }
+
+  const text = textOf(assistant);
+  if (!text) throw new Error("SubAgent produced no structured output");
+
+  let output: unknown;
+  try {
+    output = JSON.parse(text);
+  } catch {
+    throw new Error("SubAgent output is not valid JSON");
+  }
+  const result = run.type.outputSchema.safeParse(output);
+  if (!result.success) {
+    throw new Error(
+      `SubAgent output failed schema validation: ${result.error.message}`,
+    );
+  }
+  return result.data;
+}

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

@@ -0,0 +1,254 @@
+import {
+  DynamicWorkerExecutor,
+  resolveProvider,
+  runCode,
+} from "@cloudflare/codemode";
+import {
+  createWorkspaceStateBackend,
+  type WorkspaceFsLike,
+} from "@cloudflare/shell";
+import { stateToolsFromBackend } from "@cloudflare/shell/workers";
+import type {
+  AgentTool,
+  AgentToolResult,
+} from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type { WorkspacePort } from "../../../kernel/bindings";
+import type { AgentType } from "../../../layers/orchestration/subagents/agent-types/contract";
+import {
+  compilePiTools,
+  type CompilePiToolsOptions,
+  type PiToolCandidate,
+} from "../../../pi/tool";
+import { workspacePiToolCandidates } from "../../../pi/tool/workspace-sandbox";
+
+const READONLY_WORKSPACE_TOOLS = new Set([
+  "read",
+  "list",
+  "find",
+  "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",
+  "extract",
+  "dispatch_background",
+];
+const MAX_FETCH_BODY_BYTES = 50_000;
+
+const executeParameters = Type.Object({
+  code: Type.String({
+    minLength: 1,
+    description:
+      "JavaScript to run. Return the final value. The sandbox provides fetch and state.*.",
+  }),
+});
+
+const fetchParameters = Type.Object({
+  url: Type.String({ minLength: 1, maxLength: 8_192 }),
+});
+
+function result(details: unknown): AgentToolResult<unknown> {
+  let text: string;
+  try {
+    text = JSON.stringify(details);
+  } catch {
+    text = String(details);
+  }
+  return {
+    content: [{ type: "text", text }],
+    details,
+  };
+}
+
+function executeCandidate(options: {
+  workspace: WorkspacePort;
+  loader: WorkerLoader;
+  outbound: Fetcher;
+}): PiToolCandidate {
+  const executor = new DynamicWorkerExecutor({
+    loader: options.loader,
+    globalOutbound: options.outbound,
+  });
+  const state = resolveProvider(
+    stateToolsFromBackend(
+      createWorkspaceStateBackend(
+        options.workspace as unknown as WorkspaceFsLike,
+      ),
+    ),
+  );
+  const tool: AgentTool<typeof executeParameters> = {
+    name: "execute",
+    label: "Execute JavaScript",
+    description:
+      "Run JavaScript in an isolated Worker with controlled network access and this Chat's scoped " +
+      "Workspace exposed as state.*. Return the final value from the script.",
+    parameters: executeParameters,
+    async execute(_toolCallId, { code }, signal, onUpdate) {
+      signal?.throwIfAborted();
+      onUpdate?.(
+        result({ status: "running", message: "Executing sandbox code." }),
+      );
+      const output = await runCode({
+        code,
+        executor,
+        providers: [state],
+      });
+      signal?.throwIfAborted();
+      return result(output);
+    },
+  };
+  return {
+    owner: "subagent-execute",
+    requiredExecutionLevel: "safe",
+    tool,
+  };
+}
+
+async function boundedBody(
+  response: Response,
+): Promise<{ body: string; truncated: boolean }> {
+  const reader = response.body?.getReader();
+  if (!reader) return { body: "", truncated: false };
+
+  const decoder = new TextDecoder();
+  let body = "";
+  let bytes = 0;
+  let truncated = false;
+  try {
+    while (bytes < MAX_FETCH_BODY_BYTES) {
+      const next = await reader.read();
+      if (next.done) {
+        body += decoder.decode();
+        return { body, truncated };
+      }
+      const remaining = MAX_FETCH_BODY_BYTES - bytes;
+      const value = next.value;
+      const accepted =
+        value.byteLength > remaining ? value.subarray(0, remaining) : value;
+      bytes += accepted.byteLength;
+      body += decoder.decode(accepted, { stream: true });
+      if (accepted.byteLength < value.byteLength) {
+        truncated = true;
+        break;
+      }
+    }
+    if (bytes >= MAX_FETCH_BODY_BYTES) truncated = true;
+    body += decoder.decode();
+    return { body, truncated };
+  } finally {
+    if (truncated) await reader.cancel().catch(() => {});
+    else reader.releaseLock();
+  }
+}
+
+function fetchCandidate(options: {
+  outbound: Fetcher;
+}): PiToolCandidate {
+  const tool: AgentTool<typeof fetchParameters> = {
+    name: "fetch_url",
+    label: "Fetch URL",
+    description:
+      "Fetch one HTTPS URL and return its status, headers, and a bounded text body.",
+    parameters: fetchParameters,
+    async execute(_toolCallId, { url }, signal, onUpdate) {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:") {
+        throw new Error("fetch_url only allows HTTPS URLs");
+      }
+      onUpdate?.(
+        result({ status: "running", message: `Fetching ${parsed.host}.` }),
+      );
+      signal?.throwIfAborted();
+      const response = await options.outbound.fetch(
+        new Request(parsed.toString(), { signal }),
+      );
+      const { body, truncated } = await boundedBody(response);
+      return result({
+        url: response.url,
+        status: response.status,
+        statusText: response.statusText,
+        headers: Object.fromEntries(response.headers),
+        body,
+        truncated,
+      });
+    },
+  };
+  return {
+    owner: "subagent-fetch",
+    requiredExecutionLevel: "safe",
+    tool,
+  };
+}
+
+/**
+ * SubAgent 链路上没有审批通道:主链的审批闸在 Runtime 的 execution 适配器里
+ * (requiresPiToolApproval → park → 等用户裁决),而子 agent 是 `new Agent({ tools })`
+ * 直接跑,parked 的请求没有任何界面能落地、也没有人能批。
+ *
+ * 只有 `safe` Tool 可以挂到这条没有审批通道的链路；更高档位必须在装配时失败关闭。
+ *
+ * 所以把这个不变量钉在装配处:要的是「装不上」,不是「跑起来才炸」。而且这里是唯一还能
+ * 检查的位置 —— 档位挂在 PiToolCandidate 上,compilePiTools 之后只剩 AgentTool。
+ */
+function assertSafeExecutionLevel(
+  candidates: readonly PiToolCandidate[],
+): void {
+  const risky = candidates.filter(
+    (candidate) => candidate.requiredExecutionLevel !== "safe",
+  );
+  if (risky.length === 0) return;
+  throw new Error(
+    "SubAgent tools must require safe execution level: " +
+      risky
+        .map((candidate) =>
+          `${candidate.tool.name} (${candidate.requiredExecutionLevel})`
+        )
+        .join(", ") +
+      ". The SubAgent chain has no approval channel, so a tool that needs " +
+      "approval would execute unreviewed. Wire an approval channel into the " +
+      "SubAgent run before mounting it.",
+  );
+}
+
+/**
+ * Assemble the complete Pi-native tool surface for one already-scoped
+ * SubAgent run. The caller owns Workspace scoping and network egress.
+ */
+export function createCloudflareSubAgentTools(options: {
+  profile: AgentType["tools"];
+  workspace: WorkspacePort;
+  loader: WorkerLoader;
+  outbound: Fetcher;
+  settle: CompilePiToolsOptions["settle"];
+}): AgentTool[] {
+  const workspace = workspacePiToolCandidates(options.workspace).filter(
+    (candidate) =>
+      options.profile === "capable" ||
+      READONLY_WORKSPACE_TOOLS.has(candidate.tool.name),
+  );
+  const candidates =
+    options.profile === "capable"
+      ? [
+          ...workspace,
+          executeCandidate(options),
+          fetchCandidate(options),
+        ]
+      : [...workspace, fetchCandidate(options)];
+
+  // 子 Agent 是独立的嵌套 Tool surface：先移除会递归委派的候选，
+  // compiler 只负责执行治理和结算。
+  const deny = new Set(DENIED_TOOLS);
+  const mounted = candidates.filter(
+    (candidate) => !deny.has(candidate.tool.name),
+  );
+  assertSafeExecutionLevel(mounted);
+
+  return compilePiTools(mounted, {
+    settle: options.settle,
+  });
+}

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

@@ -0,0 +1,35 @@
+import type { RuntimeTurnEventsPort } from "../../../kernel/bindings";
+import type { RuntimeAgentHooks } from "../../../runtime-definition";
+
+export function createUniversalAgentHooks<
+  Env extends Cloudflare.Env,
+  Config,
+  Command = never,
+  Change = never,
+>(adapter: {
+  guard(config: Config): Promise<void>;
+  turnEvents(): RuntimeTurnEventsPort | Promise<RuntimeTurnEventsPort>;
+}): RuntimeAgentHooks<Env, Config, Command, Change> {
+  const turnEvents = () => Promise.resolve(adapter.turnEvents());
+  return {
+    beforeCommit: [async (_context, config) => adapter.guard(config)],
+    onTurnEnd: async (_context, messages) => {
+      await (await turnEvents()).onResponse(messages);
+    },
+    onModelUsage: async (event) => {
+      await (await turnEvents()).onModelUsage?.(event);
+    },
+    onToolSettled: async (event) => {
+      await (await turnEvents()).onToolSettled?.(event);
+    },
+    onApproval: async (input) => {
+      await (await turnEvents()).onApproval?.(input);
+    },
+    onActivityChanged: async (projection) => {
+      await (await turnEvents()).onActivityChanged?.(projection);
+    },
+    onSubmissionTerminal: async (input) => {
+      await (await turnEvents()).onSubmissionTerminal?.(input);
+    },
+  };
+}