@handstage/core 0.0.1

package/README.md

@@ -0,0 +1,2 @@
+# @handstage/core
+

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./v3/index";

package/dist/v3/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { maybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor";
+// currently the CLI is only used to spawn the shutdown supervisor
+// in the future, we may want to add more CLI commands here
+if (!maybeRunShutdownSupervisorFromArgv(process.argv.slice(2))) {
+    console.error("Unsupported stagehand CLI invocation. Expected --supervisor with valid args.");
+    process.exit(1);
+}

package/dist/v3/index.js

@@ -0,0 +1,13 @@
+import { maybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor";
+import * as PublicApi from "./types/public/index";
+import { V3 } from "./v3";
+export { maybeRunShutdownSupervisorFromArgv as __internalMaybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor";
+export * from "./types/public/index";
+export { V3, V3 as Stagehand } from "./v3";
+const StagehandDefault = {
+    ...PublicApi,
+    V3,
+    Stagehand: V3,
+    __internalMaybeRunShutdownSupervisorFromArgv: maybeRunShutdownSupervisorFromArgv,
+};
+export default StagehandDefault;

package/dist/v3/launch/local.js

@@ -0,0 +1,97 @@
+import { launch } from "chrome-launcher";
+import WebSocket from "ws";
+import { ConnectionTimeoutError } from "../types/public/sdkErrors";
+export async function launchLocalChrome(opts) {
+    const connectTimeoutMs = opts.connectTimeoutMs ?? 15_000;
+    const deadlineMs = Date.now() + connectTimeoutMs;
+    const connectionPollInterval = 250;
+    const maxConnectionRetries = Math.max(1, Math.ceil(connectTimeoutMs / connectionPollInterval));
+    const headless = opts.headless ?? false;
+    const chromeFlags = [
+        headless ? "--headless=new" : undefined,
+        "--remote-allow-origins=*",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-dev-shm-usage",
+        "--site-per-process",
+        ...(opts.chromeFlags ?? []),
+    ].filter((f) => typeof f === "string");
+    const chrome = await launch({
+        chromePath: opts.chromePath,
+        chromeFlags,
+        port: opts.port,
+        userDataDir: opts.userDataDir,
+        handleSIGINT: opts.handleSIGINT,
+        connectionPollInterval,
+        maxConnectionRetries,
+    });
+    const ws = await waitForWebSocketDebuggerUrl(chrome.port, deadlineMs);
+    await waitForWebSocketReady(ws, deadlineMs);
+    return { ws, chrome };
+}
+async function waitForWebSocketDebuggerUrl(port, deadlineMs) {
+    let lastErrMsg = "";
+    while (Date.now() < deadlineMs) {
+        try {
+            const resp = await fetch(`http://127.0.0.1:${port}/json/version`);
+            if (resp.ok) {
+                const json = (await resp.json());
+                const url = json
+                    .webSocketDebuggerUrl;
+                if (typeof url === "string")
+                    return url;
+            }
+            else {
+                lastErrMsg = `${resp.status} ${resp.statusText}`;
+            }
+        }
+        catch (err) {
+            lastErrMsg = err instanceof Error ? err.message : String(err);
+        }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new ConnectionTimeoutError(`Timed out waiting for /json/version on port ${port} ${lastErrMsg ? ` (last error: ${lastErrMsg})` : ""}`);
+}
+async function waitForWebSocketReady(wsUrl, deadlineMs) {
+    let lastErrMsg = "";
+    while (Date.now() < deadlineMs) {
+        const remainingMs = Math.max(200, deadlineMs - Date.now());
+        try {
+            await probeWebSocket(wsUrl, Math.min(2_000, remainingMs));
+            return;
+        }
+        catch (error) {
+            lastErrMsg = error instanceof Error ? error.message : String(error);
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    }
+    throw new ConnectionTimeoutError(`Timed out waiting for CDP websocket to accept connections at ${wsUrl}${lastErrMsg ? ` (last error: ${lastErrMsg})` : ""}`);
+}
+function probeWebSocket(wsUrl, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(wsUrl);
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                ws.terminate();
+            }
+            catch {
+                // best-effort cleanup
+            }
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            finish(new Error(`websocket probe timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+        ws.once("open", () => finish());
+        ws.once("error", (error) => finish(error));
+    });
+}

package/dist/v3/logger.js

@@ -0,0 +1,37 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createConsoleLogger } from "./types/public/consoleLogger";
+/**
+ * Stagehand V3 per-instance log routing (AsyncLocalStorage).
+ *
+ * - `bindInstanceLogger` / `unbindInstanceLogger`: register the effective logger for an instance id.
+ * - `withInstanceLogContext`: run a function with that instance id on the async context.
+ * - `v3Logger`: emit a line for the current instance, or fall back to `createConsoleLogger()` when no context.
+ */
+const logContext = new AsyncLocalStorage();
+const instanceLoggers = new Map();
+const fallbackLogger = createConsoleLogger();
+export function bindInstanceLogger(instanceId, logger) {
+    instanceLoggers.set(instanceId, logger);
+}
+export function unbindInstanceLogger(instanceId) {
+    instanceLoggers.delete(instanceId);
+}
+export function withInstanceLogContext(instanceId, fn) {
+    return logContext.run(instanceId, fn);
+}
+export function v3Logger(line) {
+    const id = logContext.getStore();
+    if (id) {
+        const fn = instanceLoggers.get(id);
+        if (fn) {
+            try {
+                fn(line);
+                return;
+            }
+            catch {
+                // fall through to fallback
+            }
+        }
+    }
+    fallbackLogger(line);
+}

package/dist/v3/runtimePaths.js

@@ -0,0 +1,106 @@
+/**
+ * Keep this file in sync with:
+ * - /packages/core/lib/v3/runtimePaths.ts
+ * - /packages/server-v3/scripts/runtimePaths.ts
+ * - /packages/server-v4/scripts/runtimePaths.ts
+ * - /packages/evals/runtimePaths.ts
+ * - /packages/docs/scripts/runtimePaths.js
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const PACKAGE_SEGMENT = "/packages/core/";
+const EVAL_FRAMES = new Set(["[eval]", "[eval]-wrapper"]);
+const INTERNAL_FRAME_NAMES = new Set([
+    "readCallsites",
+    "readCallsitePath",
+    "resolveCallerFilePath",
+    "getCurrentFilePath",
+    "getCurrentDirPath",
+    "getRepoRootDir",
+    "getPackageRootDir",
+    "createRequireFromCaller",
+    "isMainModule",
+]);
+const normalizePath = (value) => {
+    const input = value.startsWith("file://") ? fileURLToPath(value) : value;
+    return path.resolve(input).replaceAll("\\", "/");
+};
+const readCallsites = () => {
+    const previousPrepare = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_, stack) => stack;
+        return new Error().stack ?? [];
+    }
+    finally {
+        Error.prepareStackTrace = previousPrepare;
+    }
+};
+const readCallsitePath = (callsite) => {
+    const callsiteWithScript = callsite;
+    const rawPath = callsite.getFileName() ?? callsiteWithScript.getScriptNameOrSourceURL?.();
+    if (!rawPath)
+        return null;
+    if (rawPath.startsWith("node:"))
+        return null;
+    if (EVAL_FRAMES.has(rawPath))
+        return null;
+    return normalizePath(rawPath);
+};
+const isInternalCallsite = (callsite) => {
+    const functionName = callsite.getFunctionName();
+    if (functionName && INTERNAL_FRAME_NAMES.has(functionName))
+        return true;
+    const methodName = callsite.getMethodName();
+    if (methodName && INTERNAL_FRAME_NAMES.has(methodName))
+        return true;
+    const callsiteString = callsite.toString();
+    for (const frameName of INTERNAL_FRAME_NAMES) {
+        if (callsiteString.includes(`${frameName} (`))
+            return true;
+        if (callsiteString.includes(`.${frameName} (`))
+            return true;
+    }
+    return false;
+};
+const resolveCallerFilePath = () => {
+    const packageCandidates = [];
+    const fallbackCandidates = [];
+    for (const callsite of readCallsites()) {
+        const filePath = readCallsitePath(callsite);
+        if (!filePath)
+            continue;
+        if (isInternalCallsite(callsite))
+            continue;
+        if (filePath.includes(PACKAGE_SEGMENT)) {
+            packageCandidates.push(filePath);
+            continue;
+        }
+        fallbackCandidates.push(filePath);
+    }
+    const packageCandidate = packageCandidates[0];
+    if (packageCandidate)
+        return packageCandidate;
+    const fallbackCandidate = fallbackCandidates[0];
+    if (fallbackCandidate)
+        return fallbackCandidate;
+    throw new Error("Unable to resolve caller file path.");
+};
+export const getCurrentFilePath = () => resolveCallerFilePath();
+export const getCurrentDirPath = () => path.dirname(getCurrentFilePath());
+export const getRepoRootDir = () => {
+    const currentFilePath = getCurrentFilePath();
+    const index = currentFilePath.lastIndexOf(PACKAGE_SEGMENT);
+    if (index === -1) {
+        throw new Error(`Unable to determine repo root from ${currentFilePath} (missing ${PACKAGE_SEGMENT}).`);
+    }
+    return currentFilePath.slice(0, index);
+};
+export const getPackageRootDir = () => `${getRepoRootDir()}${PACKAGE_SEGMENT.slice(0, -1)}`;
+export const createRequireFromCaller = () => createRequire(getCurrentFilePath());
+export const isMainModule = () => {
+    const entryScript = process.argv.at(1);
+    if (!entryScript)
+        return false;
+    return normalizePath(entryScript) === getCurrentFilePath();
+};

package/dist/v3/shutdown/cleanupLocal.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+/**
+ * Shared cleanup logic for locally launched Chrome.
+ *
+ * Used by both `V3.close()` (normal shutdown) and the supervisor process
+ * (crash cleanup). The caller provides a `killChrome` callback since the
+ * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process
+ * vs raw `process.kill(pid)` from the supervisor.
+ */
+export async function cleanupLocalBrowser(opts) {
+    if (opts.killChrome) {
+        try {
+            await opts.killChrome();
+        }
+        catch {
+            // best-effort
+        }
+    }
+    if (opts.createdTempProfile &&
+        !opts.preserveUserDataDir &&
+        opts.userDataDir) {
+        try {
+            fs.rmSync(opts.userDataDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}

package/dist/v3/shutdown/supervisor.js

@@ -0,0 +1,159 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a stdin lifeline. When the parent dies, stdin closes
+ * and the supervisor performs best-effort cleanup (Chrome kill + temp profile).
+ */
+import { cleanupLocalBrowser } from "./cleanupLocal";
+const SIGKILL_POLL_MS = 250;
+const SIGKILL_TIMEOUT_MS = 7_000;
+const PID_POLL_INTERVAL_MS = 500;
+// `cleanupPromise` guarantees we execute cleanup at most once.
+let config = null;
+let cleanupPromise = null;
+let started = false;
+let localPidKnownGone = false;
+const exit = (code = 0) => {
+    try {
+        process.exit(code);
+    }
+    catch {
+        // ignore
+    }
+};
+// Best-effort two-phase kill: SIGTERM first, then SIGKILL after timeout.
+// Treat only ESRCH as "already gone"; other errors should not imply dead.
+const politeKill = async (pid) => {
+    const isAlive = () => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            const err = error;
+            // ESRCH = "No such process" (PID is already gone).
+            return err.code !== "ESRCH";
+        }
+    };
+    if (!isAlive())
+        return;
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        const err = error;
+        // ESRCH = process already exited; no further action needed.
+        if (err.code === "ESRCH")
+            return;
+    }
+    const deadline = Date.now() + SIGKILL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, SIGKILL_POLL_MS));
+        if (!isAlive())
+            return;
+    }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        // best-effort
+    }
+};
+let pidPollTimer = null;
+// Local-only fallback: if Chrome dies while parent still lives, run cleanup and exit.
+const startPidPolling = (pid) => {
+    if (pidPollTimer)
+        return;
+    pidPollTimer = setInterval(() => {
+        try {
+            process.kill(pid, 0);
+            return;
+        }
+        catch (error) {
+            const err = error;
+            // Only ESRCH means the process is definitely gone.
+            if (err.code !== "ESRCH")
+                return;
+        }
+        localPidKnownGone = true;
+        if (pidPollTimer) {
+            clearInterval(pidPollTimer);
+            pidPollTimer = null;
+        }
+        void runCleanup("Browser process exited").finally(() => exit(0));
+    }, PID_POLL_INTERVAL_MS);
+};
+const cleanupLocal = async (cfg, reason) => {
+    const deletingUserDataDir = Boolean(cfg.createdTempProfile && !cfg.preserveUserDataDir && cfg.userDataDir);
+    await cleanupLocalBrowser({
+        // If polling already observed ESRCH, avoid a follow-up PID kill.
+        // The PID could be reused by a different process before cleanup runs.
+        killChrome: cfg.pid && !localPidKnownGone
+            ? () => {
+                console.error(`[shutdown-supervisor] Shutting down Chrome pid=${cfg.pid} ` +
+                    `(reason=${reason}, deletingUserDataDir=${deletingUserDataDir})`);
+                return politeKill(cfg.pid);
+            }
+            : undefined,
+        userDataDir: cfg.userDataDir,
+        createdTempProfile: cfg.createdTempProfile,
+        preserveUserDataDir: cfg.preserveUserDataDir,
+    });
+};
+// Idempotent cleanup entrypoint used by all supervisor shutdown paths.
+const runCleanup = (reason) => {
+    if (!cleanupPromise) {
+        cleanupPromise = (async () => {
+            const cfg = config;
+            if (!cfg)
+                return;
+            await cleanupLocal(cfg, reason);
+        })();
+    }
+    return cleanupPromise;
+};
+const applyConfig = (nextConfig) => {
+    config = nextConfig;
+    localPidKnownGone = false;
+    if (config.pid) {
+        startPidPolling(config.pid);
+    }
+};
+const onLifelineClosed = (reason) => {
+    void runCleanup(reason).finally(() => exit(0));
+};
+const parseConfigFromArgv = (argv = process.argv.slice(2)) => {
+    const prefix = "--supervisor-config=";
+    const raw = argv.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+    if (!argv.includes("--supervisor") || !raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+export const runShutdownSupervisor = (initialConfig) => {
+    if (started)
+        return;
+    started = true;
+    applyConfig(initialConfig);
+    // Stdin is the lifeline; losing it means parent is gone.
+    try {
+        process.stdin.resume();
+        process.stdin.on("end", () => onLifelineClosed("Stagehand process completed"));
+        process.stdin.on("close", () => onLifelineClosed("Stagehand process completed"));
+        process.stdin.on("error", () => onLifelineClosed("Stagehand process crashed or was killed"));
+    }
+    catch {
+        // ignore
+    }
+};
+export const maybeRunShutdownSupervisorFromArgv = (argv = process.argv.slice(2)) => {
+    const parsed = parseConfigFromArgv(argv);
+    if (!parsed)
+        return false;
+    runShutdownSupervisor(parsed);
+    return true;
+};

package/dist/v3/shutdown/supervisorClient.js

@@ -0,0 +1,88 @@
+/**
+ * Parent-side helper for spawning the shutdown supervisor process.
+ *
+ * The supervisor runs out-of-process and watches a lifeline pipe. If the parent
+ * dies, the supervisor performs best-effort cleanup (Chrome kill, temp profile)
+ * when keepAlive is false.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { getCurrentFilePath } from "../runtimePaths";
+import { ShutdownSupervisorResolveError, ShutdownSupervisorSpawnError, } from "../types/private/shutdownErrors";
+const moduleFilename = getCurrentFilePath();
+const moduleDir = path.dirname(moduleFilename);
+const nodeRequire = createRequire(moduleFilename);
+const isSeaRuntime = () => {
+    try {
+        const sea = nodeRequire("node:sea");
+        return Boolean(sea.isSea?.());
+    }
+    catch {
+        return false;
+    }
+};
+// SEA: re-exec current binary with supervisor args.
+// Non-SEA: execute Stagehand CLI entrypoint with supervisor args.
+const resolveCliPath = () => `${moduleDir}/../cli.js`;
+const resolveSupervisorCommand = (config) => {
+    const baseArgs = ["--supervisor", serializeConfigArg(config)];
+    if (isSeaRuntime()) {
+        return { command: process.execPath, args: baseArgs };
+    }
+    const cliPath = resolveCliPath();
+    if (!fs.existsSync(cliPath))
+        return null;
+    const needsTsxLoader = fs.existsSync(`${moduleDir}/supervisor.ts`) &&
+        !fs.existsSync(`${moduleDir}/supervisor.js`);
+    return {
+        command: process.execPath,
+        args: needsTsxLoader
+            ? ["--import", "tsx", cliPath, ...baseArgs]
+            : [cliPath, ...baseArgs],
+    };
+};
+// Single JSON arg keeps supervisor bootstrap parsing tiny and versionable.
+const serializeConfigArg = (config) => `--supervisor-config=${JSON.stringify({
+    ...config,
+    parentPid: process.pid,
+})}`;
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export function startShutdownSupervisor(config, opts) {
+    const resolved = resolveSupervisorCommand(config);
+    if (!resolved) {
+        opts?.onError?.(new ShutdownSupervisorResolveError("Shutdown supervisor entry missing (expected Stagehand CLI entrypoint)."), "resolve");
+        return null;
+    }
+    const child = spawn(resolved.command, resolved.args, {
+        // stdin is the parent lifeline.
+        // Preserve supervisor stderr so crash-cleanup debug lines are visible.
+        stdio: ["pipe", "ignore", "inherit"],
+        detached: true,
+    });
+    child.on("error", (error) => {
+        opts?.onError?.(new ShutdownSupervisorSpawnError(`Shutdown supervisor failed to start: ${error.message}`), "spawn");
+    });
+    try {
+        child.unref();
+        const stdin = child.stdin;
+        stdin?.unref?.();
+    }
+    catch {
+        // best-effort: avoid keeping the event loop alive
+    }
+    const stop = () => {
+        // Normal close path: terminate supervisor directly.
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // ignore
+        }
+    };
+    return { stop };
+}

package/dist/v3/timeoutConfig.js

@@ -0,0 +1,31 @@
+import { TimeoutError } from "./types/public/sdkErrors";
+export function getEnvTimeoutMs(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return undefined;
+    const normalized = raw.trim().replace(/ms$/i, "");
+    const value = Number(normalized);
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    return value;
+}
+export async function withTimeout(promise, timeoutMs, operation) {
+    if (typeof timeoutMs !== "number" ||
+        !Number.isFinite(timeoutMs) ||
+        timeoutMs <= 0) {
+        return await promise;
+    }
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new TimeoutError(operation, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}

package/dist/v3/types/private/api.js

@@ -0,0 +1 @@
+export {};

package/dist/v3/types/private/index.js

@@ -0,0 +1,3 @@
+export * from "./api";
+export * from "./internal";
+export * from "./snapshot";

package/dist/v3/types/private/internal.js

@@ -0,0 +1 @@
+export {};

package/dist/v3/types/private/locator.js

@@ -0,0 +1 @@
+export {};

package/dist/v3/types/private/network.js

@@ -0,0 +1,2 @@
+export const DEFAULT_IDLE_WAIT = 500;
+export const IGNORED_RESOURCE_TYPES = new Set(["EventSource", "WebSocket"]);

package/dist/v3/types/private/shutdown.js

@@ -0,0 +1,4 @@
+/**
+ * Internal-only types for the shutdown supervisor process.
+ */
+export {};

package/dist/v3/types/private/shutdownErrors.js

@@ -0,0 +1,21 @@
+/**
+ * Internal-only errors for the shutdown supervisor.
+ */
+export class ShutdownSupervisorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorError";
+    }
+}
+export class ShutdownSupervisorResolveError extends ShutdownSupervisorError {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorResolveError";
+    }
+}
+export class ShutdownSupervisorSpawnError extends ShutdownSupervisorError {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorSpawnError";
+    }
+}

package/dist/v3/types/private/snapshot.js

@@ -0,0 +1 @@
+export {};

package/dist/v3/types/public/api.js

@@ -0,0 +1,36 @@
+/**
+ * Local browser launch options schema (Zod).
+ */
+import { z } from "zod";
+export const LocalBrowserLaunchOptionsSchema = z
+    .object({
+    args: z.array(z.string()).optional(),
+    executablePath: z.string().optional(),
+    port: z.number().optional(),
+    userDataDir: z.string().optional(),
+    preserveUserDataDir: z.boolean().optional(),
+    headless: z.boolean().optional(),
+    devtools: z.boolean().optional(),
+    chromiumSandbox: z.boolean().optional(),
+    ignoreDefaultArgs: z.union([z.boolean(), z.array(z.string())]).optional(),
+    proxy: z
+        .object({
+        server: z.string(),
+        bypass: z.string().optional(),
+        username: z.string().optional(),
+        password: z.string().optional(),
+    })
+        .optional(),
+    locale: z.string().optional(),
+    viewport: z.object({ width: z.number(), height: z.number() }).optional(),
+    deviceScaleFactor: z.number().optional(),
+    hasTouch: z.boolean().optional(),
+    ignoreHTTPSErrors: z.boolean().optional(),
+    cdpUrl: z.string().optional(),
+    cdpHeaders: z.record(z.string(), z.string()).optional(),
+    connectTimeoutMs: z.number().optional(),
+    downloadsPath: z.string().optional(),
+    acceptDownloads: z.boolean().optional(),
+})
+    .strict()
+    .meta({ id: "LocalBrowserLaunchOptions" });