@deepraxis/sdk 0.1.1-dev.f8aa5de → 0.1.1-dev.fee48ec

package/dist/helpers/browser-actions.d.ts

@@ -0,0 +1,84 @@
+/**
+ * ticket-944 — the `actions` driver: the Browser service driven over the public HTTP faces, with no Playwright and
+ * no `node:child_process`. A light machine cannot install `playwright-core` at all, so instead of asking to be
+ * upgraded it drives the same cloud session through:
+ *
+ *   GET  /browser/v1/sessions?name=<name>&status=RUNNING   the live session this agent session already has
+ *   POST /browser/v1/sessions                              open one under that name when there is none
+ *   POST /browser/v1/sessions/<id>/actions                 run one page action (#942)
+ *
+ * The service executes each action on the session's own CDP control connection, so `open` / `click` / `fill` / …
+ * keep working on a machine with no browser stack of its own
+ * (`services/browser/src/domain/page-actions.ts`).
+ */
+/** Where screenshots land, matching the Playwright driver's directory. */
+export declare const SCREENSHOT_DIR = ".praxis/screenshots";
+/** The two `fs/promises` members this driver uses; the light isolate provides `fs/promises`, never sync `fs`. */
+export interface FsPromisesLike {
+    mkdir(path: string, options: {
+        recursive: true;
+    }): Promise<unknown>;
+    writeFile(path: string, data: Uint8Array): Promise<unknown>;
+}
+/** What the actions driver needs from the platform and the process. All of it is injectable for tests. */
+export interface BrowserActionsDeps {
+    api: string;
+    token: string;
+    /** The cloud session name — the agent session id, exactly as the Playwright path's connect URL uses it. */
+    name: string;
+    labels: Record<string, string>;
+    /** Browser context id (bsc_…) carrying saved sign-ins; omitted without one. */
+    context?: string;
+    home: string;
+    fetch: typeof globalThis.fetch;
+    fs: FsPromisesLike;
+    now: () => number;
+}
+/** An existing tab as `tabs.list` reports it. */
+export interface ActionTabInfo {
+    id: string;
+    url: string;
+    title: string;
+    active: boolean;
+}
+/** A page action's answer, structurally: every result kind carries at least `type`. */
+type ActionAnswer = Record<string, unknown> & {
+    type?: unknown;
+};
+/** `~/.praxis/screenshots/<timestamp>-<tab>.png`, the Playwright driver's own naming. */
+export declare const screenshotPath: (home: string, tab: string, now: number) => string;
+/**
+ * base64 → bytes, without Buffer or atob: the light machine's isolate is promised neither, and the screenshot is
+ * the one binary this file writes. Characters outside the alphabet are ignored, as base64 decoders do.
+ */
+export declare function decodeBase64(text: string): Uint8Array;
+/** One tab handle: every method is one page action on the resolved session. */
+export interface ActionsTab {
+    readonly id: string;
+    snapshot(): Promise<string>;
+    click(ref: string): Promise<void>;
+    fill(ref: string, text: string): Promise<void>;
+    press(key: string): Promise<void>;
+    scroll(direction: 'up' | 'down', pixels?: number): Promise<void>;
+    evaluate(expression: string): Promise<unknown>;
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<{
+        path: string;
+        hint: string;
+    }>;
+}
+/** The page-action client: session resolution, one request per action, one tab handle per tab id. */
+export interface BrowserActions {
+    sessionId(): Promise<string>;
+    list(): Promise<ActionTabInfo[]>;
+    tab(id: string): ActionsTab;
+    /** One already-built action, for the shapes no tab method covers. */
+    action(body: Record<string, unknown>): Promise<ActionAnswer>;
+}
+/**
+ * Builds the actions client. It never opens a connection, imports Playwright, or reads a Node builtin: a session
+ * id is resolved once per call from the name, and every action is a request that returns its own answer.
+ */
+export declare function createBrowserActions(deps: BrowserActionsDeps): BrowserActions;
+export {};

