@phi-code-admin/browser 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @phi-code-admin/browser — programmatic browser API for phi-code.
+ *
+ * Boots the bundled `@phi-code-admin/camofox-browser` Express server on a
+ * private localhost port the first time any tool is called, then exposes
+ * the 10 OpenClaw tools as plain async functions. Shutdown is automatic
+ * on `process.exit` and can be triggered explicitly with `closeAll()`.
+ *
+ * Design constraints (per phi-code vendoring spec):
+ *   - Zero external network calls. The Camoufox binary is provided by
+ *     `@phi-code-admin/camoufox-bin-*` via npm optionalDependencies.
+ *   - The Express server is an implementation detail; consumers only see
+ *     ES module exports. The server can still be launched independently
+ *     via `npx @phi-code-admin/camofox-browser` for users who want REST.
+ *   - Each tool returns a JSON-serialisable object. No process objects,
+ *     no file handles, no streams — the result is safe to pass into a
+ *     TUI rendering layer or to serialise as a tool_result message.
+ */
+/**
+ * Boot (or reuse) the camofox-browser server. Idempotent across calls.
+ */
+export declare function ensureServer(): Promise<{
+    baseUrl: string;
+}>;
+/**
+ * Kill the embedded camofox-browser server (if running) and reset state.
+ * Safe to call multiple times. Resolves once the child has exited.
+ */
+export declare function closeAll(): Promise<void>;
+export interface CreateTabResult {
+    tabId: string;
+    userId: string;
+    url?: string;
+}
+/** Open a new browser tab. Returns the tab id used by the other tools. */
+export declare function createTab(options: {
+    userId?: string;
+    url?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}): Promise<CreateTabResult>;
+export interface NavigateResult {
+    tabId: string;
+    url: string;
+    status?: number;
+    loadEvent?: string;
+}
+/**
+ * Navigate the given tab (or a freshly opened one) to a URL.
+ * High-level convenience: passing `url` without `tabId` opens a new tab
+ * first.
+ */
+export declare function navigate(options: {
+    url: string;
+    tabId?: string;
+    userId?: string;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    timeoutMs?: number;
+}): Promise<NavigateResult>;
+/**
+ * Get an accessibility snapshot (DOM tree with ref ids) of the given tab.
+ * Refs returned here can be used with `click`/`type`/`scroll`.
+ */
+export declare function snapshot(options: {
+    tabId: string;
+}): Promise<unknown>;
+export interface ExtractResult {
+    url?: string;
+    title?: string;
+    content?: string;
+    textContent?: string;
+    excerpt?: string;
+    length?: number;
+}
+/**
+ * Extract the readable content of the current page (Readability-style).
+ * For a fresh page, pass `url` to navigate first; otherwise the tab's
+ * current document is extracted.
+ */
+export declare function extract(options: {
+    tabId?: string;
+    userId?: string;
+    url?: string;
+    mode?: "readability" | "html" | "text";
+}): Promise<ExtractResult>;
+export interface ScreenshotResult {
+    tabId: string;
+    mimeType: string;
+    bytesBase64: string;
+}
+/** Capture a screenshot of the given tab as a base64-encoded PNG. */
+export declare function screenshot(options: {
+    tabId: string;
+    fullPage?: boolean;
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}): Promise<ScreenshotResult>;
+/**
+ * High-level search macro: opens a new tab, navigates to a search engine
+ * macro (`?q=...` on Google / DDG depending on host config), and returns
+ * the readability extraction of the result page.
+ */
+export declare function search(options: {
+    query: string;
+    engine?: "google" | "duckduckgo" | "bing";
+    userId?: string;
+}): Promise<ExtractResult>;
+/** Click an element by ref (from `snapshot`) or CSS selector. */
+export declare function click(options: {
+    tabId: string;
+    ref?: string;
+    selector?: string;
+    button?: "left" | "right" | "middle";
+}): Promise<{
+    tabId: string;
+}>;
+/** Type text into a focused element (or one targeted via ref/selector). */
+export declare function type(options: {
+    tabId: string;
+    text: string;
+    ref?: string;
+    selector?: string;
+    pressEnter?: boolean;
+    delayMs?: number;
+}): Promise<{
+    tabId: string;
+}>;
+/** Scroll the page or a specific element by ref. */
+export declare function scroll(options: {
+    tabId: string;
+    direction: "up" | "down" | "left" | "right";
+    ref?: string;
+    pixels?: number;
+}): Promise<{
+    tabId: string;
+}>;
+/** Close a single tab. The underlying browser context is kept warm. */
+export declare function closeTab(options: {
+    tabId: string;
+}): Promise<{
+    tabId: string;
+}>;
+export interface ListedTab {
+    tabId: string;
+    url?: string;
+    title?: string;
+    createdAt?: number;
+}
+/** List all open tabs for a user. */
+export declare function listTabs(options?: {
+    userId?: string;
+}): Promise<ListedTab[]>;
+export type BrowserApi = {
+    createTab: typeof createTab;
+    navigate: typeof navigate;
+    snapshot: typeof snapshot;
+    extract: typeof extract;
+    screenshot: typeof screenshot;
+    search: typeof search;
+    click: typeof click;
+    type: typeof type;
+    scroll: typeof scroll;
+    closeTab: typeof closeTab;
+    listTabs: typeof listTabs;
+    ensureServer: typeof ensureServer;
+    closeAll: typeof closeAll;
+};

