@pasko70/pibo 1.0.5 → 1.2.0

package/dist/tools/cdp-client.js

@@ -0,0 +1,189 @@
+export const DEFAULT_CDP_URL = "http://127.0.0.1:56663";
+export const DEFAULT_CDP_TIMEOUT_MS = 2_500;
+export class CdpClient {
+    webSocketUrl;
+    nextId = 0;
+    pending = new Map();
+    socket;
+    constructor(webSocketUrl) {
+        this.webSocketUrl = webSocketUrl;
+    }
+    connect(timeoutMs = 3_000) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(this.webSocketUrl);
+            this.socket = socket;
+            let settled = false;
+            const timer = setTimeout(() => fail(new Error("Timed out connecting to CDP target")), timeoutMs);
+            const settle = () => {
+                if (settled)
+                    return false;
+                settled = true;
+                clearTimeout(timer);
+                return true;
+            };
+            const succeed = () => {
+                if (settle())
+                    resolve();
+            };
+            const fail = (error) => {
+                if (settle())
+                    reject(error);
+            };
+            socket.addEventListener("open", succeed);
+            socket.addEventListener("message", (event) => this.handleMessage(String(event.data)));
+            socket.addEventListener("error", () => fail(new Error(`CDP WebSocket error connecting to ${this.webSocketUrl}`)));
+            socket.addEventListener("close", () => {
+                for (const [id, pending] of this.pending) {
+                    clearTimeout(pending.timer);
+                    pending.reject(new Error("CDP target closed"));
+                    this.pending.delete(id);
+                }
+            });
+        });
+    }
+    send(method, params, timeoutMs = 10_000) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            throw new Error("CDP target is not connected");
+        const id = ++this.nextId;
+        const payload = params ? { id, method, params } : { id, method };
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Timed out waiting for CDP method ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        this.socket.send(JSON.stringify(payload));
+        return promise;
+    }
+    async evaluate(expression, timeoutMs = 10_000) {
+        const response = await this.send("Runtime.evaluate", {
+            expression,
+            awaitPromise: true,
+            returnByValue: true,
+            userGesture: true,
+        }, timeoutMs);
+        if (response.exceptionDetails)
+            throw new Error(`Browser evaluation failed: ${JSON.stringify(response.exceptionDetails)}`);
+        return response.result?.value;
+    }
+    close() {
+        try {
+            this.socket?.close();
+        }
+        catch {
+            // ignore close races
+        }
+    }
+    handleMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (typeof message.id !== "number")
+            return;
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pending.delete(message.id);
+        if (message.error) {
+            pending.reject(new Error(message.error.message ?? JSON.stringify(message.error)));
+            return;
+        }
+        pending.resolve(message.result);
+    }
+}
+export function normalizeCdpUrlSync(value) {
+    return value.replace(/\/+$/, "");
+}
+export async function fetchWithTimeout(url, timeoutMs, init = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to fetch ${url}: ${reason}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function listCdpTargets(options = {}) {
+    const cdpUrl = normalizeCdpUrlSync(options.cdpUrl ?? DEFAULT_CDP_URL);
+    try {
+        const response = await fetchWithTimeout(`${cdpUrl}/json/list`, options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS);
+        if (!response.ok) {
+            throw new Error(`Chrome target discovery responded with HTTP ${response.status} ${response.statusText}`);
+        }
+        const payload = await response.json();
+        if (!Array.isArray(payload))
+            throw new Error("Chrome target discovery returned invalid JSON");
+        return payload.map(normalizeCdpTarget);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("Failed to fetch")) {
+            throw new Error(`CDP endpoint ${cdpUrl} is unreachable. Is Chrome running with remote debugging? (${error.message})`);
+        }
+        throw error;
+    }
+}
+export async function openCdpTarget(url, options = {}) {
+    const cdpUrl = normalizeCdpUrlSync(options.cdpUrl ?? DEFAULT_CDP_URL);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS;
+    const endpoint = `${cdpUrl}/json/new?${encodeURIComponent(url)}`;
+    try {
+        let response = await fetchWithTimeout(endpoint, timeoutMs, { method: "PUT" });
+        if (response.status === 404 || response.status === 405) {
+            response = await fetchWithTimeout(endpoint, timeoutMs);
+        }
+        if (!response.ok)
+            throw new Error(`Chrome target creation responded with HTTP ${response.status} ${response.statusText}`);
+        const payload = await response.json();
+        return normalizeCdpTarget(payload);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("Failed to fetch")) {
+            throw new Error(`CDP endpoint ${cdpUrl} is unreachable. Is Chrome running with remote debugging? (${error.message})`);
+        }
+        throw error;
+    }
+}
+export function findCdpTarget(targets, targetIdOrUrl) {
+    return targets.find((target) => target.id === targetIdOrUrl || target.url === targetIdOrUrl || target.title === targetIdOrUrl || target.webSocketDebuggerUrl === targetIdOrUrl);
+}
+export async function connectCdpTarget(target, timeoutMs = 3_000) {
+    if (!target.webSocketDebuggerUrl)
+        throw new Error(`CDP target ${target.id || target.url} is not attachable (no webSocketDebuggerUrl)`);
+    const client = new CdpClient(target.webSocketDebuggerUrl);
+    try {
+        await client.connect(timeoutMs);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to connect to CDP target ${target.id || target.url}: ${reason}`);
+    }
+    return client;
+}
+function normalizeCdpTarget(target) {
+    const record = target && typeof target === "object" && !Array.isArray(target) ? target : {};
+    return {
+        id: stringValue(record.id),
+        type: stringValue(record.type),
+        title: stringValue(record.title),
+        url: stringValue(record.url),
+        webSocketDebuggerUrl: optionalStringValue(record.webSocketDebuggerUrl),
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : "";
+}
+function optionalStringValue(value) {
+    const text = stringValue(value);
+    return text || undefined;
+}

package/dist/tools/guides.js

@@ -1,3 +1,201 @@
+export const RALPH_GUIDE = {
+    name: 'ralph',
+    description: 'Create, inspect, and control Pibo Ralph jobs from the CLI.',
+    content: `---
+name: ralph
+description: Creates and controls continuous Pibo agent jobs for implementation loops, bug fixing, validation, and PRD/story execution.
+allowed-tools: Bash(pibo:*), Bash(npm:*)
+---
+
+# Ralph CLI Tool
+
+Ralph runs repeatable Pibo agent jobs. Use it when the user wants an implementation loop, PRD/story execution, bug fixing, validation, or a background job that can be started, stopped, inspected, and resumed.
+
+## Required Context
+
+Ralph jobs are app-global. Choose either:
+
+- room target: \`--room <current-room-id>\`
+- shared default target: \`--default-chat\`
+
+Inside the Pibo source repo, use \`npm run --silent dev -- ralph ...\` for uninstalled local changes. For the installed CLI, use \`pibo ralph ...\`.
+
+## Discover Templates
+
+\`\`\`bash
+pibo ralph templates
+pibo ralph templates --json
+pibo tools guide ralph ralph
+\`\`\`
+
+Good defaults:
+
+- \`prd-single-story-standard\`: one failing PRD story per run; promise-complete stop policy.
+- \`prd-batch-stories\`: multiple PRD stories in priority order; commit after each story.
+- \`single-run-objective\`: one focused non-PRD objective; stops after one completed run attempt.
+
+## Create Jobs
+
+Create stopped, inspect, then start:
+
+\`\`\`bash
+pibo ralph add \\
+  --room "<room-id>" \\
+  --template prd-single-story-standard \\
+  --name "Implement story X" \\
+  --prompt "Implement exactly one failing PRD story, test it, and commit." \\
+  --json
+
+pibo ralph start <job-id>
+\`\`\`
+
+Create and start immediately:
+
+\`\`\`bash
+pibo ralph add \\
+  --room "<room-id>" \\
+  --template single-run-objective \\
+  --name "Fix bug Y" \\
+  --prompt "Reproduce and fix bug Y, then run focused tests." \\
+  --start \\
+  --json
+\`\`\`
+
+Explicit options override template fields.
+
+## Inspect and Debug
+
+\`\`\`bash
+pibo ralph status --json
+pibo ralph list --all --json
+pibo ralph runs --job <job-id> --json
+pibo ralph policy show <job-id> --json
+\`\`\`
+
+Use \`runs --json\` to debug failures, session ids, completion state, and recent activity. Prefer bounded JSON output when another agent will parse it.
+
+## Control Jobs
+
+\`\`\`bash
+pibo ralph stop <job-id>      # finish current session, then stop
+pibo ralph cancel <job-id>    # abort current session and stop
+pibo ralph edit <job-id> --prompt "Updated objective" --json
+pibo ralph remove <job-id>
+\`\`\`
+
+Prefer \`stop\` for normal shutdown and \`cancel\` only when the active run is stuck or unsafe.
+
+## Safety
+
+1. Do not start many Ralph jobs unless the user asked for parallel work.
+2. Use templates first; avoid ad-hoc long prompts when a preset fits.
+3. Inspect with \`list --json\` and \`runs --json\` before editing or canceling an unknown job.
+4. If working in the source repo before install, use \`npm run --silent dev -- ralph ...\`.
+`,
+};
+export const AGENT_BROWSER_GUIDE = {
+    name: 'agent-browser',
+    description: 'Ref-based browser automation with the Agent Browser CLI.',
+    content: `---
+name: agent-browser
+description: Fast native browser automation CLI for AI agents. Use when you need to open pages, inspect snapshots, click refs, fill fields, and keep browser state under a Pibo-owned tool home.
+allowed-tools: Bash(agent-browser:*)
+---
+
+# Browser Automation with Agent Browser
+
+Agent Browser uses refs from interactive snapshots. Inspect first, act on refs, then inspect again after navigation or DOM changes.
+
+## Prerequisites
+
+Initialize one shell with the Pibo tool environment:
+
+\`\`\`bash
+eval "$(pibo tools env agent-browser)"
+agent-browser doctor --offline --quick
+\`\`\`
+
+Inside the Pibo source repo, use \`eval "$(npm run --silent dev -- tools env agent-browser)"\`. The Pibo wrapper comes first on \`PATH\` and keeps state under \`AGENT_BROWSER_HOME\`, normally \`$PIBO_HOME/tools/agent-browser/home\`. For \`agent-browser@0.27.0\`, the wrapper also redirects \`HOME\` there by default so \`~/.agent-browser\` stays inside the tool home.
+
+## Core Workflow
+
+\`\`\`bash
+agent-browser open <url>
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser fill @e2 "text"
+agent-browser snapshot -i
+agent-browser get title
+agent-browser close --all
+\`\`\`
+
+Re-run \`snapshot -i\` after navigation, submit, scroll, animation, or any DOM-changing action. Do not reuse stale refs.
+
+## Sessions
+
+Use sessions for separate browser tasks:
+
+\`\`\`bash
+agent-browser --session pibo-check open https://example.com
+AGENT_BROWSER_SESSION=pibo-check agent-browser snapshot -i
+agent-browser session list
+\`\`\`
+
+Keep mutating commands against the same session serial. Avoid parallel \`click\`, \`fill\`, \`open\`, or \`snapshot\` calls for one session.
+
+## State and Profiles
+
+The wrapper defaults browser-launching commands to a persistent Pibo profile:
+
+\`\`\`bash
+agent-browser open https://example.com
+\`\`\`
+
+Opt out when needed:
+
+\`\`\`bash
+agent-browser --fresh-profile open https://example.com
+agent-browser --profile /path/to/profile open https://example.com
+agent-browser --session-name saved-check open https://example.com
+\`\`\`
+
+Treat profiles, saved states, auth vaults, cookies, and headers as secrets. Do not print or copy their contents into chat.
+
+## Authenticated Chat Web Work
+
+Prefer isolated leases when more than one agent may use authenticated Chat Web:
+
+\`\`\`bash
+eval "$(pibo tools agent-browser lease acquire --app pibo-chat --holder "$USER")"
+agent-browser open http://4788.192.168.0.204.sslip.io/apps/chat
+agent-browser snapshot -i
+\`\`\`
+
+To prepare the reusable template profile:
+
+\`\`\`bash
+eval "$(pibo tools agent-browser auth-template env --app pibo-chat)"
+agent-browser open http://4788.192.168.0.204.sslip.io/apps/chat
+\`\`\`
+
+Sign in once, close the browser, then acquire leases from the template.
+
+For an already-open browser, inspect CDP targets:
+
+\`\`\`bash
+pibo tools agent-browser targets
+pibo tools agent-browser attach-chat
+\`\`\`
+
+## Upstream Skills
+
+Pibo keeps the full upstream skill out of default runtime context. Fetch it only when needed:
+
+\`\`\`bash
+agent-browser skills get core --full
+\`\`\`
+`,
+};
 export const BROWSER_USE_GUIDE = {
     name: 'browser-use',
     description: 'Local browser automation with the browser-use CLI.',
@@ -43,7 +241,7 @@ After navigation, submit, keypress navigation, major DOM changes, or scroll on c
 \`\`\`bash
 browser-use --headed open <url>                # Starts Pibo-managed persistent PIBo Chrome via CDP
 browser-use --fresh-profile open <url>         # Starts a fresh temporary browser profile
-browser-use connect                            # Connect to local Chrome via CDP
+browser-use --connect open <url>               # Connect to local Chrome via CDP (requires --remote-debugging-port)
 browser-use --profile "Default" open <url>     # Upstream profile mode; Browser Use may copy it to a temp dir
 \`\`\`
 
@@ -110,7 +308,7 @@ browser-use close --all
 For the Pibo Chat Web App, prefer an isolated authenticated lease when multiple agents may use the browser at the same time:
 
 \`\`\`bash
-eval "$(pibo tools browser-use lease acquire --app pibo-chat --owner "$USER")"
+eval "$(pibo tools browser-use lease acquire --app pibo-chat --holder "$USER")"
 browser-use state
 \`\`\`
 
@@ -161,7 +359,7 @@ browser-use profile list
 
 To intentionally use a real local Chrome user data directory instead of the Pibo-managed one, set \`PIBO_BROWSER_USE_CHROME_USER_DATA_DIR\` before starting the session.
 
-If \`browser-use connect\` cannot find Chrome, ask the user whether they want to relaunch Chrome with remote debugging or use a managed Chromium profile.
+If \`browser-use --connect\` cannot find Chrome, ask the user whether they want to relaunch Chrome with remote debugging or use a managed Chromium profile.
 
 ## Tips
 
@@ -178,6 +376,7 @@ If \`browser-use connect\` cannot find Chrome, ask the user whether they want to
 11. \`select\` confirms the visible option text, while \`get value\` returns the underlying option value.
 12. Avoid \`browser-use --version\`; this CLI does not support it.
 13. Avoid \`extract\`; it is listed by the CLI but is not implemented in this version.
+14. If Chrome fails to start with a "SingletonLock" error, the wrapper auto-detects and terminates stale Chrome processes holding the lock. Retry your command.
 `,
 };
 export const REMOTE_BROWSER_GUIDE = {
@@ -220,7 +419,7 @@ After navigation, submit, keypress navigation, major DOM changes, or scroll on c
 \`\`\`bash
 browser-use open <url>
 browser-use --headed open <url>
-browser-use connect
+browser-use --connect open <url>
 browser-use --cdp-url ws://localhost:9222/devtools/browser/... open <url>
 \`\`\`