package/dist/helpers/browser-actions.js

@@ -0,0 +1,141 @@
+/**
+ * ticket-944 — the `actions` driver: the Browser service driven over the public HTTP faces, with no Playwright and
+ * no `node:child_process`. A light machine cannot install `playwright-core` at all, so instead of asking to be
+ * upgraded it drives the same cloud session through:
+ *
+ *   GET  /browser/v1/sessions?name=<name>&status=RUNNING   the live session this agent session already has
+ *   POST /browser/v1/sessions                              open one under that name when there is none
+ *   POST /browser/v1/sessions/<id>/actions                 run one page action (#942)
+ *
+ * The service executes each action on the session's own CDP control connection, so `open` / `click` / `fill` / …
+ * keep working on a machine with no browser stack of its own
+ * (`services/browser/src/domain/page-actions.ts`).
+ */
+import { PraxisError } from "../core/errors.js";
+/** The public own-face path prefix — the same one this SDK's connect URL is built on. */
+const BROWSER_V1 = '/browser/v1';
+/** Where screenshots land, matching the Playwright driver's directory. */
+export const SCREENSHOT_DIR = '.praxis/screenshots';
+/**
+ * A refusal becomes an error here and nowhere else: the server's own code, status and message travel unchanged,
+ * so ACTION_REF_STALE stays distinguishable from an outage (ticket-834's rule, for the actions door).
+ */
+function failure(status, body) {
+    const record = body;
+    const code = typeof record?.code === 'string' ? record.code : undefined;
+    const message = typeof record?.message === 'string' ? record.message
+        : typeof record?.error === 'string' ? record.error
+            : `The browser action failed with HTTP ${status}.`;
+    return new PraxisError({ status, ...(code === undefined ? {} : { code }), message, raw: body });
+}
+/** `~/.praxis/screenshots/<timestamp>-<tab>.png`, the Playwright driver's own naming. */
+export const screenshotPath = (home, tab, now) => `${home}/${SCREENSHOT_DIR}/${now}-${tab.slice(0, 8)}.png`;
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * base64 → bytes, without Buffer or atob: the light machine's isolate is promised neither, and the screenshot is
+ * the one binary this file writes. Characters outside the alphabet are ignored, as base64 decoders do.
+ */
+export function decodeBase64(text) {
+    const clean = text.replace(/[^A-Za-z0-9+/]/g, '');
+    const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
+    let byte = 0;
+    let bits = 0;
+    let written = 0;
+    for (const character of clean) {
+        const value = ALPHABET.indexOf(character);
+        if (value < 0)
+            continue;
+        byte = (byte << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[written++] = (byte >> bits) & 0xff;
+        }
+    }
+    return out.subarray(0, written);
+}
+/**
+ * Builds the actions client. It never opens a connection, imports Playwright, or reads a Node builtin: a session
+ * id is resolved once per call from the name, and every action is a request that returns its own answer.
+ */
+export function createBrowserActions(deps) {
+    const request = async (path, init = {}) => {
+        const headers = {
+            Authorization: `Bearer ${deps.token}`,
+            ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+            ...(init.headers ?? {}),
+        };
+        let response;
+        try {
+            response = await deps.fetch(`${deps.api}${BROWSER_V1}${path}`, { ...init, headers });
+        }
+        catch (cause) {
+            throw new PraxisError({ status: 503, code: 'BROWSER_UNAVAILABLE', message: `Reaching the cloud browser failed: ${cause.message.split('\n')[0]}` });
+        }
+        const text = await response.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            body = text;
+        }
+        if (!response.ok)
+            throw failure(response.status, body);
+        return body;
+    };
+    /** Resolved once per client: one connect() is one program, and the session it named does not change inside it. */
+    let resolved;
+    /** The live session named for this agent session, else a new one under that name. */
+    const sessionId = async () => {
+        resolved ??= (async () => {
+            const found = (await request(`/sessions?name=${encodeURIComponent(deps.name)}&status=RUNNING`));
+            // A page holds only this account's sessions, but a name is what identifies ours: anything else is not it.
+            const live = (found?.data ?? []).find(row => typeof row.id === 'string' && row.name === deps.name);
+            if (live?.id)
+                return live.id;
+            const created = (await request('/sessions', {
+                method: 'POST',
+                body: JSON.stringify({
+                    name: deps.name,
+                    labels: deps.labels,
+                    ...(deps.context === undefined ? {} : { browserSettings: { context: { id: deps.context, persist: true } } }),
+                }),
+            }));
+            if (typeof created?.id !== 'string')
+                throw new PraxisError({ status: 503, code: 'BROWSER_UNAVAILABLE', message: 'The cloud browser session could not be opened.' });
+            return created.id;
+        })();
+        // A failed resolution is not cached: the next action may find the service again.
+        return await resolved.catch(cause => { resolved = undefined; throw cause; });
+    };
+    const action = async (body) => {
+        const id = await sessionId();
+        return (await request(`/sessions/${encodeURIComponent(id)}/actions`, { method: 'POST', body: JSON.stringify(body) }));
+    };
+    const list = async () => {
+        const answer = await action({ type: 'tabs.list' });
+        return (answer.tabs ?? []).map(tab => ({ id: tab.id, url: tab.url, title: tab.title, active: tab.active }));
+    };
+    const tab = (id) => {
+        const on = (type, extra = {}) => action({ type, tab: id, ...extra });
+        return {
+            id,
+            // The server's own rendering; same reading model as the Playwright driver's ariaSnapshot({ mode: "ai" }).
+            snapshot: async () => String((await on('snapshot')).snapshot ?? ''),
+            click: async (ref) => { await on('click', { ref }); },
+            fill: async (ref, text) => { await on('fill', { ref, text }); },
+            press: async (key) => { await on('press', { key }); },
+            scroll: async (direction, pixels) => { await on('scroll', { direction, ...(pixels === undefined ? {} : { pixels }) }); },
+            evaluate: async (expression) => (await on('evaluate', { expression })).value,
+            screenshot: async (options) => {
+                const answer = await on('screenshot', options?.fullPage === true ? { fullPage: true } : {});
+                const path = screenshotPath(deps.home, id, deps.now());
+                await deps.fs.mkdir(`${deps.home}/${SCREENSHOT_DIR}`, { recursive: true });
+                await deps.fs.writeFile(path, decodeBase64(String(answer.data ?? '')));
+                return { path, hint: 'View this PNG with the Read tool.' };
+            },
+        };
+    };
+    return { sessionId, list, tab, action };
+}

