@docyrus/docyrus 0.0.60 → 0.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.60",
+  "version": "0.0.62",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",

package/resources/pi-agent/extensions/browser-tools.ts

@@ -0,0 +1,229 @@
+/**
+ * Browser automation tools for the pi coding agent (desktop mode).
+ *
+ * Active when DOCYRUS_DESKTOP_TOOLS=1 env var is set (passed by --desktop flag).
+ *
+ * Uses pi agent's ctx.ui.input() which sends an extension_ui_request to the
+ * client and blocks until extension_ui_response arrives. The client detects
+ * the docyrus_browser_* prefix in the request title and executes the browser
+ * command via Electron webContents API / CDP.
+ *
+ * Flow:
+ *   1. Agent calls docyrus_browser_snapshot
+ *   2. execute() calls ctx.ui.input("docyrus_browser_snapshot", paramsJson)
+ *   3. Pi sends extension_ui_request { method: "input", title: "docyrus_browser_snapshot", placeholder: paramsJson }
+ *   4. Client detects docyrus_browser_ prefix, executes via Electron IPC
+ *   5. Client responds with extension_ui_response { value: resultJson }
+ *   6. ctx.ui.input() resolves → execute() returns result to agent
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const TOOL_TIMEOUT_MS = 60_000;
+
+function browserToolResult(output: unknown) {
+  const text = typeof output === "string" ? output : JSON.stringify(output, null, 2);
+  return { content: [{ type: "text" as const, text }] };
+}
+
+function browserToolError(message: string) {
+  return { content: [{ type: "text" as const, text: message }], isError: true };
+}
+
+function createExecuteHandler(toolName: string) {
+  return async(
+    _toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    _onUpdate: unknown,
+    ctx: { ui: { input: (title: string, placeholder?: string, opts?: { signal?: AbortSignal; timeout?: number }) => Promise<string | undefined> }; hasUI: boolean },
+  ) => {
+    if (!ctx.hasUI) {
+      return browserToolError("Browser tools require a connected UI (desktop app or RPC client)");
+    }
+
+    try {
+      const paramsJson = JSON.stringify(params);
+      const resultJson = await ctx.ui.input(toolName, paramsJson, {
+        signal,
+        timeout: TOOL_TIMEOUT_MS,
+      });
+
+      if (!resultJson) {
+        return browserToolError("Browser tool execution cancelled or timed out");
+      }
+
+      try {
+        const parsed = JSON.parse(resultJson);
+        return browserToolResult(parsed);
+      } catch {
+        return browserToolResult(resultJson);
+      }
+    } catch (e: unknown) {
+      return browserToolError(e instanceof Error ? e.message : String(e));
+    }
+  };
+}
+
+export default function browserTools(pi: ExtensionAPI) {
+  if (process.env.DOCYRUS_DESKTOP_TOOLS !== "1") {
+    return;
+  }
+
+  pi.registerTool({
+    name: "docyrus_browser_navigate",
+    label: "Browser Navigate",
+    description: "Navigate the preview browser to a URL.",
+    parameters: Type.Object({
+      url: Type.String({ description: "URL to navigate to" }),
+      reload: Type.Optional(Type.Boolean({ description: "Force reload after navigation" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_navigate"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_wait",
+    label: "Browser Wait",
+    description: "Wait for a condition: network idle, CSS selector, URL pattern, or fixed delay.",
+    parameters: Type.Object({
+      idle: Type.Optional(Type.Boolean({ description: "Wait for network idle" })),
+      selector: Type.Optional(Type.String({ description: "Wait for CSS selector to appear" })),
+      url: Type.Optional(Type.String({ description: "Wait for URL to match glob pattern" })),
+      ms: Type.Optional(Type.Number({ description: "Wait for fixed milliseconds" })),
+      timeout: Type.Optional(Type.Number({ description: "Maximum wait time in ms (default: 15000)" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_wait"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_snapshot",
+    label: "Browser Snapshot",
+    description: "Get a compact snapshot of interactive page elements with refs (@e1, @e2, ...) for use in click/fill/select.",
+    parameters: Type.Object({
+      all: Type.Optional(Type.Boolean({ description: "Include all elements, not just interactive ones" })),
+      selector: Type.Optional(Type.String({ description: "Scope snapshot to a CSS selector subtree" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_snapshot"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_click",
+    label: "Browser Click",
+    description: "Click an element by snapshot ref (@e1), CSS selector, or x,y coordinates. Coordinate clicks pass through iframes and shadow DOM.",
+    parameters: Type.Object({
+      target: Type.String({ description: "Snapshot ref (@e1), CSS selector, or x coordinate" }),
+      y: Type.Optional(Type.Number({ description: "Y coordinate (when using coordinate mode with target as x)" })),
+      timeout: Type.Optional(Type.Number({ description: "Timeout in ms (default: 5000)" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_click"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_fill",
+    label: "Browser Fill",
+    description: "Clear and type a value into an input or textarea by snapshot ref or CSS selector.",
+    parameters: Type.Object({
+      target: Type.String({ description: "Snapshot ref (@e1) or CSS selector" }),
+      value: Type.String({ description: "Value to type into the element" }),
+      timeout: Type.Optional(Type.Number({ description: "Timeout in ms (default: 5000)" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_fill"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_select",
+    label: "Browser Select",
+    description: "Select a dropdown option by snapshot ref or CSS selector.",
+    parameters: Type.Object({
+      target: Type.String({ description: "Snapshot ref (@e1) or CSS selector" }),
+      value: Type.String({ description: "Option text or value to select" }),
+    }),
+    execute: createExecuteHandler("docyrus_browser_select"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_eval",
+    label: "Browser Eval",
+    description: "Evaluate JavaScript in the preview page and return the result.",
+    parameters: Type.Object({
+      code: Type.String({ description: "JavaScript code to evaluate" }),
+    }),
+    execute: createExecuteHandler("docyrus_browser_eval"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_screenshot",
+    label: "Browser Screenshot",
+    description: "Capture a screenshot of the preview browser. Returns base64-encoded PNG.",
+    parameters: Type.Object({
+      full: Type.Optional(Type.Boolean({ description: "Capture full page instead of just the viewport" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_screenshot"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_console",
+    label: "Browser Console",
+    description: "Read captured console messages from the preview page.",
+    parameters: Type.Object({
+      level: Type.Optional(Type.String({ description: "Filter by level: log, warn, error, info, debug" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_console"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_network",
+    label: "Browser Network",
+    description: "Inspect captured network requests.",
+    parameters: Type.Object({
+      method: Type.Optional(Type.String({ description: "Filter by HTTP method" })),
+      status: Type.Optional(Type.String({ description: "Filter by status code or pattern (200, 4xx)" })),
+      url: Type.Optional(Type.String({ description: "Filter by URL substring" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_network"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_cookies",
+    label: "Browser Cookies",
+    description: "List cookies for the preview page.",
+    parameters: Type.Object({
+      name: Type.Optional(Type.String({ description: "Filter by cookie name" })),
+      domain: Type.Optional(Type.String({ description: "Filter by domain" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_cookies"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_content",
+    label: "Browser Content",
+    description: "Extract readable markdown content from the current preview page.",
+    parameters: Type.Object({}),
+    execute: createExecuteHandler("docyrus_browser_content"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_info",
+    label: "Browser Info",
+    description: "Get current page info: URL, title, viewport, scroll, page size.",
+    parameters: Type.Object({}),
+    execute: createExecuteHandler("docyrus_browser_info"),
+  });
+
+  pi.registerTool({
+    name: "docyrus_browser_devtools",
+    label: "Browser Devtools",
+    description: "Read @docyrus/devtools runtime diagnostics.",
+    parameters: Type.Object({
+      subcommand: Type.Union([
+        Type.Literal("state"),
+        Type.Literal("errors"),
+        Type.Literal("issues"),
+        Type.Literal("console"),
+      ], { description: "What to read: state, errors, issues, or console" }),
+      level: Type.Optional(Type.String({ description: "Filter console entries by level" })),
+    }),
+    execute: createExecuteHandler("docyrus_browser_devtools"),
+  });
+}