@springbrand/agent-runtime 0.2.0-alpha.24 → 0.2.0-alpha.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.24",
+  "version": "0.2.0-alpha.25",
   "type": "module",
   "files": [
     "src",

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

@@ -83,6 +83,16 @@ function previewNote(base: string): string {
     "file:// cannot reach the workspace, and there is no other preview host — do not guess one.";
 }
 
+function browserToolDescription(): string {
+  return "Run JavaScript against a live browser over the Chrome DevTools Protocol through the `cdp` connector. " +
+    "Each top-level `browser_execute` call is one-shot: it starts a fresh browser and closes it when the call returns. " +
+    "Never reuse a `targetId` or `sessionId` from an earlier browser_execute call. " +
+    "Create targets, attach, navigate, interact, inspect diagnostics, and capture screenshots within the same call. " +
+    "Use `cdp.spec()` to discover commands, `cdp.send({ method, params })` for target-scoped commands, " +
+    "and `cdp.attachToTarget({ targetId })` before page-scoped commands. " +
+    "Issue browser calls sequentially so the inspection can be replayed reliably.";
+}
+
 /**
  * 把宿主的 Durable Object state、Worker Loader 和 Browser Run 绑定组装成浏览器执行 Port。
  *
@@ -121,7 +131,10 @@ export function createBrowserExecutionFactory(options: {
       if (!tool) {
         throw new Error("Upstream createBrowserTools did not return browser_execute");
       }
-      const port = toCodeExecutionPort(tool, "browser_execute");
+      const port = {
+        ...toCodeExecutionPort(tool, "browser_execute"),
+        description: browserToolDescription(),
+      };
       if (!options.previewBaseUrl) return port;
       // 前置而不是追加：上游的 codemode 描述很长，缀在末尾的一句会被读丢 ——
       // 2026-08-13 手动冒烟里模型就没看见它，转而去猜 `file://` 和 `https://workspace.local/`。