@deepraxis/sdk 0.1.1-dev.d25d171 → 0.1.1-dev.d3030b1

package/dist/helpers/application-build.d.ts

@@ -0,0 +1,10 @@
+import type { PublishInput } from './application-publish.js';
+/** A vite/vinext build read into memory: paths are relative to dist/server and dist/client. */
+export interface BuildOutput {
+    serverFiles: Record<string, Uint8Array>;
+    clientFiles: Record<string, Uint8Array>;
+    /** Parsed dist/server/wrangler.json. */
+    wranglerJson: unknown;
+}
+/** Pure mapping from a vite/vinext build (dist/server + dist/client + wrangler.json) to `praxis.application.publish` input. No fs, no network. */
+export declare function publishInputFromBuild(build: BuildOutput, name: string): PublishInput;

package/dist/helpers/application-build.js

@@ -0,0 +1,98 @@
+import { PraxisError } from "../core/errors.js";
+// wrangler.json keys that declare a binding the platform does not accept (it answers UNSUPPORTED).
+const UNSUPPORTED_BINDING_KEYS = ['services', 'queues', 'durable_objects', 'ai', 'analytics_engine_datasets', 'vectorize', 'hyperdrive',
+    'browser', 'send_email', 'mtls_certificates', 'dispatch_namespaces', 'unsafe', 'version_metadata', 'images', 'workflows', 'pipelines',
+    'secrets_store_secrets', 'ratelimits', 'vpc_services', 'media', 'tail_consumers', 'worker_loaders'];
+// A key declares something only if it holds a value somewhere inside: vite's generated wrangler.json writes
+// empty containers such as `queues: { producers: [], consumers: [] }` and `durable_objects: { bindings: [] }`.
+const isPresent = (value) => {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.some(isPresent);
+    if (typeof value === 'object')
+        return Object.values(value).some(isPresent);
+    return true;
+};
+/** Compile one .assetsignore line (gitignore subset: names, `*`, `**`, leading /, trailing /) to a matcher over a relative path. */
+function ignoreMatcher(line) {
+    let pattern = line.trim();
+    if (!pattern || pattern.startsWith('#') || pattern.startsWith('!'))
+        return null;
+    const anchored = pattern.startsWith('/') || pattern.slice(0, -1).includes('/');
+    pattern = pattern.replace(/^\//, '').replace(/\/$/, '');
+    const source = pattern.split('**').map(part => part.split('*').map(piece => piece.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*');
+    const regex = new RegExp(`^${source}$`);
+    return path => {
+        const segments = path.split('/');
+        // The path or any of its parent directories matches, as in gitignore.
+        for (let end = 1; end <= segments.length; end++) {
+            if (anchored ? regex.test(segments.slice(0, end).join('/')) : regex.test(segments[end - 1]))
+                return true;
+        }
+        return false;
+    };
+}
+function bindingsFrom(wrangler) {
+    const bindings = [];
+    const fromList = (key, type) => {
+        const list = wrangler[key];
+        if (!isPresent(list))
+            return;
+        if (!Array.isArray(list))
+            throw new PraxisError({ code: 'INVALID_PARAMS', message: `wrangler.json ${key} must be an array` });
+        for (const entry of list) {
+            if (typeof entry?.binding !== 'string')
+                throw new PraxisError({ code: 'INVALID_PARAMS', message: `wrangler.json ${key} entry has no binding name` });
+            bindings.push({ type, name: entry.binding });
+        }
+    };
+    fromList('d1_databases', 'd1');
+    fromList('kv_namespaces', 'kv_namespace');
+    fromList('r2_buckets', 'r2_bucket');
+    for (const [name, value] of Object.entries((wrangler.vars ?? {}))) {
+        bindings.push((typeof value === 'string' ? { type: 'plain_text', name, text: value } : { type: 'json', name, json: value }));
+    }
+    if (typeof wrangler.assets?.binding === 'string')
+        bindings.push({ type: 'assets', name: wrangler.assets.binding });
+    return bindings;
+}
+/** Pure mapping from a vite/vinext build (dist/server + dist/client + wrangler.json) to `praxis.application.publish` input. No fs, no network. */
+export function publishInputFromBuild(build, name) {
+    const wrangler = build.wranglerJson;
+    if (!wrangler || typeof wrangler !== 'object' || Array.isArray(wrangler)) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'wranglerJson must be the parsed dist/server/wrangler.json object' });
+    }
+    const offending = UNSUPPORTED_BINDING_KEYS.filter(key => isPresent(wrangler[key]));
+    if (offending.length) {
+        throw new PraxisError({ code: 'UNSUPPORTED', message: `wrangler.json declares bindings the platform does not support: ${offending.join(', ')}` });
+    }
+    const modules = Object.entries(build.serverFiles)
+        .filter(([path]) => path.endsWith('.js'))
+        .map(([path, content]) => ({ name: path, content, content_type: 'application/javascript+module' }));
+    if (typeof wrangler.main !== 'string')
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'wrangler.json has no main entry' });
+    if (!modules.some(module => module.name === wrangler.main)) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: `wrangler.json main ${wrangler.main} is not a .js file under dist/server` });
+    }
+    const ignored = new TextDecoder().decode(build.clientFiles['.assetsignore'] ?? new Uint8Array()).split(/\r?\n/)
+        .map(ignoreMatcher).filter((matcher) => matcher !== null);
+    const files = {};
+    for (const [path, content] of Object.entries(build.clientFiles)) {
+        if (path === '.assetsignore' || ignored.some(matches => matches(path)))
+            continue;
+        files[`/${path}`] = content;
+    }
+    const { binding: _binding, directory: _directory, ...assetsConfig } = (wrangler.assets ?? {});
+    const bindings = bindingsFrom(wrangler);
+    return {
+        name,
+        files,
+        modules,
+        main_module: wrangler.main,
+        ...(typeof wrangler.compatibility_date === 'string' ? { compatibility_date: wrangler.compatibility_date } : {}),
+        ...(Array.isArray(wrangler.compatibility_flags) ? { compatibility_flags: wrangler.compatibility_flags } : {}),
+        ...(bindings.length ? { bindings } : {}),
+        ...(Object.keys(assetsConfig).length ? { assets_config: assetsConfig } : {}),
+    };
+}