package/dist/helpers/browser-connect.d.ts

@@ -6,7 +6,7 @@ export declare const PLAYWRIGHT_CORE_VERSION = "1.63.0";
 export type PlaywrightPage = any;
 export interface BrowserTab {
     readonly id: string;
-    /** The Playwright Page for locators and waits. */
+    /** The Playwright Page for locators and waits. Absent in the `actions` driver, where reading it throws. */
     readonly playwright: PlaywrightPage;
     goto(url: string): Promise<void>;
     back(): Promise<void>;
@@ -15,8 +15,18 @@ export interface BrowserTab {
     close(): Promise<void>;
     url(): Promise<string>;
     title(): Promise<string>;
-    /** The page as a Playwright ARIA snapshot with [ref=eN] marks. */
+    /** The page as an accessibility snapshot with [ref=eN] marks: Playwright's, or the server's own text. */
     snapshot(): Promise<string>;
+    /** Clicks the element a snapshot marked `[ref=eN]`. */
+    click(ref: string): Promise<void>;
+    /** Fills the element a snapshot marked `[ref=eN]`. */
+    fill(ref: string, text: string): Promise<void>;
+    /** Presses one key (Enter, Tab, a single character). */
+    press(key: string): Promise<void>;
+    /** Scrolls the page by `pixels` (default 800) in one direction. */
+    scroll(direction: 'up' | 'down', pixels?: number): Promise<void>;
+    /** Evaluates an expression in the page and returns its value. */
+    evaluate(expression: string): Promise<unknown>;
     /** Writes a PNG under ~/.praxis/screenshots and returns its path; view it with the Read tool. */
     screenshot(options?: {
         fullPage?: boolean;
@@ -47,6 +57,7 @@ interface ContextsApi {
         query?: {
             limit?: number;
             cursor?: string;
+            name?: string;
         };
     }): Promise<{
         data: (ContextLike & {
@@ -61,6 +72,15 @@ interface ContextsApi {
         };
     }): Promise<ContextLike>;
 }
+/** The playwright-core module shape the helper uses. */
+export interface PlaywrightModule {
+    chromium: {
+        connectOverCDP(url: string, options: {
+            headers: Record<string, string>;
+            timeout?: number;
+        }): Promise<unknown>;
+    };
+}
 /** What connect() needs from the platform client and the process. All of it is injectable for tests. */
 export interface BrowserConnectDeps {
     contexts: ContextsApi;
@@ -68,6 +88,10 @@ export interface BrowserConnectDeps {
     /** process.getBuiltinModule; undefined on runtimes without it. */
     builtin: ((name: string) => unknown) | undefined;
     now?: () => number;
+    /** An already-loaded playwright-core; the real loader finds or installs one and imports it. */
+    playwright?: PlaywrightModule;
+    /** The fetch the actions driver sends its requests with; globalThis.fetch by default. */
+    fetch?: typeof globalThis.fetch;
 }
 export declare const unavailable: (message: string) => PraxisError;
 /** Same signal the plugin installer and child_process use: the light machine asks to be upgraded and the program runs again. */

package/dist/helpers/browser-connect.js

@@ -8,11 +8,14 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { PraxisError } from "../core/errors.js";
 import { BROWSER_DOCUMENTATION } from "./browser-documentation.js";
-import { agentContextName, buildConnectUrl, decideTabReuse, pickAgentContext } from "./browser-decisions.js";
+import { createBrowserActions } from "./browser-actions.js";
+import { agentContextName, buildConnectUrl, decideBrowserDriver, decideTabReuse, isDuplicateNameError, matchTargetsToPages, pickAgentContext, pickContextByName } from "./browser-decisions.js";
 /** Version of the Playwright client library: preinstalled in the base image, installed on demand elsewhere. */
 export const PLAYWRIGHT_CORE_VERSION = '1.63.0';
 const GLOBAL_PLAYWRIGHT = '/usr/local/lib/node_modules/playwright-core';
 const IDLE_MS = 300_000;
+/** A scroll without a distance moves this far, the server's own default (PAGE_ACTION_LIMITS.scrollPixelsDefault). */
+const SCROLL_PIXELS_DEFAULT = 800;
 export const unavailable = (message) => new PraxisError({ status: 503, code: 'BROWSER_UNAVAILABLE', message });
 /** Same signal the plugin installer and child_process use: the light machine asks to be upgraded and the program runs again. */
 export const needsFullMachine = () => Object.assign(new Error('The cloud browser needs a full sandbox — upgrade this instance'), { code: 'PROGRAM_NEEDS_FULL_MACHINE' });
@@ -32,7 +35,34 @@ function node(deps, name) {
     }
     throw needsFullMachine();
 }
+/**
+ * Whether this runtime can load `node:child_process` — the one capability the Playwright driver needs and the
+ * actions driver does not. A refusal is a fact about the machine, never an error: it selects the driver.
+ */
+function hasChildProcess(deps) {
+    if (!deps.builtin)
+        return false;
+    try {
+        return Boolean(deps.builtin('node:child_process'));
+    }
+    catch {
+        return false;
+    }
+}
+/** An optional builtin: absent (or refused) answers undefined instead of throwing, for modules a driver may not need. */
+function optionalNode(deps, name) {
+    if (!deps.builtin)
+        return undefined;
+    try {
+        return deps.builtin(name) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function loadPlaywright(deps, home) {
+    if (deps.playwright)
+        return deps.playwright;
     node(deps, 'node:child_process'); // fails fast on a light machine, before any network work
     const fs = node(deps, 'node:fs');
     const entry = (root) => `${root}/index.mjs`;
@@ -49,22 +79,164 @@ async function loadPlaywright(deps, home) {
     }
     return await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `file://${entry(root)}`));
 }
+/** The agent's own context, in one name-filtered request; the paged scan is only the pre-`name` server fallback. */
 async function ensureContext(deps, agentId) {
-    const seen = [];
-    let cursor;
-    for (let page = 0; page < 20; page++) {
-        const result = await deps.contexts.list({ query: { limit: 100, ...(cursor ? { cursor } : {}) } });
-        seen.push(...result.data);
-        const own = pickAgentContext(seen, agentId);
-        if (own)
-            return own.id;
-        if (!result.nextCursor)
-            break;
-        cursor = result.nextCursor;
+    const name = agentContextName(agentId);
+    const byNameQuery = () => deps.contexts.list({ query: { name, limit: 1 } });
+    // A server that knows `name` answers with this agent's context or nothing; a non-empty answer of other rows means
+    // it ignored the filter, and only then is the paged scan worth its round trips.
+    const paged = async () => {
+        const seen = [];
+        let cursor;
+        for (let page = 0; page < 20; page++) {
+            const result = await deps.contexts.list({ query: { limit: 100, ...(cursor ? { cursor } : {}) } });
+            seen.push(...result.data);
+            const own = pickAgentContext(seen, agentId);
+            if (own)
+                return own.id;
+            if (!result.nextCursor)
+                break;
+            cursor = result.nextCursor;
+        }
+        return undefined;
+    };
+    const find = async () => {
+        const answer = (await byNameQuery()).data;
+        const byName = pickContextByName(answer, agentId);
+        if (byName)
+            return byName.id;
+        return answer.length > 0 ? paged() : undefined;
+    };
+    const existing = await find();
+    if (existing)
+        return existing;
+    try {
+        return (await deps.contexts.create({ body: { name, labels: { agent: agentId } } })).id;
+    }
+    catch (cause) {
+        // Names are unique per account, so this is a concurrent run winning the create: reuse what it made.
+        if (!isDuplicateNameError(cause))
+            throw cause;
+        const raced = await find();
+        if (raced)
+            return raced;
+        throw cause;
     }
-    return (await deps.contexts.create({ body: { name: agentContextName(agentId), labels: { agent: agentId } } })).id;
 }
 const bounded = (work, ms) => Promise.race([work, new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), ms))]);
+/**
+ * ticket-834 — an agent that is refused a browser must be able to tell "come back in 7 s" from "your key is
+ * wrong". Playwright's transport rejects with `WebSocket error: <url> <status> <statusWord>\n<body>` when the
+ * CDP upgrade is answered, wrapped by `browserType.connectOverCDP: `; the body is the only part that says
+ * which refusal it was and how long to wait, so parse it instead of reporting the first line as an outage.
+ */
+function refusedConnect(cause) {
+    if (!(cause instanceof Error))
+        return null;
+    const match = /WebSocket error: \S+ (\d{3}) [^\n]*\n([\s\S]+)$/.exec(cause.message);
+    if (!match)
+        return null;
+    const status = Number(match[1]);
+    let body;
+    try {
+        body = JSON.parse(match[2].trim());
+    }
+    catch {
+        return null;
+    }
+    if (typeof body?.code !== 'string')
+        return null;
+    const retryAfter = typeof body.retryAfter === 'number' && Number.isFinite(body.retryAfter) ? body.retryAfter : null;
+    const message = typeof body.message === 'string' ? body.message : undefined;
+    return new PraxisError({
+        status,
+        code: body.code,
+        message: `${message ?? body.code}${retryAfter === null ? '' : ` Retry after ${retryAfter} s.`}`,
+        raw: body,
+    });
+}
+/**
+ * The light machine's browser: every call is one page action over HTTP, so nothing here loads playwright-core,
+ * reads `node:child_process`, or keeps a connection open. Tabs are addressed by the CDP target id the service
+ * reports, which is the same id the Playwright driver hands out.
+ */
+async function connectActions(deps, settings) {
+    // fs/promises is what the light isolate provides (sync fs is refused there); screenshots go through it.
+    const fs = optionalNode(deps, 'node:fs/promises');
+    if (!fs)
+        throw unavailable('praxis.browser.connect() needs node:fs/promises on the session machine to save screenshots.');
+    const client = createBrowserActions({
+        api: settings.api, token: settings.token, name: settings.name,
+        labels: { agent_session: settings.name, agent: settings.agentId },
+        context: settings.context, home: settings.home, fs, now: settings.now,
+        // Bound: a Worker isolate (the light machine) throws "Illegal invocation" when fetch is called as a method of another object.
+        fetch: deps.fetch ?? globalThis.fetch.bind(globalThis),
+    });
+    const noPlaywright = () => new PraxisError({
+        status: 501, code: 'BROWSER_DRIVER_ACTIONS',
+        message: 'This machine drives the cloud browser through server-side page actions, so tab.playwright is not available. '
+            + 'Available: goto, back, forward, reload, url, title, snapshot, click(ref), fill(ref, text), press(key), scroll(direction, pixels), evaluate(expression), screenshot, close. '
+            + 'Run this program on an environment with the heavy machine template when a Playwright Page is required.',
+    });
+    /** One tab: the actions client plus the navigation shapes it does not own. */
+    const wrap = async (id) => {
+        const tab = client.tab(id);
+        /** Where the tab is now, in one action: evaluate answers url and title together. */
+        const located = () => tab.evaluate('({ url: location.href, title: document.title })');
+        return {
+            id,
+            get playwright() { throw noPlaywright(); },
+            goto: async (target) => { await client.action({ type: 'open', url: target, tab: id }); },
+            back: async () => { await client.action({ type: 'back', tab: id }); },
+            forward: async () => { await client.action({ type: 'forward', tab: id }); },
+            reload: async () => { await client.action({ type: 'reload', tab: id }); },
+            // The actions face has no close: report it, and leave the tab for the session to release.
+            close: async () => { throw unavailable('The server-side page actions have no close-tab action; leave the tab open and the cloud session releases it when it idles out.'); },
+            url: async () => String((await located()).url ?? ''),
+            title: async () => String((await located()).title ?? ''),
+            snapshot: () => tab.snapshot(),
+            click: ref => tab.click(ref),
+            fill: (ref, text) => tab.fill(ref, text),
+            press: key => tab.press(key),
+            scroll: (direction, pixels) => tab.scroll(direction, pixels ?? SCROLL_PIXELS_DEFAULT),
+            evaluate: expression => tab.evaluate(expression),
+            screenshot: options => tab.screenshot(options),
+        };
+    };
+    const ids = async () => (await client.list()).map(entry => entry.id);
+    const openTab = async (target, options) => {
+        const tabs = await client.list();
+        if (options?.reuseTab !== false) {
+            const reuse = decideTabReuse(target, tabs);
+            if (reuse) {
+                const tab = await wrap(reuse.id);
+                await tab.goto(target);
+                return tab;
+            }
+        }
+        const answer = await client.action({ type: 'open', url: target, ...(tabs.length === 0 ? {} : { newTab: true }) });
+        return await wrap(String(answer.tab ?? ''));
+    };
+    return {
+        tabs: {
+            list: () => client.list(),
+            get: async (id) => {
+                if (!(await ids()).includes(id))
+                    throw new PraxisError({ status: 404, code: 'TAB_NOT_FOUND', message: `No tab with id ${id}; call browser.tabs.list() for the current tabs.` });
+                return await wrap(id);
+            },
+            new: async () => {
+                // `open` with `newTab` is the only way the actions face creates a page.
+                const answer = await client.action({ type: 'open', url: 'about:blank', newTab: true });
+                return await wrap(String(answer.tab ?? ''));
+            },
+        },
+        open: openTab,
+        documentation: () => BROWSER_DOCUMENTATION,
+        /** Drops this connection's session id only; the cloud session is left to idle out, as in the Playwright path. */
+        disconnect: async () => undefined,
+    };
+}
 export async function connectBrowser(deps, options = {}) {
     const { PRAXIS_API: api, PRAXIS_RUN_TOKEN: token, PRAXIS_AGENT_ID: agentId, PRAXIS_SESSION_ID: sessionId } = deps.env;
     const missing = ['PRAXIS_API', 'PRAXIS_RUN_TOKEN', 'PRAXIS_AGENT_ID', 'PRAXIS_SESSION_ID'].filter(name => !deps.env[name]);
@@ -72,20 +244,52 @@ export async function connectBrowser(deps, options = {}) {
         throw unavailable(`praxis.browser.connect() runs inside an agent session; ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not set. Use praxis.browser.sessions.create() for a standalone cloud browser.`);
     }
     const home = deps.env.HOME ?? '/home/user';
-    const playwright = await loadPlaywright(deps, home);
+    const now = deps.now ?? Date.now;
+    const driver = decideBrowserDriver({ override: deps.env.PRAXIS_BROWSER_DRIVER, childProcessAvailable: hasChildProcess(deps) });
     const context = options.context === false ? undefined : await ensureContext(deps, agentId);
+    // The light machine drives the browser the service already runs; it never asks to be upgraded.
+    if (driver === 'actions')
+        return await connectActions(deps, { api, token, name: sessionId, agentId, home, context, now });
+    const playwright = await loadPlaywright(deps, home);
     const url = buildConnectUrl({ api, name: sessionId, context, idleMs: IDLE_MS, labels: { agent_session: sessionId, agent: agentId } });
     let browser;
     try {
         browser = await playwright.chromium.connectOverCDP(url, { headers: { Authorization: `Bearer ${token}` }, timeout: 60_000 });
     }
     catch (cause) {
-        throw unavailable(`Connecting to the cloud browser failed: ${cause.message.split('\n')[0]}`);
+        // A refusal that named itself travels as itself; anything else — a network error, a timeout — is the outage it looks like.
+        throw refusedConnect(cause) ?? unavailable(`Connecting to the cloud browser failed: ${cause.message.split('\n')[0]}`);
     }
     const fs = node(deps, 'node:fs');
-    const now = deps.now ?? Date.now;
     const pages = () => browser.contexts().flatMap((c) => c.pages());
     const ids = new WeakMap();
+    /** One browser-level CDP session for the connection: `Target.getTargets` answers for every tab in one round trip. */
+    let cdp;
+    const browserSession = async () => {
+        if (!browser.newBrowserCDPSession)
+            return undefined; // older playwright-core: every page keeps the per-page lookup
+        if (!cdp) {
+            try {
+                cdp = await browser.newBrowserCDPSession();
+            }
+            catch {
+                return undefined;
+            } // a browser that refuses the session lists tabs the old way, it does not fail
+        }
+        return cdp;
+    };
+    /** CDP's page targets, or nothing when the browser session is unavailable — never a thrown listing. */
+    const pageTargets = async () => {
+        const session = await browserSession();
+        if (!session)
+            return undefined;
+        try {
+            return ((await session.send('Target.getTargets'))?.targetInfos ?? []);
+        }
+        catch {
+            return undefined;
+        }
+    };
     const idOf = async (page) => {
         const known = ids.get(page);
         if (known)
@@ -100,6 +304,25 @@ export async function connectBrowser(deps, options = {}) {
             await session.detach().catch(() => { });
         }
     };
+    /**
+     * Every page with its target id: the one `Target.getTargets` covers the pages it names unambiguously, and only
+     * the rest (another tab on the same url, a page it does not name) pay for their own `Target.getTargetInfo`.
+     * Matching itself makes no request, so `get` reads the map for free and only a miss asks the page again.
+     */
+    const observed = async () => {
+        const all = pages();
+        const urls = all.map(page => page.url());
+        const targets = await pageTargets();
+        const { matched } = matchTargetsToPages(targets ?? [], urls);
+        return all.map((page, index) => {
+            const target = matched.get(index);
+            if (target)
+                ids.set(page, target.targetId);
+            return { page, id: target?.targetId, url: target?.url ?? urls[index] ?? '', title: target?.title };
+        });
+    };
+    /** A page's target id, from the map when it named it or from its own CDP session otherwise. */
+    const idOfObserved = async (tab) => tab.id ?? await bounded(idOf(tab.page), 2000).catch(() => '');
     const wrap = async (page) => {
         const id = await idOf(page);
         return {
@@ -112,6 +335,12 @@ export async function connectBrowser(deps, options = {}) {
             url: async () => page.url(),
             title: async () => page.title(),
             snapshot: async () => page.ariaSnapshot({ mode: 'ai' }),
+            // `aria-ref=` is Playwright's own spelling of a snapshot ref, so the two drivers act on the same handle.
+            click: async (ref) => { await page.locator(`aria-ref=${ref}`).click(); },
+            fill: async (ref, text) => { await page.locator(`aria-ref=${ref}`).fill(text); },
+            press: async (key) => { await page.keyboard.press(key); },
+            scroll: async (direction, pixels) => { await page.mouse.wheel(0, direction === 'down' ? pixels ?? SCROLL_PIXELS_DEFAULT : -(pixels ?? SCROLL_PIXELS_DEFAULT)); },
+            evaluate: async (expression) => await page.evaluate(expression),
             screenshot: async (shot) => {
                 const dir = `${home}/.praxis/screenshots`;
                 fs.mkdirSync(dir, { recursive: true });
@@ -121,17 +350,20 @@ export async function connectBrowser(deps, options = {}) {
             },
         };
     };
-    const list = async () => Promise.all(pages().map(async (page) => ({
-        id: await idOf(page), url: page.url(),
-        title: await bounded(page.title(), 2000).catch(() => ''),
-        active: await bounded(page.evaluate(() => document.visibilityState === 'visible'), 2000).catch(() => false),
+    const list = async () => Promise.all((await observed()).map(async (tab) => ({
+        id: await idOfObserved(tab), url: tab.url,
+        // A matched target already carries the title; an unmapped page keeps asking its own page, as before.
+        title: tab.title ?? await bounded(tab.page.title(), 2000).catch(() => ''),
+        active: await bounded(tab.page.evaluate(() => document.visibilityState === 'visible'), 2000).catch(() => false),
     })));
     const get = async (id) => {
-        for (const page of pages())
-            if (await idOf(page) === id) {
-                await page.bringToFront().catch(() => { });
-                return wrap(page);
+        for (const tab of await observed()) {
+            const known = await idOfObserved(tab);
+            if (known === id && known) {
+                await tab.page.bringToFront().catch(() => { });
+                return wrap(tab.page);
             }
+        }
         throw new PraxisError({ status: 404, code: 'TAB_NOT_FOUND', message: `No tab with id ${id}; call browser.tabs.list() for the current tabs.` });
     };
     const create = async () => {
@@ -156,6 +388,12 @@ export async function connectBrowser(deps, options = {}) {
             return tab;
         },
         documentation: () => BROWSER_DOCUMENTATION,
-        disconnect: async () => { await browser.close(); },
+        /** Drops this connection only; the cloud session and its tabs stay until it idles out. */
+        disconnect: async () => {
+            // browser.close() drops the whole CDP connection, the browser-level session with it; detaching
+            // it first only added one more cross-region round trip (+0.6–0.8 s on the #829 LAB).
+            cdp = undefined;
+            await browser.close();
+        },
     };
 }