@phi-code-admin/browser 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -30,11 +30,21 @@ export declare function closeAll(): Promise<void>;
 export interface CreateTabResult {
     tabId: string;
     userId: string;
+    sessionKey: string;
     url?: string;
 }
-/** Open a new browser tab. Returns the tab id used by the other tools. */
-export declare function createTab(options: {
+/**
+ * Open a new browser tab. Returns the tab id used by the other tools.
+ *
+ * The camofox-browser REST contract requires every tab to be associated
+ * with a `userId` (logical user) AND a `sessionKey` (logical session
+ * inside that user — used to group tabs that should share cookies /
+ * fingerprints / proxies). Phi-code's chat agents only need one of each,
+ * so both default to a constant sentinel when omitted.
+ */
+export declare function createTab(options?: {
     userId?: string;
+    sessionKey?: string;
     url?: string;
     viewport?: {
         width: number;
@@ -56,6 +66,7 @@ export declare function navigate(options: {
     url: string;
     tabId?: string;
     userId?: string;
+    sessionKey?: string;
     waitUntil?: "load" | "domcontentloaded" | "networkidle";
     timeoutMs?: number;
 }): Promise<NavigateResult>;
@@ -65,6 +76,7 @@ export declare function navigate(options: {
  */
 export declare function snapshot(options: {
     tabId: string;
+    userId?: string;
 }): Promise<unknown>;
 export interface ExtractResult {
     url?: string;
@@ -82,6 +94,7 @@ export interface ExtractResult {
 export declare function extract(options: {
     tabId?: string;
     userId?: string;
+    sessionKey?: string;
     url?: string;
     mode?: "readability" | "html" | "text";
 }): Promise<ExtractResult>;
@@ -93,6 +106,7 @@ export interface ScreenshotResult {
 /** Capture a screenshot of the given tab as a base64-encoded PNG. */
 export declare function screenshot(options: {
     tabId: string;
+    userId?: string;
     fullPage?: boolean;
     clip?: {
         x: number;
@@ -110,10 +124,12 @@ export declare function search(options: {
     query: string;
     engine?: "google" | "duckduckgo" | "bing";
     userId?: string;
+    sessionKey?: string;
 }): Promise<ExtractResult>;
 /** Click an element by ref (from `snapshot`) or CSS selector. */
 export declare function click(options: {
     tabId: string;
+    userId?: string;
     ref?: string;
     selector?: string;
     button?: "left" | "right" | "middle";
@@ -123,6 +139,7 @@ export declare function click(options: {
 /** Type text into a focused element (or one targeted via ref/selector). */
 export declare function type(options: {
     tabId: string;
+    userId?: string;
     text: string;
     ref?: string;
     selector?: string;
@@ -134,6 +151,7 @@ export declare function type(options: {
 /** Scroll the page or a specific element by ref. */
 export declare function scroll(options: {
     tabId: string;
+    userId?: string;
     direction: "up" | "down" | "left" | "right";
     ref?: string;
     pixels?: number;
@@ -143,6 +161,7 @@ export declare function scroll(options: {
 /** Close a single tab. The underlying browser context is kept warm. */
 export declare function closeTab(options: {
     tabId: string;
+    userId?: string;
 }): Promise<{
     tabId: string;
 }>;

package/dist/index.js

@@ -26,6 +26,7 @@ let serverProcess = null;
 let serverPort = null;
 let bootPromise = null;
 const DEFAULT_USER_ID = "phi-default";
+const DEFAULT_SESSION_KEY = "phi-default-session";
 const HEALTH_TIMEOUT_MS = 30_000;
 const HEALTH_POLL_INTERVAL_MS = 250;
 async function findAvailablePort() {
@@ -92,24 +93,58 @@ export async function ensureServer() {
             stdio: ["ignore", "pipe", "pipe"],
             detached: false,
         });
-        // Surface crashes during boot, but never propagate to the consumer.
+        // Surface child stderr so the user can see crash reasons. Once the
+        // server has become healthy we go quiet again unless
+        // PHI_BROWSER_VERBOSE=1 is set. Boot-time crashes ALWAYS print —
+        // otherwise a silent E22-style "failed to become healthy" exception
+        // is unsurmountable from the consumer side.
+        const stderrTail = [];
+        let healthy = false;
         child.stderr?.on("data", (chunk) => {
-            if (process.env.PHI_BROWSER_VERBOSE) {
-                process.stderr.write(`[camofox] ${chunk}`);
+            const text = chunk.toString();
+            if (!healthy || process.env.PHI_BROWSER_VERBOSE) {
+                process.stderr.write(`[camofox] ${text}`);
             }
+            stderrTail.push(text);
+            while (stderrTail.length > 200)
+                stderrTail.shift();
         });
         child.on("exit", (code) => {
             serverProcess = null;
             serverPort = null;
             bootPromise = null;
-            if (process.env.PHI_BROWSER_VERBOSE) {
+            if (!healthy || process.env.PHI_BROWSER_VERBOSE) {
                 process.stderr.write(`[camofox] server exited with code ${code}\n`);
             }
         });
+        // Expose stderr tail through a wrapper that promotes the listener
+        // flip — needed below when waitForHealth resolves.
+        child.__markHealthy = () => {
+            healthy = true;
+        };
+        child.__stderrTail = stderrTail;
         serverProcess = child;
         serverPort = port;
         const baseUrl = `http://127.0.0.1:${port}`;
-        await waitForHealth(baseUrl);
+        try {
+            await waitForHealth(baseUrl);
+            child.__markHealthy?.();
+        }
+        catch (err) {
+            // Augment the health-check error with whatever the child wrote to
+            // stderr so the consumer has at least one breadcrumb to follow.
+            const tail = (child.__stderrTail ?? [])
+                .join("")
+                .split(/\r?\n/)
+                .filter(Boolean)
+                .slice(-20)
+                .join("\n");
+            const original = err instanceof Error ? err.message : String(err);
+            const augmented = new Error(tail
+                ? `${original}\nLast stderr lines from camofox-browser child:\n${tail}`
+                : `${original}\n(no stderr captured — set PHI_BROWSER_VERBOSE=1 for more)`);
+            throw augmented;
+        }
         return { baseUrl };
     })();
     try {
@@ -209,16 +244,25 @@ async function request(pathname, options = {}) {
         clearTimeout(timeout);
     }
 }
-/** Open a new browser tab. Returns the tab id used by the other tools. */
-export async function createTab(options) {
+/**
+ * Open a new browser tab. Returns the tab id used by the other tools.
+ *
+ * The camofox-browser REST contract requires every tab to be associated
+ * with a `userId` (logical user) AND a `sessionKey` (logical session
+ * inside that user — used to group tabs that should share cookies /
+ * fingerprints / proxies). Phi-code's chat agents only need one of each,
+ * so both default to a constant sentinel when omitted.
+ */
+export async function createTab(options = {}) {
     const userId = options.userId ?? DEFAULT_USER_ID;
-    const body = { userId };
+    const sessionKey = options.sessionKey ?? DEFAULT_SESSION_KEY;
+    const body = { userId, sessionKey };
     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 };
+    return { tabId: res.tabId, userId, sessionKey, url: options.url };
 }
 /**
  * Navigate the given tab (or a freshly opened one) to a URL.
@@ -228,11 +272,19 @@ export async function createTab(options) {
 export async function navigate(options) {
     let tabId = options.tabId;
     if (!tabId) {
-        const tab = await createTab({ userId: options.userId, url: options.url });
+        const tab = await createTab({
+            userId: options.userId,
+            sessionKey: options.sessionKey,
+            url: options.url,
+        });
         tabId = tab.tabId;
         return { tabId, url: options.url };
     }
-    const body = { url: options.url };
+    const body = {
+        userId: options.userId ?? DEFAULT_USER_ID,
+        sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+        url: options.url,
+    };
     if (options.waitUntil)
         body.waitUntil = options.waitUntil;
     if (options.timeoutMs)
@@ -245,7 +297,9 @@ export async function navigate(options) {
  * Refs returned here can be used with `click`/`type`/`scroll`.
  */
 export async function snapshot(options) {
-    return await request(`/tabs/${encodeURIComponent(options.tabId)}/snapshot`);
+    const userId = options.userId ?? DEFAULT_USER_ID;
+    const qs = `?userId=${encodeURIComponent(userId)}`;
+    return await request(`/tabs/${encodeURIComponent(options.tabId)}/snapshot${qs}`);
 }
 /**
  * Extract the readable content of the current page (Readability-style).
@@ -258,32 +312,45 @@ export async function extract(options) {
         if (!options.url) {
             throw new Error("extract() requires either tabId or url");
         }
-        const tab = await createTab({ userId: options.userId, url: options.url });
+        const tab = await createTab({
+            userId: options.userId,
+            sessionKey: options.sessionKey,
+            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" },
+            body: { userId: options.userId ?? DEFAULT_USER_ID, event: "load" },
         }).catch(() => { });
     }
     else if (options.url) {
-        await navigate({ tabId, url: options.url });
+        await navigate({
+            tabId,
+            url: options.url,
+            userId: options.userId,
+            sessionKey: options.sessionKey,
+        });
     }
     const res = await request(`/tabs/${encodeURIComponent(tabId)}/extract`, {
         method: "POST",
-        body: { mode: options.mode ?? "readability" },
+        body: {
+            userId: options.userId ?? DEFAULT_USER_ID,
+            sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+            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();
+    query.set("userId", options.userId ?? DEFAULT_USER_ID);
     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}` : ""}`);
+    const res = await request(`/tabs/${encodeURIComponent(options.tabId)}/screenshot?${query.toString()}`);
     return {
         tabId: options.tabId,
         mimeType: res.mimeType ?? "image/png",
@@ -302,14 +369,14 @@ export async function search(options) {
         : 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 });
+    return await extract({ url, userId: options.userId, sessionKey: options.sessionKey });
 }
 /** 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 = {};
+    const body = { userId: options.userId ?? DEFAULT_USER_ID };
     if (options.ref)
         body.ref = options.ref;
     if (options.selector)
@@ -324,7 +391,10 @@ export async function click(options) {
 }
 /** Type text into a focused element (or one targeted via ref/selector). */
 export async function type(options) {
-    const body = { text: options.text };
+    const body = {
+        userId: options.userId ?? DEFAULT_USER_ID,
+        text: options.text,
+    };
     if (options.ref)
         body.ref = options.ref;
     if (options.selector)
@@ -341,7 +411,10 @@ export async function type(options) {
 }
 /** Scroll the page or a specific element by ref. */
 export async function scroll(options) {
-    const body = { direction: options.direction };
+    const body = {
+        userId: options.userId ?? DEFAULT_USER_ID,
+        direction: options.direction,
+    };
     if (options.ref)
         body.ref = options.ref;
     if (options.pixels)
@@ -354,7 +427,9 @@ export async function scroll(options) {
 }
 /** Close a single tab. The underlying browser context is kept warm. */
 export async function closeTab(options) {
-    await request(`/tabs/${encodeURIComponent(options.tabId)}`, { method: "DELETE" });
+    const userId = options.userId ?? DEFAULT_USER_ID;
+    const qs = `?userId=${encodeURIComponent(userId)}`;
+    await request(`/tabs/${encodeURIComponent(options.tabId)}${qs}`, { method: "DELETE" });
     return { tabId: options.tabId };
 }
 /** List all open tabs for a user. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/browser",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"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",
@@ -38,7 +38,7 @@
 		"clean": "rimraf dist"
 	},
 	"dependencies": {
-		"@phi-code-admin/camofox-browser": "1.0.0",
+		"@phi-code-admin/camofox-browser": "1.0.1",
 		"@phi-code-admin/camoufox-js": "1.0.0"
 	},
 	"devDependencies": {