package/dist/helpers/application-publish.d.ts

@@ -12,6 +12,14 @@ export interface PublishInput {
         content: string;
         content_type?: string;
     };
+    /** Multi-module Worker (e.g. a vite/vinext build). Names pass through unchanged; relative paths with / are legal. Mutually exclusive with main. */
+    modules?: {
+        name: string;
+        content: string | Uint8Array;
+        content_type?: string;
+    }[];
+    /** Entry module name; defaults to the first module and must name one of modules. */
+    main_module?: string;
     /** 运行时兼容日期，默认当天 UTC（YYYY-MM-DD）。 */
     compatibility_date?: string;
     /** 运行时兼容标志，原样传递；平台固定附加 global_fetch_strictly_public。 */

package/dist/helpers/application-publish.js

@@ -21,11 +21,30 @@ export async function publish(client, input) {
     const timeout = input.timeout_ms ?? 120_000;
     if (!Number.isFinite(timeout) || timeout < 0)
         throw new RangeError('timeout_ms must be non-negative and finite');
-    const contentType = ['application/javascript+module', 'text/javascript', 'application/javascript', 'application/json',
-        'text/plain', 'application/wasm', 'application/octet-stream', 'application/x-python']
-        .find(type => type === (input.main?.content_type ?? 'application/javascript+module'));
-    if (!contentType)
-        throw new PraxisError({ code: 'INVALID_PARAMS', message: `Unsupported module content_type: ${input.main?.content_type}` });
+    const moduleTypes = ['application/javascript+module', 'text/javascript', 'application/javascript', 'application/json',
+        'text/plain', 'application/wasm', 'application/octet-stream', 'application/x-python'];
+    const moduleType = (type) => {
+        const found = moduleTypes.find(candidate => candidate === (type ?? 'application/javascript+module'));
+        if (!found)
+            throw new PraxisError({ code: 'INVALID_PARAMS', message: `Unsupported module content_type: ${type}` });
+        return found;
+    };
+    if (input.main && input.modules)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'Pass either main or modules, not both' });
+    if (input.main_module !== undefined && !input.modules)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'main_module requires modules; with main the entry is main.name' });
+    if (input.modules && input.modules.length === 0)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'modules must not be empty' });
+    const entryModules = input.main
+        ? [{ name: input.main.name, content_type: moduleType(input.main.content_type), content_base64: base64(new TextEncoder().encode(input.main.content)) }]
+        : input.modules?.map(module => ({ name: module.name, content_type: moduleType(module.content_type),
+            content_base64: base64(typeof module.content === 'string' ? new TextEncoder().encode(module.content) : module.content) }));
+    if (new Set(entryModules?.map(module => module.name)).size !== (entryModules?.length ?? 0))
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'Duplicate module name' });
+    const mainModule = input.main ? input.main.name : input.modules ? (input.main_module ?? input.modules[0].name) : undefined;
+    if (input.modules && !input.modules.some(module => module.name === mainModule)) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: `main_module ${mainModule} is not among modules` });
+    }
     const files = Object.entries(input.files);
     if (files.length > 100_000)
         throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
