@docyrus/docyrus 0.0.59 → 0.0.62

package/resources/browser-tools/browser-tabs.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { ensureDaemon, cdp, evaluate, getMode, setSession } from "./browser-client.js";
+
+const args = process.argv.slice(2);
+const switchIdx = args.indexOf("--switch");
+const switchTo = switchIdx !== -1 ? parseInt(args[switchIdx + 1], 10) : null;
+
+await ensureDaemon();
+
+try {
+  const { targetInfos } = cdp("Target.getTargets");
+  const pages = targetInfos.filter((t) =>
+    t.type === "page" && !t.url.startsWith("chrome://") && !t.url.startsWith("chrome-extension://") && !t.url.startsWith("devtools://"),
+  );
+
+  if (switchTo !== null) {
+    if (switchTo < 0 || switchTo >= pages.length) {
+      console.error(`✗ Tab index ${switchTo} out of range (0-${pages.length - 1})`);
+      process.exit(1);
+    }
+    const target = pages[switchTo];
+    cdp("Target.activateTarget", { targetId: target.targetId });
+    const { sessionId } = cdp("Target.attachToTarget", { targetId: target.targetId, flatten: true });
+    setSession(sessionId);
+    // Enable domains on new session
+    for (const domain of ["Page", "DOM", "Runtime", "Network"]) {
+      try { cdp(`${domain}.enable`, {}, sessionId); } catch {}
+    }
+    console.log(JSON.stringify({ mode: getMode(), switched: switchTo, url: target.url, title: target.title }));
+  } else {
+    const tabs = pages.map((t, i) => ({ index: i, url: t.url, title: t.title }));
+    console.log(JSON.stringify({ mode: getMode(), count: tabs.length, tabs }));
+  }
+} catch (e) {
+  console.error(`✗ Tabs failed: ${e.message}`);
+  process.exit(1);
+}

package/resources/browser-tools/browser-wait.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { ensureDaemon, evaluate, waitForCondition, getMode, drainEvents } from "./browser-client.js";
+import { execFileSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+const idle = args.includes("--idle");
+const selectorIdx = args.indexOf("--selector");
+const urlIdx = args.indexOf("--url");
+const timeoutIdx = args.indexOf("--timeout");
+const selector = selectorIdx !== -1 ? args[selectorIdx + 1] : null;
+const urlPattern = urlIdx !== -1 ? args[urlIdx + 1] : null;
+const timeout = timeoutIdx !== -1 ? parseInt(args[timeoutIdx + 1], 10) : 15000;
+const fixedDelay = args.find((a) => !a.startsWith("--") && /^\d+$/.test(a));
+
+if (!idle && !selector && !urlPattern && !fixedDelay) {
+  console.log("Usage: browser-wait.js [--idle] [--selector <css>] [--url <pattern>] [<ms>] [--timeout <ms>]");
+  process.exit(1);
+}
+
+await ensureDaemon();
+
+try {
+  if (fixedDelay) {
+    const ms = parseInt(fixedDelay, 10);
+    execFileSync(process.execPath, ["-e", `setTimeout(()=>{},${ms})`], { timeout: ms + 1000 });
+  } else if (idle) {
+    // Wait for network idle: no network events for 500ms
+    const deadline = Date.now() + timeout;
+    let lastActivity = Date.now();
+    while (Date.now() < deadline) {
+      const evts = drainEvents();
+      const networkEvts = evts.filter((e) => e.method.startsWith("Network."));
+      if (networkEvts.length > 0) { lastActivity = Date.now(); }
+      if (Date.now() - lastActivity > 500) { break; }
+      execFileSync(process.execPath, ["-e", "setTimeout(()=>{},100)"], { timeout: 1000 });
+    }
+  } else if (selector) {
+    waitForCondition(`!!document.querySelector(${JSON.stringify(selector)})`, timeout);
+  } else if (urlPattern) {
+    const regex = "^" + urlPattern.replace(/\*\*/g, ".*").replace(/(?<!\.\*)\*/g, "[^/]*") + "$";
+    waitForCondition(`new RegExp(${JSON.stringify(regex)}).test(window.location.href)`, timeout);
+  }
+
+  const url = evaluate("window.location.href");
+  console.log(JSON.stringify({ mode: getMode(), waited: true, url }));
+} catch (e) {
+  console.error(`✗ Wait failed: ${e.message}`);
+  process.exit(1);
+}

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"),
+  });
+}

package/resources/pi-agent/skills/docyrus-chrome-devtools-cli/SKILL.md

@@ -1,97 +1,208 @@
 ---
 name: docyrus-browser-cli