package/dist/index.js

@@ -0,0 +1,368 @@
+/**
+ * @phi-code-admin/browser — programmatic browser API for phi-code.
+ *
+ * Boots the bundled `@phi-code-admin/camofox-browser` Express server on a
+ * private localhost port the first time any tool is called, then exposes
+ * the 10 OpenClaw tools as plain async functions. Shutdown is automatic
+ * on `process.exit` and can be triggered explicitly with `closeAll()`.
+ *
+ * Design constraints (per phi-code vendoring spec):
+ *   - Zero external network calls. The Camoufox binary is provided by
+ *     `@phi-code-admin/camoufox-bin-*` via npm optionalDependencies.
+ *   - The Express server is an implementation detail; consumers only see
+ *     ES module exports. The server can still be launched independently
+ *     via `npx @phi-code-admin/camofox-browser` for users who want REST.
+ *   - Each tool returns a JSON-serialisable object. No process objects,
+ *     no file handles, no streams — the result is safe to pass into a
+ *     TUI rendering layer or to serialise as a tool_result message.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import * as net from "node:net";
+import * as path from "node:path";
+const require = createRequire(import.meta.url);
+// ─── Server lifecycle ────────────────────────────────────────────────────
+let serverProcess = null;
+let serverPort = null;
+let bootPromise = null;
+const DEFAULT_USER_ID = "phi-default";
+const HEALTH_TIMEOUT_MS = 30_000;
+const HEALTH_POLL_INTERVAL_MS = 250;
+async function findAvailablePort() {
+    return await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address && typeof address !== "string") {
+                server.close(() => resolve(address.port));
+            }
+            else {
+                server.close();
+                reject(new Error("Could not allocate port"));
+            }
+        });
+    });
+}
+async function waitForHealth(baseUrl) {
+    const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`${baseUrl}/health`);
+            if (res.ok)
+                return;
+        }
+        catch {
+            // not yet
+        }
+        await new Promise((r) => setTimeout(r, HEALTH_POLL_INTERVAL_MS));
+    }
+    throw new Error(`camofox-browser server failed to become healthy at ${baseUrl} within ${HEALTH_TIMEOUT_MS}ms`);
+}
+function resolveServerEntry() {
+    // The vendored camofox-browser ships its Express entry as `server.js`
+    // (declared as the `main` field). createRequire resolves the package
+    // to that file even when consumers install us via npm/pnpm/yarn.
+    return require.resolve("@phi-code-admin/camofox-browser");
+}
+/**
+ * Boot (or reuse) the camofox-browser server. Idempotent across calls.
+ */
+export async function ensureServer() {
+    if (bootPromise)
+        return bootPromise;
+    bootPromise = (async () => {
+        const port = await findAvailablePort();
+        const entry = resolveServerEntry();
+        const cwd = path.dirname(entry);
+        const env = {
+            ...process.env,
+            PORT: String(port),
+            // Disable telemetry by default (PHI-VENDOR contract).
+            CAMOFOX_CRASH_REPORT_URL: process.env.CAMOFOX_CRASH_REPORT_URL || "",
+            // Tighten resource caps; phi-code is interactive, so 2 sessions
+            // with 4 tabs each is plenty. Override with the env var.
+            MAX_SESSIONS: process.env.MAX_SESSIONS || "2",
+            MAX_TABS_PER_SESSION: process.env.MAX_TABS_PER_SESSION || "4",
+        };
+        const child = spawn(process.execPath, [entry], {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: false,
+        });
+        // Surface crashes during boot, but never propagate to the consumer.
+        child.stderr?.on("data", (chunk) => {
+            if (process.env.PHI_BROWSER_VERBOSE) {
+                process.stderr.write(`[camofox] ${chunk}`);
+            }
+        });
+        child.on("exit", (code) => {
+            serverProcess = null;
+            serverPort = null;
+            bootPromise = null;
+            if (process.env.PHI_BROWSER_VERBOSE) {
+                process.stderr.write(`[camofox] server exited with code ${code}\n`);
+            }
+        });
+        serverProcess = child;
+        serverPort = port;
+        const baseUrl = `http://127.0.0.1:${port}`;
+        await waitForHealth(baseUrl);
+        return { baseUrl };
+    })();
+    try {
+        return await bootPromise;
+    }
+    catch (err) {
+        bootPromise = null;
+        serverProcess = null;
+        serverPort = null;
+        throw err;
+    }
+}
+/**
+ * Kill the embedded camofox-browser server (if running) and reset state.
+ * Safe to call multiple times. Resolves once the child has exited.
+ */
+export async function closeAll() {
+    const proc = serverProcess;
+    bootPromise = null;
+    serverProcess = null;
+    serverPort = null;
+    if (!proc)
+        return;
+    return await new Promise((resolve) => {
+        const done = () => resolve();
+        proc.once("exit", done);
+        try {
+            proc.kill("SIGTERM");
+        }
+        catch {
+            done();
+            return;
+        }
+        // Hard fallback after 2s — Firefox can take a moment.
+        setTimeout(() => {
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                /* already dead */
+            }
+        }, 2_000);
+    });
+}
+// Best-effort cleanup on process exit. Async cleanup is allowed in the
+// `beforeExit` phase; `exit` is sync-only so we can only request a kill.
+process.on("beforeExit", () => {
+    void closeAll();
+});
+process.on("exit", () => {
+    const proc = serverProcess;
+    if (proc) {
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            /* no-op */
+        }
+    }
+});
+async function request(pathname, options = {}) {
+    const { baseUrl } = await ensureServer();
+    const url = `${baseUrl}${pathname}`;
+    const method = options.method ?? "GET";
+    const headers = {
+        "Content-Type": "application/json",
+        ...(options.headers ?? {}),
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 60_000);
+    try {
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let parsed = undefined;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            const message = typeof parsed === "object" && parsed && "error" in parsed
+                ? String(parsed.error)
+                : `HTTP ${res.status}`;
+            throw new Error(`${method} ${pathname} → ${message}`);
+        }
+        return parsed;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Open a new browser tab. Returns the tab id used by the other tools. */
+export async function createTab(options) {
+    const userId = options.userId ?? DEFAULT_USER_ID;
+    const body = { userId };
+    if (options.url)
+        body.url = options.url;
+    if (options.viewport)
+        body.viewport = options.viewport;
+    const res = await request("/tabs", { method: "POST", body });
+    return { tabId: res.tabId, userId, url: options.url };
+}
+/**
+ * Navigate the given tab (or a freshly opened one) to a URL.
+ * High-level convenience: passing `url` without `tabId` opens a new tab
+ * first.
+ */
+export async function navigate(options) {
+    let tabId = options.tabId;
+    if (!tabId) {
+        const tab = await createTab({ userId: options.userId, url: options.url });
+        tabId = tab.tabId;
+        return { tabId, url: options.url };
+    }
+    const body = { url: options.url };
+    if (options.waitUntil)
+        body.waitUntil = options.waitUntil;
+    if (options.timeoutMs)
+        body.timeoutMs = options.timeoutMs;
+    const res = await request(`/tabs/${encodeURIComponent(tabId)}/navigate`, { method: "POST", body });
+    return { tabId, url: options.url, status: res.status, loadEvent: res.loadEvent };
+}
+/**
+ * Get an accessibility snapshot (DOM tree with ref ids) of the given tab.
+ * Refs returned here can be used with `click`/`type`/`scroll`.
+ */
+export async function snapshot(options) {
+    return await request(`/tabs/${encodeURIComponent(options.tabId)}/snapshot`);
+}
+/**
+ * Extract the readable content of the current page (Readability-style).
+ * For a fresh page, pass `url` to navigate first; otherwise the tab's
+ * current document is extracted.
+ */
+export async function extract(options) {
+    let tabId = options.tabId;
+    if (!tabId) {
+        if (!options.url) {
+            throw new Error("extract() requires either tabId or url");
+        }
+        const tab = await createTab({ userId: options.userId, url: options.url });
+        tabId = tab.tabId;
+        // Wait for the navigation to settle before extracting.
+        await request(`/tabs/${encodeURIComponent(tabId)}/wait`, {
+            method: "POST",
+            body: { event: "load" },
+        }).catch(() => { });
+    }
+    else if (options.url) {
+        await navigate({ tabId, url: options.url });
+    }
+    const res = await request(`/tabs/${encodeURIComponent(tabId)}/extract`, {
+        method: "POST",
+        body: { mode: options.mode ?? "readability" },
+    });
+    return res;
+}
+/** Capture a screenshot of the given tab as a base64-encoded PNG. */
+export async function screenshot(options) {
+    const query = new URLSearchParams();
+    if (options.fullPage)
+        query.set("fullPage", "1");
+    if (options.clip)
+        query.set("clip", JSON.stringify(options.clip));
+    const qs = query.toString();
+    const res = await request(`/tabs/${encodeURIComponent(options.tabId)}/screenshot${qs ? `?${qs}` : ""}`);
+    return {
+        tabId: options.tabId,
+        mimeType: res.mimeType ?? "image/png",
+        bytesBase64: res.image ?? "",
+    };
+}
+/**
+ * High-level search macro: opens a new tab, navigates to a search engine
+ * macro (`?q=...` on Google / DDG depending on host config), and returns
+ * the readability extraction of the result page.
+ */
+export async function search(options) {
+    const engine = options.engine ?? "duckduckgo";
+    const url = engine === "google"
+        ? `https://www.google.com/search?q=${encodeURIComponent(options.query)}`
+        : engine === "bing"
+            ? `https://www.bing.com/search?q=${encodeURIComponent(options.query)}`
+            : `https://duckduckgo.com/?q=${encodeURIComponent(options.query)}`;
+    return await extract({ url, userId: options.userId });
+}
+/** Click an element by ref (from `snapshot`) or CSS selector. */
+export async function click(options) {
+    if (!options.ref && !options.selector) {
+        throw new Error("click() requires `ref` or `selector`");
+    }
+    const body = {};
+    if (options.ref)
+        body.ref = options.ref;
+    if (options.selector)
+        body.selector = options.selector;
+    if (options.button)
+        body.button = options.button;
+    await request(`/tabs/${encodeURIComponent(options.tabId)}/click`, {
+        method: "POST",
+        body,
+    });
+    return { tabId: options.tabId };
+}
+/** Type text into a focused element (or one targeted via ref/selector). */
+export async function type(options) {
+    const body = { text: options.text };
+    if (options.ref)
+        body.ref = options.ref;
+    if (options.selector)
+        body.selector = options.selector;
+    if (options.pressEnter)
+        body.pressEnter = options.pressEnter;
+    if (options.delayMs !== undefined)
+        body.delayMs = options.delayMs;
+    await request(`/tabs/${encodeURIComponent(options.tabId)}/type`, {
+        method: "POST",
+        body,
+    });
+    return { tabId: options.tabId };
+}
+/** Scroll the page or a specific element by ref. */
+export async function scroll(options) {
+    const body = { direction: options.direction };
+    if (options.ref)
+        body.ref = options.ref;
+    if (options.pixels)
+        body.pixels = options.pixels;
+    await request(`/tabs/${encodeURIComponent(options.tabId)}/scroll`, {
+        method: "POST",
+        body,
+    });
+    return { tabId: options.tabId };
+}
+/** Close a single tab. The underlying browser context is kept warm. */
+export async function closeTab(options) {
+    await request(`/tabs/${encodeURIComponent(options.tabId)}`, { method: "DELETE" });
+    return { tabId: options.tabId };
+}
+/** List all open tabs for a user. */
+export async function listTabs(options = {}) {
+    const userId = options.userId ?? DEFAULT_USER_ID;
+    const metrics = await request(`/sessions/${encodeURIComponent(userId)}/tabs`).catch(async () => {
+        const all = await request("/metrics").catch(() => ({}));
+        return { tabs: Array.isArray(all.tabs) ? all.tabs : [] };
+    });
+    return metrics.tabs ?? [];
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@phi-code-admin/browser",
+	"version": "1.0.0",
+	"description": "Phi-code browser automation API: lazy-start the bundled Camoufox + camofox-browser server and expose 10 high-level tools (navigate, extract, screenshot, click, type, scroll, snapshot, search, close_tab, list_tabs) as plain ES module functions. Zero external dependencies at runtime.",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"license": "MIT",
+	"author": "uglyswap (phi-code maintainer)",
+	"homepage": "https://github.com/uglyswap/phi-code/tree/main/packages/browser",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/uglyswap/phi-code.git",
+		"directory": "packages/browser"
+	},
+	"bugs": {
+		"url": "https://github.com/uglyswap/phi-code/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"clean": "rimraf dist"
+	},
+	"dependencies": {
+		"@phi-code-admin/camofox-browser": "1.0.0",
+		"@phi-code-admin/camoufox-js": "1.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^24.0.0",
+		"rimraf": "^6.0.1",
+		"typescript": "^5.7.0"
+	}
+}