@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.3

package/src/pi/tool/base.ts

@@ -2,7 +2,10 @@ import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
-import { Type, type TSchema } from "@earendil-works/pi-ai";
+import { Type, type Static, type TSchema } from "@earendil-works/pi-ai";
+import { estimateStringTokens } from "agents/experimental/memory/utils";
+import type { RuntimeMemoryPort } from "../../kernel/bindings";
+import type { RuntimeMemoryProfile } from "../../kernel/profile";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
 import { webSearchPiToolCandidate } from "./web-search";
@@ -42,13 +45,63 @@ const updatePlanParameters = Type.Object({
       Type.Literal("pending"),
       Type.Literal("in_progress"),
       Type.Literal("done"),
-    ], { description: "Current status of this step." }),
+    ], {
+      description:
+        'Current status. Use "done" for a finished step; never use "completed".',
+    }),
   }), {
     description:
       "The complete, ordered plan. Overwrites any previously reported plan.",
   }),
 });
 
+type UpdatePlanArguments = Static<typeof updatePlanParameters>;
+
+function normalizeStepStatus(
+  status: unknown,
+): UpdatePlanArguments["steps"][number]["status"] {
+  switch (status) {
+    case "done":
+    case "completed": // Anthropic models sometimes output "completed"
+      return "done";
+    case "in_progress":
+    case "inProgress": // camelCase variant
+      return "in_progress";
+    default: // covers "pending", "todo" (Google), and any other unknown value
+      return "pending";
+  }
+}
+
+export function normalizeUpdatePlanArguments(
+  input: unknown,
+): UpdatePlanArguments {
+  if (input === null || typeof input !== "object") {
+    return input as UpdatePlanArguments;
+  }
+  const value = input as Record<string, unknown>;
+  if (!Array.isArray(value.steps)) return input as UpdatePlanArguments;
+  return {
+    ...value,
+    steps: value.steps.map((step) => {
+      if (step === null || typeof step !== "object") return step;
+      const s = step as Record<string, unknown>;
+      return { ...s, status: normalizeStepStatus(s.status) };
+    }),
+  } as UpdatePlanArguments;
+}
+
+const setContextParameters = Type.Object({
+  label: Type.Union([
+    Type.Literal("memory"),
+    Type.Literal("preferences"),
+  ]),
+  content: Type.String(),
+  action: Type.Optional(Type.Union([
+    Type.Literal("replace"),
+    Type.Literal("append"),
+  ])),
+});
+
 function result<T>(details: T): AgentToolResult<T> {
   return {
     content: [{ type: "text", text: serializeOutput(details).text }],
@@ -97,6 +150,7 @@ export function basePiToolCandidates(
       description:
         "Maintain the user-visible plan for the current task. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
       parameters: updatePlanParameters,
+      prepareArguments: normalizeUpdatePlanArguments,
       async execute(_toolCallId, input) {
         return result({
           ok: true,
@@ -108,3 +162,59 @@ export function basePiToolCandidates(
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];
 }
+
+/** Writable hot-memory Tool restored from Think Session context blocks. */
+export function memoryPiToolCandidate(
+  memory: RuntimeMemoryPort,
+  profile: Pick<
+    RuntimeMemoryProfile,
+    "memoryTokens" | "preferencesTokens"
+  >,
+): PiToolCandidate {
+  const queues = new Map<string, Promise<void>>();
+  const tool: AgentTool<typeof setContextParameters> = {
+    name: "set_context",
+    label: "Set context",
+    description:
+      "Replace or append durable working context. Use memory for facts and active context; use preferences for tone, format, tools, and workflow preferences.",
+    parameters: setContextParameters,
+    async execute(_toolCallId, { label, content, action = "replace" }) {
+      const run = async () => {
+        const existing = action === "append"
+          ? await memory.get(label) ?? ""
+          : "";
+        const separator = existing && !content.startsWith("\n") ? "\n" : "";
+        const updated = `${existing}${separator}${content}`;
+        const maxTokens = label === "memory"
+          ? profile.memoryTokens
+          : profile.preferencesTokens;
+        const tokens = estimateStringTokens(updated);
+        if (tokens > maxTokens) {
+          throw new Error(
+            `Block "${label}" exceeds maxTokens: ${tokens} > ${maxTokens}`,
+          );
+        }
+        await memory.set(label, updated);
+        return result({ label, action, tokens, maxTokens });
+      };
+      const tail = queues.get(label) ?? Promise.resolve();
+      const output = tail.then(run);
+      const next = output.then(
+        () => {},
+        () => {},
+      );
+      queues.set(label, next);
+      void next.then(() => {
+        if (queues.get(label) === next) queues.delete(label);
+      });
+      return output;
+    },
+  };
+  return {
+    owner: "runtime-memory",
+    authorized: true,
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool,
+  };
+}

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

@@ -1,13 +1,8 @@
-import {
-  createCodemodeRuntime,
-  DynamicWorkerExecutor,
-  truncateResult,
-} from "@cloudflare/codemode";
 import {
   createWorkspaceStateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
-import { StateConnector } from "@cloudflare/shell/workers";
+import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
 import type {
   RuntimeCodeExecutionPort,
   WorkspacePort,
@@ -22,7 +17,7 @@ const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
  *
  * Worker 宿主在具备 Durable Object state 和完整平台绑定时调用，然后把返回值交给 Runtime 工具组装。
  *
- * Cloudflare Codemode 把持久化 Runtime 和无状态 Dynamic Worker executor 分开；这里必须用 StateConnector 显式注入已限定范围的 Workspace，并在返回模型前用官方 `truncateResult` 限制结果。
+ * Think 的独立 execute factory 接受显式宿主参数，不要求 Agent 继承 Think；这里只借它组装 Codemode Runtime、Dynamic Worker executor 和已限定范围的 Workspace state connector。
  */
 export function createWorkspaceCodeExecutionPort(options: {
   readonly ctx: DurableObjectState;
@@ -30,26 +25,26 @@ export function createWorkspaceCodeExecutionPort(options: {
   readonly outbound: Fetcher;
   readonly workspace: WorkspacePort;
 }): RuntimeCodeExecutionPort {
-  const runtime = createCodemodeRuntime({
+  const { tool } = createExecuteRuntime({
     ctx: options.ctx,
-    executor: new DynamicWorkerExecutor({
-      loader: options.loader,
-      globalOutbound: options.outbound,
-      // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
-      timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-    }),
-    connectors: [
-      new StateConnector(
-        options.ctx,
-        createWorkspaceStateBackend(
-          options.workspace as unknown as WorkspaceFsLike,
-        ),
-      ),
-    ],
+    loader: options.loader,
+    globalOutbound: options.outbound,
+    // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
+    timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+    state: createWorkspaceStateBackend(
+      options.workspace as unknown as WorkspaceFsLike,
+    ),
     name: "execute",
-    transformResult: truncateResult,
   });
+  const execute = tool.execute;
+  if (typeof execute !== "function") {
+    throw new Error("Think createExecuteRuntime returned a non-executable tool");
+  }
   return {
-    execute: (input) => runtime.execute(input),
+    execute: (input) => Promise.resolve(execute(input, {
+      toolCallId: "execute",
+      messages: [],
+      context: undefined,
+    })),
   };
 }

package/src/pi/tool/core.ts

@@ -1,21 +1,16 @@
+import { createQuickActionTools } from "@cloudflare/think/tools/browser";
 import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import {
-  browserExtract,
-  browserLinks,
-  browserMarkdown,
-  browserScrape,
-  type QuickActionPage,
-} from "agents/browser";
 import type {
   RuntimeBrowserPort,
   RuntimeCodeExecutionPort,
 } from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiLoadedExtension } from "../assembly/extensions";
+import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
@@ -32,128 +27,33 @@ function result(details: unknown): AgentToolResult<unknown> {
 
 // #region Browser Quick Actions
 
-const pageParameters = {
-  url: Type.Optional(Type.String({ format: "uri" })),
-  html: Type.Optional(Type.String({ minLength: 1 })),
+const BROWSER_TOOL_LABELS: Readonly<Record<string, string>> = {
+  browser_markdown: "Read web page",
+  browser_extract: "Extract web data",
+  browser_links: "List web links",
+  browser_scrape: "Scrape web elements",
 };
-const browserPageParameters = Type.Object(pageParameters);
-const browserExtractParameters = Type.Object({
-  ...pageParameters,
-  prompt: Type.Optional(Type.String({ minLength: 1 })),
-  schema: Type.Optional(Type.Unknown()),
-});
-const browserScrapeParameters = Type.Object({
-  ...pageParameters,
-  selectors: Type.Array(Type.String({ minLength: 1 }), {
-    minItems: 1,
-  }),
-});
-
-// 把工具输入收窄为 Browser Quick Action 接受的页面来源。
-// 四个 Browser Quick Action execute 方法在调用 Agents SDK 前共用它。
-// 实际运行时再拒绝空输入，而同时给出 url 和 html 时优先 url，不能把不完整来源传给宿主绑定。
-function page(input: {
-  url?: string;
-  html?: string;
-}): QuickActionPage {
-  if (input.url) return { url: input.url };
-  if (input.html) return { html: input.html };
-  throw new Error("Provide either 'url' or 'html'");
-}
 
 /**
  * 为 Cloudflare Browser Run 的四个一次性 Quick Action 创建 Pi 工具候选项。
  *
  * Runtime 在宿主提供 Browser port 时调用，模型分别用它读取 Markdown、抽取数据、列出链接或按选择器抓取。
  *
- * Cloudflare 官方将 Quick Actions 定位为只需 browser binding 的无状态单次操作，所以这里直接调用四个宿主函数，不引入额外会话或重试状态。
+ * Cloudflare 官方将 Quick Actions 定位为只需 browser binding 的无状态单次操作，这里直接复用官方工厂。
  */
 export function browserQuickActionPiToolCandidates(
   browser: RuntimeBrowserPort,
 ): PiToolCandidate[] {
-  const markdown: AgentTool<typeof browserPageParameters> = {
-    name: "browser_markdown",
-    label: "Read web page",
-    description:
-      "Load a web page (or render raw HTML) and return its content as Markdown. Best for reading articles, docs, or any page as text.",
-    parameters: browserPageParameters,
-    // 把 URL 或 HTML 读成 Markdown。
-    // Pi 工具循环在模型选择 `browser_markdown` 时调用，调用前允许 Turn 取消。
-    // 取消检查必须放在 Browser binding 调用前，避免已终止 Turn 继续发起页面请求。
-    async execute(_toolCallId, input, signal) {
-      signal?.throwIfAborted();
-      return result(await browserMarkdown(browser, page(input)));
-    },
-  };
-  const extract: AgentTool<typeof browserExtractParameters> = {
-    name: "browser_extract",
-    label: "Extract web data",
-    description:
-      "Extract structured data from a web page using AI. Describe what you want in 'prompt'. Passing a JSON Schema in 'schema' is strongly recommended — without one the extractor often fails to produce JSON.",
-    parameters: browserExtractParameters,
-    // 按自然语言提示或 JSON Schema 从页面抽取数据。
-    // Pi 工具循环在模型选择 `browser_extract` 时调用，至少需要 prompt 或 schema 之一。
-    // schema 必须转成 Browser Run 期望的 `json_schema` response_format，而空抽取要求必须在发起请求前失败。
-    async execute(
-      _toolCallId,
-      { prompt, schema, ...input },
-      signal,
-    ) {
-      signal?.throwIfAborted();
-      if (!prompt && schema === undefined) {
-        throw new Error("Provide either 'prompt' or 'schema'");
-      }
-      return result(await browserExtract(browser, {
-        ...page(input),
-        prompt,
-        response_format: schema === undefined
-          ? undefined
-          : { type: "json_schema", schema },
-      }));
-    },
-  };
-  const links: AgentTool<typeof browserPageParameters> = {
-    name: "browser_links",
-    label: "List web links",
-    description:
-      "Return every link found on a web page (including ones not visible). Useful for discovering pages to follow.",
-    parameters: browserPageParameters,
-    // 列出 URL 或 HTML 页面中的链接。
-    // Pi 工具循环在模型选择 `browser_links` 时调用，调用前允许 Turn 取消。
-    // 保留 Agents SDK 的原始结果形状，让统一 result 边界负责文本投影而不在此处二次整形。
-    async execute(_toolCallId, input, signal) {
-      signal?.throwIfAborted();
-      return result(await browserLinks(browser, page(input)));
-    },
-  };
-  const scrape: AgentTool<typeof browserScrapeParameters> = {
-    name: "browser_scrape",
-    label: "Scrape web elements",
-    description:
-      "Scrape specific elements from a web page by CSS selector. Returns the matched elements' text, HTML, and attributes.",
-    parameters: browserScrapeParameters,
-    // 按 CSS 选择器抓取 URL 或 HTML 页面的指定元素。
-    // Pi 工具循环在模型选择 `browser_scrape` 时调用，并把简化的字符串列表传入。
-    // Browser Run 需要 `{ selector }` 对象列表，因此这个适配只在边界做一次形状转换。
-    async execute(
-      _toolCallId,
-      { selectors, ...input },
-      signal,
-    ) {
-      signal?.throwIfAborted();
-      return result(await browserScrape(browser, {
-        ...page(input),
-        elements: selectors.map((selector) => ({ selector })),
-      }));
-    },
-  };
-
-  return [markdown, extract, links, scrape].map((tool) => ({
-    owner: "core:browser",
-    authorized: true,
-    requiredExecutionLevel: "low",
-    tool,
-  }));
+  return Object.entries(createQuickActionTools({ browser })).map(
+    ([name, tool]) => ({
+      owner: "core:browser",
+      authorized: true,
+      requiredExecutionLevel: "low",
+      tool: aiToolToPi(name, tool, {
+        label: BROWSER_TOOL_LABELS[name] ?? name,
+      }),
+    }),
+  );
 }
 
 // #endregion