-description: Use Docyrus CLI browser commands for browser automation (local Chrome or remote Cloudflare Browser Rendering). Use when you need to start a browser session, navigate pages, inspect DOM state, evaluate JavaScript, capture screenshots, pick elements interactively, inspect cookies, extract readable page content, or run CDP scripts.
+description: Use Docyrus CLI browser commands for browser automation (local Chrome or remote Cloudflare Browser Rendering). Use when you need to start a browser session, navigate pages, inspect page state, interact with elements, capture screenshots, evaluate JavaScript, read console output, inspect network requests, or run CDP scripts.
 ---
 
 # Docyrus Browser CLI
 
-Browser automation commands exposed through the `docyrus` CLI. Works in both local mode (Chrome on `:9222`) and remote sandbox mode (Cloudflare Browser Rendering via WSS).
+Browser automation via a persistent daemon that holds a raw CDP (Chrome DevTools Protocol) WebSocket connection. No Puppeteer/Playwright framework — direct CDP for speed and flexibility.
 
-All commands return JSON with a `mode` field (`"local"` or `"remote"`). In remote mode, responses include `devtoolsFrontendUrl` for live DevTools access.
+Works in both **local mode** (Chrome on `:9222`) and **remote sandbox mode** (Cloudflare Browser Rendering).
 
-## Commands
+## Architecture
+
+```
+docyrus browser <command>
+  → tool script (Node.js)
+    → HTTP request to daemon (localhost:9333)
+      → raw CDP WebSocket to Chrome/Cloudflare
+```
 
-Start a browser session:
+The daemon starts automatically on the first command and stays alive for 5 minutes of idle time. All commands share the same browser connection — no reconnection overhead.
+
+## Core Workflow for Self-Testing
 
 ```bash
+# 1. Start browser + daemon
 docyrus browser start
-docyrus browser start --profile
+
+# 2. Navigate to preview
+docyrus browser nav https://preview-url.example.com
+
+# 3. Wait for page to fully load
+docyrus browser wait --idle
+
+# 4. Discover interactive elements
+docyrus browser snapshot
+
+# 5. Interact using refs from snapshot
+docyrus browser fill @e2 "user@example.com"
+docyrus browser click @e3
+
+# 6. Verify results
+docyrus browser wait --selector ".success-message"
+docyrus browser screenshot
+docyrus browser console --level error
+docyrus browser network --method POST --status 2xx
 ```
 
-- Local mode: launches Chrome with remote debugging on `:9222`. `--profile` copies the user's default Chrome profile.
-- Sandbox mode: creates a Cloudflare Browser Rendering session and opens the app preview URL.
+## Commands
 
-Navigate tabs:
+### Session Management
 
 ```bash
-docyrus browser nav https://example.com
-docyrus browser nav https://example.com --new
-docyrus browser nav https://example.com --reload
+docyrus browser start                     # Start Chrome + daemon
+docyrus browser start --profile           # Start with user's Chrome profile (local only)
+docyrus browser close                     # Stop daemon and disconnect
 ```
 
-Run JavaScript in the active tab:
+### Navigation
+
+```bash
+docyrus browser nav <url>                 # Navigate active tab
+docyrus browser nav <url> --new           # Open in new tab
+docyrus browser nav <url> --reload        # Navigate and force reload
+```
+
+### Waiting
+
+```bash
+docyrus browser wait --idle               # Wait for network idle
+docyrus browser wait --selector "h1"      # Wait for element to appear
+docyrus browser wait --url "**/dashboard" # Wait for URL to match pattern
+docyrus browser wait 2000                 # Wait fixed milliseconds
+docyrus browser wait --idle --timeout 30000
+```
+
+### Page Snapshot (Element Discovery)
+
+```bash
+docyrus browser snapshot                  # Interactive elements with refs (@e1, @e2, ...)
+docyrus browser snapshot --all            # Include non-interactive elements
+docyrus browser snapshot --selector "#app" # Scope to a subtree
+```
+
+Returns:
+```json
+{
+  "snapshot": [
+    { "ref": "@e1", "tag": "input", "type": "email", "placeholder": "Email" },
+    { "ref": "@e2", "tag": "input", "type": "password" },
+    { "ref": "@e3", "tag": "button", "text": "Sign In" }
+  ]
+}
+```
+
+### Element Interaction
+
+Three targeting modes — refs, CSS selectors, or x,y coordinates:
+
+```bash
+docyrus browser click @e3                 # Click by snapshot ref
+docyrus browser click "button.submit"     # Click by CSS selector
+docyrus browser click 350 200             # Coordinate click (compositor-level)
+docyrus browser fill @e1 "user@test.com"  # Clear + type into input
+docyrus browser select @e4 "Option A"    # Select dropdown option
+```
+
+Coordinate clicks pass through iframes, shadow DOM, and cross-origin frames at the compositor level — no DOM piercing needed. Use `info` for viewport dimensions.
+
+### JavaScript Evaluation
 
 ```bash
 docyrus browser eval 'document.title'
-docyrus browser eval 'document.querySelectorAll("a").length'
+docyrus browser eval 'const rows = document.querySelectorAll("tr"); return rows.length'
+docyrus browser eval 'await fetch("/api/health").then(r => r.json())'
 ```
 
