@mercuryo-ai/agentbrowse 0.2.50

package/dist/assistive-stagehand.js

@@ -0,0 +1,10 @@
+import { connectConfiguredAssistiveStagehand } from './assistive-runtime.js';
+/**
+ * Connect Stagehand with the currently configured assistive runtime.
+ *
+ * This stays separate from the generic Stagehand connector so the browser-core
+ * layer does not own orchestration/backend setup directly.
+ */
+export async function connectAssistiveStagehand(cdpUrl, options = {}) {
+    return connectConfiguredAssistiveStagehand(cdpUrl, options);
+}

package/dist/browser-session-state.d.ts

@@ -0,0 +1,95 @@
+import type { BrowseRuntimeState } from "./runtime-state.js";
+import type { ProxyConfig } from "./solver/types.js";
+/** Browser capabilities discovered or provisioned for the session. */
+export interface BrowserSessionCapabilities {
+    captchaSolve?: boolean;
+}
+/** Persisted browser session state shared across AgentBrowse commands. */
+export interface BrowserSessionState {
+    cdpUrl: string;
+    pid?: number;
+    launchedAt: string;
+    port?: number;
+    profile?: string;
+    identity?: BrowseSessionIdentity;
+    transport?: BrowseSessionTransport;
+    capabilities?: BrowserSessionCapabilities;
+    runtime?: BrowseRuntimeState;
+}
+/** Browser session state plus transient run-scoped metadata. */
+export interface BrowserCommandSession extends BrowserSessionState {
+    activeRunId?: string;
+}
+/** Stable identity metadata for an attached or owned browser session. */
+export interface BrowseSessionIdentity {
+    browserInstanceRef: string;
+    endpoint: string;
+    pid?: number;
+    profile?: string;
+    provider?: string;
+    launchedAt: string;
+    ownership: "agentbrowse" | "external";
+}
+/** Transport metadata for the attached browser connection. */
+export interface BrowseSessionTransport {
+    proxyMode: "direct" | "proxy";
+    proxy?: ProxyConfig;
+}
+/** Filesystem-backed session store used by the CLI and local wrappers. */
+export interface BrowserSessionStore {
+    readonly rootDir: string;
+    readonly sessionPath: string;
+    serialize(session: BrowserSessionState): string;
+    save(session: BrowserSessionState): void;
+    load(): BrowserSessionState | null;
+    delete(): void;
+}
+type ManagedBrowserSessionInput = Omit<BrowserSessionState, "port" | "identity" | "pid" | "capabilities"> & {
+    pid: number;
+    capabilities?: BrowserSessionCapabilities;
+};
+type AttachedBrowserSessionInput = Omit<BrowserSessionState, "port" | "identity" | "pid" | "profile" | "capabilities"> & {
+    capabilities?: BrowserSessionCapabilities;
+    browserInstanceRef?: string;
+    provider?: string;
+};
+export declare function parseSessionPort(cdpUrl: string): number | undefined;
+/** Converts a CDP websocket or HTTP endpoint into the matching DevTools HTTP endpoint. */
+export declare function buildCdpHttpEndpointUrl(cdpUrl: string, resourcePath?: "/json/version" | "/json/list"): string | null;
+/** Extracts a stable browser instance reference from a CDP endpoint. */
+export declare function parseBrowserInstanceRef(cdpUrl: string): string;
+/** Serializes a browser session while omitting protected value payloads. */
+export declare function serializeBrowserSession(session: BrowserSessionState): string;
+/** Creates the default filesystem-backed session store used by AgentBrowse. */
+export declare function createBrowserSessionStore(options?: {
+    rootDir?: string;
+    sessionFileName?: string;
+}): BrowserSessionStore;
+/** Saves the current browser session to the default local session store. */
+export declare function saveBrowserSession(session: BrowserSessionState): void;
+/** Loads the current browser session from the default local session store. */
+export declare function loadBrowserSession(): BrowserSessionState | null;
+/** Deletes the current browser session from the default local session store. */
+export declare function deleteBrowserSession(): void;
+/** Resolves a stable browser identifier for logs, tracing, and local state. */
+export declare function resolveBrowserSessionId(session: Pick<BrowserSessionState, "cdpUrl" | "identity" | "pid">): string;
+/** Builds a managed AgentBrowse-owned browser session snapshot. */
+export declare function buildOwnedSession(session: ManagedBrowserSessionInput): BrowserSessionState;
+/** Builds an attached external browser session snapshot. */
+export declare function buildAttachedSession(session: AttachedBrowserSessionInput): BrowserSessionState;
+/** Returns the most likely DevTools port for the current session. */
+export declare function getSessionPort(session: BrowserSessionState | null): number;
+/** Returns `true` when the session advertises captcha-solving capability. */
+export declare function supportsCaptchaSolve(session: BrowserSessionState | null): boolean;
+/** Returns `true` when the session belongs to an AgentBrowse-managed browser. */
+export declare function isOwnedSession(session: BrowserSessionState | null | undefined): session is BrowserSessionState & {
+    identity: BrowseSessionIdentity;
+};
+/** Returns `true` when the session refers to an externally managed browser. */
+export declare function isAttachedSession(session: BrowserSessionState | null | undefined): session is BrowserSessionState & {
+    identity: BrowseSessionIdentity;
+};
+/** Checks whether the persisted browser session still points to a live browser instance. */
+export declare function isSessionAlive(session: BrowserSessionState): Promise<boolean>;
+export {};
+//# sourceMappingURL=browser-session-state.d.ts.map