@@ -80,7 +99,7 @@ export async function publish(client, input) {
     const removed = Object.keys(previous).filter(key => !Object.hasOwn(manifest, key));
     const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(manifest))));
     const manifestHash = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
-    const staticOnly = !['main', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
+    const staticOnly = !['main', 'modules', 'main_module', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
     const unchanged = staticOnly && !!currentVersion && manifestHash === currentVersion.praxis.assets_manifest?.manifest_hash;
     const hashes = new Set(Object.values(manifest).map(entry => entry.hash));
     const currentResult = { url: worker.subdomain.url, worker_id: worker.id, version_id: currentVersion?.id ?? null,
@@ -127,9 +146,7 @@ export async function publish(client, input) {
             assets: versionAssets,
             ...(input.compatibility_flags ? { compatibility_flags: input.compatibility_flags } : {}),
             ...(input.bindings ? { bindings: input.bindings } : {}),
-            ...(input.main ? { main_module: input.main.name, modules: [{ name: input.main.name,
-                        content_type: contentType,
-                        content_base64: base64(new TextEncoder().encode(input.main.content)) }] } : {}),
+            ...(entryModules ? { main_module: mainModule, modules: entryModules } : {}),
         } });
     let deployment = result.deployment;
     if (!deployment)

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

@@ -0,0 +1,84 @@
+/**
+ * ticket-944 — the `actions` driver: the cloud browser 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/cloud-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 cloud browser 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/cloud-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

@@ -0,0 +1,102 @@
+import { PraxisError } from '../core/errors.js';
+import { type BrowserTabInfo, type ContextLike } from './browser-decisions.js';
+/** Version of the Playwright client library: preinstalled in the base image, installed on demand elsewhere. */
+export declare const PLAYWRIGHT_CORE_VERSION = "1.63.0";
+/** Playwright's Page, kept structural: the SDK does not depend on playwright-core. */
+export type PlaywrightPage = any;
+export interface BrowserTab {
+    readonly id: string;
+    /** 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>;
+    forward(): Promise<void>;
+    reload(): Promise<void>;
+    close(): Promise<void>;
+    url(): Promise<string>;
+    title(): Promise<string>;
+    /** 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;
+    }): Promise<{
+        path: string;
+        hint: string;
+    }>;
+}
+export interface PraxisBrowser {
+    readonly tabs: {
+        list(): Promise<BrowserTabInfo[]>;
+        get(id: string): Promise<BrowserTab>;
+        'new'(): Promise<BrowserTab>;
+    };
+    open(url: string, options?: {
+        reuseTab?: boolean;
+    }): Promise<BrowserTab>;
+    documentation(): string;
+    /** Drops this connection only; the cloud session and its tabs stay until it idles out. */
+    disconnect(): Promise<void>;
+}
+export interface BrowserConnectOptions {
+    /** false skips the agent's saved sign-in context. */
+    context?: false;
+}
+interface ContextsApi {
+    list(args?: {
+        query?: {
+            limit?: number;
+            cursor?: string;
+            name?: string;
+        };
+    }): Promise<{
+        data: (ContextLike & {
+            name?: unknown;
+        })[];
+        nextCursor: string | null;
+    }>;
+    create(args: {
+        body: {
+            name: string;
+            labels: Record<string, string>;
+        };
+    }): 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;
+    env: Readonly<Record<string, string | undefined>>;
+    /** 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. */
+export declare const needsFullMachine: () => Error & {
+    code: string;
+};
+export declare function connectBrowser(deps: BrowserConnectDeps, options?: BrowserConnectOptions): Promise<PraxisBrowser>;
+export {};