-Capture a screenshot of the active tab:
+Supports expressions and multi-statement code. Uses CDP `Runtime.evaluate` with `awaitPromise: true`.
+
+### Screenshots
 
 ```bash
-docyrus browser screenshot
+docyrus browser screenshot               # Viewport screenshot → /tmp
+docyrus browser screenshot --full         # Full page
+docyrus browser screenshot --base64       # Base64 in JSON (for remote/sandbox mode)
+```
+
+### Console Messages
+
+```bash
+docyrus browser console                   # Captured logs (last 50)
+docyrus browser console --level error     # Only errors
+docyrus browser console --listen 5000     # Listen for 5 seconds via CDP events
 ```
 
-Interactively pick DOM elements in the visible browser:
+Run `console` once early to install the interceptor.
+
+### Network Inspection
 
 ```bash
-docyrus browser pick "Click the submit button"
+docyrus browser network                   # All captured requests
+docyrus browser network --method POST     # Only POST requests
+docyrus browser network --status 4xx      # Only 4xx responses
+docyrus browser network --url "/api/"     # URL substring filter
+docyrus browser network --listen 5000     # Listen for 5 seconds
 ```
 
-Inspect cookies for the active tab:
+Network events are captured automatically by the daemon (CDP `Network.enable`).
+
+### Docyrus Devtools
+
+Read runtime diagnostics from `@docyrus/devtools` (must be loaded on the page):
 
 ```bash
-docyrus browser cookies
+docyrus browser devtools state              # Full devtools state
+docyrus browser devtools errors             # Collected API errors
+docyrus browser devtools issues             # Detected API usage issues (e.g. missing fields, bad queries)
+docyrus browser devtools console            # Console entries captured by devtools
+docyrus browser devtools console --level error  # Filtered by level
 ```
 
-Extract readable content as markdown:
+Use after interacting with a Docyrus-backed app to catch API misuse, failed requests, and runtime issues that `console --level error` alone would miss.
+
+### Content Extraction
 
 ```bash
-docyrus browser content https://example.com
+docyrus browser content <url>             # Extract readable markdown from URL
 ```
 
-Run a CDP script on the active browser session:
+### Cookies
 
 ```bash
-docyrus browser run-script my-script.js
-docyrus browser run-script my-script.js --appId <appId>
-docyrus browser run-script my-script.js --appSlug my-app
+docyrus browser cookies                   # All cookies (via CDP Network.getCookies)
+docyrus browser cookies --name "session"
+docyrus browser cookies --domain ".app.com"
 ```
 
-- The script receives `browser` (Puppeteer Browser) and `page` (a new Page) as function arguments.
-- Whatever the script returns is printed as JSON to stdout.
+### Page Info
+
+```bash
+docyrus browser info                      # URL, title, viewport, scroll, page dimensions
+```
 
-Example script (`scrape-title.js`):
+### Tab Management
 
-```js
-await page.goto("https://example.com");
-const title = await page.title();
-return { title };
+```bash
+docyrus browser tabs                      # List all tabs
+docyrus browser tabs --switch 1           # Switch to tab by index
 ```
 
-## When To Use
+### CDP Scripts
+
+```bash
+docyrus browser run-script script.js
+```
 
-- Visible browser automation is required.
-- A page needs JavaScript execution before content is available.
-- You need to inspect DOM state without guessing selectors.
-- You want the user to click elements directly through an interactive picker.
-- You need quick page extraction or screenshot capture from a real browser session.
-- You need to run CDP scripts against a remote headless browser from within a sandbox.
+The script receives raw CDP helpers: `cdp`, `evaluate`, `navigate`, `captureScreenshot`, `clickAt`, `typeText`, `pressKey`, `pageInfo`, `drainEvents`, `waitForCondition`.
 
-## Working Style
+## Tips for AI Agents
 
-- Start a session first with `docyrus browser start` if the browser is not already available.
-- Prefer `docyrus browser eval` for DOM inspection and structured page state.
-- Use `docyrus browser pick` when element targeting is ambiguous or user choice matters.
-- Use `docyrus browser content` for readable markdown extraction from article-like pages.
-- Use `docyrus browser run-script` to run full Puppeteer scripts on the active browser session.
+1. `start` auto-launches the daemon — subsequent commands are fast (no reconnection)
+2. Always `wait --idle` after `nav` before taking snapshots or screenshots
+3. Use `snapshot` → refs → `click`/`fill` for reliable element targeting
+4. Re-snapshot after interactions to get fresh refs
+5. Use coordinate `click 350 200` for elements inside iframes or shadow DOM
+6. Check `console --level error` and `network --status 5xx` to catch runtime issues
+7. Use `screenshot --base64` in remote/sandbox mode
+8. `close` stops the daemon; it auto-stops after 5 minutes idle anyway