package/dist/browser-session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session-state.d.ts","sourceRoot":"","sources":["../src/browser-session-state.ts"],"names":[],"mappings":"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"}

package/dist/browser-session-state.js

@@ -0,0 +1,279 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { scrubProtectedExactValues } from "./secrets/protected-exact-value-redaction.js";
+const BLOCKED_SESSION_KEYS = new Set([
+    "rawValue",
+    "rawValues",
+    "secretValue",
+    "secretValues",
+    "resolvedValues",
+    "protectedValues",
+]);
+function getDefaultAgentbrowseStateDir() {
+    return join(homedir(), ".agentbrowse");
+}
+function getBrowserSessionPath(stateDir, sessionFileName) {
+    return join(stateDir, sessionFileName);
+}
+function ensureStateDir(stateDir) {
+    if (!existsSync(stateDir)) {
+        mkdirSync(stateDir, { recursive: true });
+    }
+}
+function atomicWriteJson(path, contents) {
+    const tempPath = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tempPath, contents);
+        renameSync(tempPath, path);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+export function parseSessionPort(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        if (!url.port) {
+            return undefined;
+        }
+        const port = Number(url.port);
+        return Number.isFinite(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Converts a CDP websocket or HTTP endpoint into the matching DevTools HTTP endpoint. */
+export function buildCdpHttpEndpointUrl(cdpUrl, resourcePath = "/json/version") {
+    try {
+        const url = new URL(cdpUrl);
+        if (url.protocol === "ws:") {
+            url.protocol = "http:";
+        }
+        else if (url.protocol === "wss:") {
+            url.protocol = "https:";
+        }
+        else if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return null;
+        }
+        url.pathname = resourcePath;
+        url.search = "";
+        url.hash = "";
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/** Extracts a stable browser instance reference from a CDP endpoint. */
+export function parseBrowserInstanceRef(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        const pathSegments = url.pathname.split("/").filter(Boolean);
+        return pathSegments.at(-1) ?? cdpUrl;
+    }
+    catch {
+        const pathSegments = cdpUrl.split("/").filter(Boolean);
+        return pathSegments.at(-1) ?? cdpUrl;
+    }
+}
+async function probeSessionEndpoint(session) {
+    const endpoint = session.identity?.endpoint ?? session.cdpUrl;
+    const versionUrl = buildCdpHttpEndpointUrl(endpoint, "/json/version");
+    if (!versionUrl) {
+        return "unreachable";
+    }
+    try {
+        const response = await fetch(versionUrl);
+        if (!response.ok) {
+            return "unreachable";
+        }
+        const payload = (await response.json());
+        const liveEndpoint = payload.webSocketDebuggerUrl?.trim();
+        if (!liveEndpoint) {
+            return "unreachable";
+        }
+        const expectedEndpoint = session.identity?.endpoint ?? session.cdpUrl;
+        if (liveEndpoint === expectedEndpoint) {
+            return "match";
+        }
+        const expectedBrowserInstanceRef = session.identity?.browserInstanceRef ??
+            parseBrowserInstanceRef(expectedEndpoint);
+        return parseBrowserInstanceRef(liveEndpoint) === expectedBrowserInstanceRef
+            ? "match"
+            : "mismatch";
+    }
+    catch {
+        return "unreachable";
+    }
+}
+/** Serializes a browser session while omitting protected value payloads. */
+export function serializeBrowserSession(session) {
+    const scrubbedSession = scrubProtectedExactValues(session, session);
+    return JSON.stringify(scrubbedSession, (key, value) => {
+        if (BLOCKED_SESSION_KEYS.has(key)) {
+            return undefined;
+        }
+        return value;
+    }, 2);
+}
+/** Creates the default filesystem-backed session store used by AgentBrowse. */
+export function createBrowserSessionStore(options = {}) {
+    const rootDir = options.rootDir ?? getDefaultAgentbrowseStateDir();
+    const sessionPath = getBrowserSessionPath(rootDir, options.sessionFileName?.trim() || "browse-session.json");
+    return {
+        rootDir,
+        sessionPath,
+        serialize: serializeBrowserSession,
+        save(session) {
+            ensureStateDir(rootDir);
+            atomicWriteJson(sessionPath, serializeBrowserSession(session));
+        },
+        load() {
+            if (!existsSync(sessionPath)) {
+                return null;
+            }
+            try {
+                const raw = JSON.parse(readFileSync(sessionPath, "utf-8"));
+                if (!raw.cdpUrl) {
+                    return null;
+                }
+                return raw;
+            }
+            catch {
+                return null;
+            }
+        },
+        delete() {
+            if (existsSync(sessionPath)) {
+                unlinkSync(sessionPath);
+            }
+        },
+    };
+}
+/** Saves the current browser session to the default local session store. */
+export function saveBrowserSession(session) {
+    createBrowserSessionStore().save(session);
+}
+/** Loads the current browser session from the default local session store. */
+export function loadBrowserSession() {
+    return createBrowserSessionStore().load();
+}
+/** Deletes the current browser session from the default local session store. */
+export function deleteBrowserSession() {
+    createBrowserSessionStore().delete();
+}
+/** Resolves a stable browser identifier for logs, tracing, and local state. */
+export function resolveBrowserSessionId(session) {
+    if (session.identity?.browserInstanceRef) {
+        return session.identity.browserInstanceRef;
+    }
+    if (typeof session.pid === "number" &&
+        Number.isFinite(session.pid) &&
+        session.pid > 0) {
+        return `pid-${session.pid}`;
+    }
+    return `cdp-${parseBrowserInstanceRef(session.cdpUrl)}`;
+}
+function buildManagedSessionIdentity(session) {
+    return {
+        browserInstanceRef: parseBrowserInstanceRef(session.cdpUrl),
+        endpoint: session.cdpUrl,
+        pid: session.pid,
+        profile: session.profile,
+        launchedAt: session.launchedAt,
+        ownership: "agentbrowse",
+    };
+}
+function buildAttachedSessionIdentity(session) {
+    return {
+        browserInstanceRef: session.browserInstanceRef ?? parseBrowserInstanceRef(session.cdpUrl),
+        endpoint: session.cdpUrl,
+        ...(session.provider ? { provider: session.provider } : {}),
+        launchedAt: session.launchedAt,
+        ownership: "external",
+    };
+}
+/** Builds a managed AgentBrowse-owned browser session snapshot. */
+export function buildOwnedSession(session) {
+    return {
+        ...session,
+        port: parseSessionPort(session.cdpUrl),
+        identity: buildManagedSessionIdentity(session),
+    };
+}
+/** Builds an attached external browser session snapshot. */
+export function buildAttachedSession(session) {
+    return {
+        ...session,
+        port: parseSessionPort(session.cdpUrl),
+        identity: buildAttachedSessionIdentity(session),
+    };
+}
+/** Returns the most likely DevTools port for the current session. */
+export function getSessionPort(session) {
+    if (session?.port)
+        return session.port;
+    if (session?.cdpUrl) {
+        const parsedPort = parseSessionPort(session.cdpUrl);
+        if (parsedPort) {
+            return parsedPort;
+        }
+    }
+    return 9222;
+}
+/** Returns `true` when the session advertises captcha-solving capability. */
+export function supportsCaptchaSolve(session) {
+    return session?.capabilities?.captchaSolve === true;
+}
+/** Returns `true` when the session belongs to an AgentBrowse-managed browser. */
+export function isOwnedSession(session) {
+    if (!session?.identity) {
+        return false;
+    }
+    if (session.identity.ownership !== "agentbrowse") {
+        return false;
+    }
+    return (typeof session.pid === "number" &&
+        Number.isFinite(session.pid) &&
+        session.identity.endpoint === session.cdpUrl &&
+        session.identity.pid === session.pid &&
+        session.identity.launchedAt === session.launchedAt &&
+        session.identity.browserInstanceRef.length > 0 &&
+        session.identity.profile === session.profile);
+}
+/** Returns `true` when the session refers to an externally managed browser. */
+export function isAttachedSession(session) {
+    if (!session?.identity) {
+        return false;
+    }
+    return (session.identity.ownership === "external" &&
+        session.identity.endpoint === session.cdpUrl &&
+        session.identity.launchedAt === session.launchedAt &&
+        session.identity.browserInstanceRef.length > 0);
+}
+/** Checks whether the persisted browser session still points to a live browser instance. */
+export async function isSessionAlive(session) {
+    const endpointProbe = await probeSessionEndpoint(session);
+    if (endpointProbe === "match") {
+        return true;
+    }
+    if (endpointProbe === "mismatch" ||
+        session.identity?.ownership === "agentbrowse") {
+        return false;
+    }
+    if (typeof session.pid !== "number" ||
+        !Number.isFinite(session.pid) ||
+        session.pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(session.pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/client-bindings.d.ts

@@ -0,0 +1,10 @@
+import type { BrowserSessionState } from './browser-session-state.js';
+import type { AgentbrowseAssistiveRuntime } from './assistive-runtime.js';
+import type { AgentbrowseDiagnosticsHooks } from './diagnostics.js';
+export interface AgentbrowseSessionBindings {
+    assistiveRuntime?: AgentbrowseAssistiveRuntime | null;
+    diagnostics?: AgentbrowseDiagnosticsHooks | null;
+}
+export declare function bindAgentbrowseSession(session: BrowserSessionState, bindings: AgentbrowseSessionBindings): BrowserSessionState;
+export declare function getAgentbrowseSessionBindings(session: BrowserSessionState | null | undefined): AgentbrowseSessionBindings | null;
+//# sourceMappingURL=client-bindings.d.ts.map

package/dist/client-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-bindings.d.ts","sourceRoot":"","sources":["../src/client-bindings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IACtD,WAAW,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAClD;AAID,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,0BAA0B,GACnC,mBAAmB,CAWrB;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAC9C,0BAA0B,GAAG,IAAI,CAMnC"}

package/dist/client-bindings.js

@@ -0,0 +1,18 @@
+const bindingsBySession = new WeakMap();
+export function bindAgentbrowseSession(session, bindings) {
+    if (!bindings.assistiveRuntime && !bindings.diagnostics) {
+        bindingsBySession.delete(session);
+        return session;
+    }
+    bindingsBySession.set(session, {
+        ...(bindings.assistiveRuntime ? { assistiveRuntime: bindings.assistiveRuntime } : {}),
+        ...(bindings.diagnostics ? { diagnostics: bindings.diagnostics } : {}),
+    });
+    return session;
+}
+export function getAgentbrowseSessionBindings(session) {
+    if (!session) {
+        return null;
+    }
+    return bindingsBySession.get(session) ?? null;
+}

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import type { BrowserCommandSession, BrowserSessionState } from './browser-session-state.js';
+import type { AgentbrowseAssistiveRuntime } from './assistive-runtime.js';
+import type { AgentbrowseDiagnosticsHooks } from './diagnostics.js';
+import { type ActResult, type BrowseAction } from './commands/act.js';
+import { type AttachOptions, type AttachResult } from './commands/attach.js';
+import { type BrowserStatusResult } from './commands/browser-status.js';
+import { type CloseResult } from './commands/close.js';
+import { type ExtractResult, type ExtractSchemaInput } from './commands/extract.js';
+import { type LaunchOptions, type LaunchResult } from './commands/launch.js';
+import { type NavigateResult } from './commands/navigate.js';
+import { type ObserveResult } from './commands/observe.js';
+import { type ScreenshotResult } from './commands/screenshot.js';
+/** Client-scoped bindings for assistive runtime and diagnostics hooks. */
+export interface AgentbrowseClientOptions {
+    assistiveRuntime?: AgentbrowseAssistiveRuntime | null;
+    diagnostics?: AgentbrowseDiagnosticsHooks | null;
+}
+/**
+ * Embedded library surface with client-scoped configuration.
+ *
+ * Use this when your application wants to keep assistive runtime and diagnostics
+ * local to one tenant, workflow, or test process instead of relying on
+ * process-global helpers.
+ */
+export interface AgentbrowseClient {
+    /** Binds assistive runtime and diagnostics hooks to a session object in-place. */
+    bindSession<TSession extends BrowserSessionState>(session: TSession): TSession;
+    /** Attaches to an existing browser via a websocket or HTTP CDP endpoint. */
+    attach(cdpUrl: string, options?: AttachOptions): Promise<AttachResult>;
+    /** Launches a managed browser session. */
+    launch(url?: string, options?: LaunchOptions): Promise<LaunchResult>;
+    /** Reads the current browser and page status. */
+    status(session: BrowserCommandSession): Promise<BrowserStatusResult>;
+    /** Navigates the current page to a new URL. */
+    navigate(session: BrowserCommandSession, nextUrl: string): Promise<NavigateResult>;
+    /** Observes the current page and returns action targets and scopes. */
+    observe(session: BrowserCommandSession, instruction?: string): Promise<ObserveResult>;
+    /** Runs a deterministic action against a stored observed target. */
+    act(session: BrowserCommandSession, targetRef: string, action: BrowseAction, value?: string): Promise<ActResult>;
+    /** Extracts structured data using a plain schema object or Zod schema. */
+    extract(session: BrowserCommandSession, schema: ExtractSchemaInput, scopeRef?: string): Promise<ExtractResult>;
+    /** Captures a screenshot of the current page. */
+    screenshot(session: BrowserCommandSession, outputPath?: string): Promise<ScreenshotResult>;
+    /** Closes the current browser session when AgentBrowse owns it. */
+    close(session: BrowserCommandSession): Promise<CloseResult>;
+}
+/** Creates an AgentBrowse client with client-scoped assistive runtime and diagnostics hooks. */
+export declare function createAgentbrowseClient(options?: AgentbrowseClientOptions): AgentbrowseClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EAAc,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,EAAU,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACvF,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAAU,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEpF,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB;IACvC,gBAAgB,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IACtD,WAAW,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,WAAW,CAAC,QAAQ,SAAS,mBAAmB,EAAE,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/E,4EAA4E;IAC5E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvE,0CAA0C;IAC1C,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACrE,iDAAiD;IACjD,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrE,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACnF,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,qBAAqB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACtF,oEAAoE;IACpE,GAAG,CACD,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACtB,0EAA0E;IAC1E,OAAO,CACL,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,iDAAiD;IACjD,UAAU,CAAC,OAAO,EAAE,qBAAqB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3F,mEAAmE;IACnE,KAAK,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC7D;AAED,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,iBAAiB,CAsDjG"}

package/dist/client.js

@@ -0,0 +1,63 @@
+import { bindAgentbrowseSession } from './client-bindings.js';
+import { actBrowser } from './commands/act.js';
+import { attach } from './commands/attach.js';
+import { browserStatus } from './commands/browser-status.js';
+import { close } from './commands/close.js';
+import { extractBrowser } from './commands/extract.js';
+import { launch } from './commands/launch.js';
+import { navigateBrowser } from './commands/navigate.js';
+import { observeBrowser } from './commands/observe.js';
+import { screenshotBrowser } from './commands/screenshot.js';
+/** Creates an AgentBrowse client with client-scoped assistive runtime and diagnostics hooks. */
+export function createAgentbrowseClient(options = {}) {
+    const bindings = {
+        ...(options.assistiveRuntime ? { assistiveRuntime: options.assistiveRuntime } : {}),
+        ...(options.diagnostics ? { diagnostics: options.diagnostics } : {}),
+    };
+    const bindSession = (session) => bindAgentbrowseSession(session, bindings);
+    return {
+        bindSession,
+        async attach(cdpUrl, attachOptions = {}) {
+            const result = await attach(cdpUrl, attachOptions);
+            if (result.success) {
+                bindSession(result.session);
+            }
+            return result;
+        },
+        async launch(url, launchOptions = {}) {
+            const result = await launch(url, launchOptions);
+            if (result.success) {
+                bindSession(result.session);
+            }
+            return result;
+        },
+        status(session) {
+            bindSession(session);
+            return browserStatus(session);
+        },
+        navigate(session, nextUrl) {
+            bindSession(session);
+            return navigateBrowser(session, nextUrl);
+        },
+        observe(session, instruction) {
+            bindSession(session);
+            return observeBrowser(session, instruction);
+        },
+        act(session, targetRef, action, value) {
+            bindSession(session);
+            return actBrowser(session, targetRef, action, value);
+        },
+        extract(session, schema, scopeRef) {
+            bindSession(session);
+            return extractBrowser(session, schema, scopeRef);
+        },
+        screenshot(session, outputPath) {
+            bindSession(session);
+            return screenshotBrowser(session, outputPath);
+        },
+        close(session) {
+            bindSession(session);
+            return close(session);
+        },
+    };
+}

package/dist/command-api-tracing.d.ts

@@ -0,0 +1,20 @@
+import { type DiagnosticCommand } from './diagnostics.js';
+type ApiTraceContext = {
+    runId?: string;
+    stepId?: string;
+    command: DiagnosticCommand;
+};
+type TracedFetchOptions = {
+    spanName: string;
+    attributes?: Record<string, unknown>;
+    fetchImpl?: typeof fetch;
+};
+type TracedStepOperationOptions = {
+    spanName: string;
+    attributes?: Record<string, unknown>;
+};
+export declare function withApiTraceContext<T>(context: ApiTraceContext, run: () => Promise<T>): Promise<T>;
+export declare function tracedStepOperation<T>(run: () => Promise<T> | T, options?: TracedStepOperationOptions): Promise<T>;
+export declare function tracedFetch(input: RequestInfo | URL, init?: RequestInit, options?: TracedFetchOptions): Promise<Response>;
+export {};
+//# sourceMappingURL=command-api-tracing.d.ts.map

package/dist/command-api-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-api-tracing.d.ts","sourceRoot":"","sources":["../src/command-api-tracing.ts"],"names":[],"mappings":"AACA,OAAO,EAAuC,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,KAAK,eAAe,GAAG;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,CAAC;AAEF,KAAK,0BAA0B,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAoEF,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACzB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,CAAC,CAAC,CA2CZ;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CA6CnB"}