@promptbook/wizard 0.112.0-12 → 0.112.0-13

package/esm/index.es.js

@@ -13,10 +13,7 @@ import { basename, join, dirname, isAbsolute, relative } from 'path';
 import { Readability } from '@mozilla/readability';
 import { JSDOM } from 'jsdom';
 import { Converter } from 'showdown';
-import { randomBytes, randomUUID } from 'crypto';
-import { tmpdir } from 'os';
-import { ConfigChecker } from 'configchecker';
-import { chromium } from 'playwright';
+import { randomBytes } from 'crypto';
 import * as dotenv from 'dotenv';
 import sha256 from 'crypto-js/sha256';
 import JSZip from 'jszip';
@@ -41,7 +38,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-12';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-13';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -5965,15 +5962,6 @@ function parseToolRuntimeContext(rawValue) {
 function readToolRuntimeContextFromToolArgs(args) {
     return parseToolRuntimeContext(args[TOOL_RUNTIME_CONTEXT_ARGUMENT]);
 }
-/**
- * Reads the hidden tool-progress token from tool arguments.
- *
- * @private internal runtime wiring for commitment tools
- */
-function readToolProgressTokenFromToolArgs(args) {
-    const token = args[TOOL_PROGRESS_TOKEN_ARGUMENT];
-    return typeof token === 'string' && token.trim().length > 0 ? token : null;
-}
 /**
  * Serializes runtime context for prompt parameters.
  *
@@ -6007,26 +5995,6 @@ function registerToolCallProgressListener(listener) {
 function unregisterToolCallProgressListener(token) {
     toolCallProgressListeners.delete(token);
 }
-/**
- * Emits one tool progress update using a hidden token carried in tool arguments.
- *
- * @param args - Raw tool arguments including hidden runtime keys.
- * @param update - Incremental progress update.
- * @returns `true` when a listener was found and notified.
- * @private internal runtime wiring for commitment tools
- */
-function emitToolCallProgressFromToolArgs(args, update) {
-    const token = readToolProgressTokenFromToolArgs(args);
-    if (!token) {
-        return false;
-    }
-    const listener = toolCallProgressListeners.get(token);
-    if (!listener) {
-        return false;
-    }
-    listener(update);
-    return true;
-}
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
@@ -27486,9 +27454,9 @@ function createTimeoutSystemMessage(extraInstructions) {
     return spaceTrim$1((block) => `
             Timeout scheduling:
             - Use "set_timeout" to wake this same chat thread in the future.
-            - Timers are thread-scoped, not global for the whole agent.
+            - Use "list_timeouts" to review timeouts across all chats for the same user+agent scope.
+            - "cancel_timeout" accepts a timeout id from any chat in this same user+agent scope.
             - When one timeout elapses, you will receive a new user-like message that explicitly says it is a timeout wake-up and includes the \`timeoutId\`.
-            - Use "cancel_timeout" when a previously scheduled timeout is no longer relevant.
             - Do not claim a timer was set or cancelled unless the tool confirms it.
             ${block(extraInstructions)}
         `);
@@ -27500,13 +27468,6 @@ function createTimeoutSystemMessage(extraInstructions) {
  * @private internal utility of USE TIMEOUT
  */
 function createDisabledTimeoutResult(action, message) {
-    if (action === 'set') {
-        return {
-            action,
-            status: 'disabled',
-            message,
-        };
-    }
     return {
         action,
         status: 'disabled',
@@ -27533,6 +27494,18 @@ function getTimeoutToolRuntimeAdapterOrDisabledResult(action, runtimeContext) {
     }
 }
 
+/**
+ * Default number of rows returned by `list_timeouts`.
+ *
+ * @private internal USE TIMEOUT constant
+ */
+const DEFAULT_LIST_TIMEOUTS_LIMIT = 20;
+/**
+ * Hard cap for `list_timeouts` page size.
+ *
+ * @private internal USE TIMEOUT constant
+ */
+const MAX_LIST_TIMEOUTS_LIMIT = 100;
 /**
  * Parses and validates `USE TIMEOUT` tool arguments.
  *
@@ -27567,6 +27540,31 @@ const parseTimeoutToolArgs = {
         }
         return { timeoutId };
     },
+    /**
+     * Parses `list_timeouts` input.
+     */
+    list(args) {
+        if (args.includeFinished !== undefined && typeof args.includeFinished !== 'boolean') {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout \`includeFinished\` must be a boolean when provided.
+                `));
+        }
+        const parsedLimit = args.limit === undefined ? DEFAULT_LIST_TIMEOUTS_LIMIT : Math.floor(Number(args.limit));
+        if (!Number.isFinite(parsedLimit) || parsedLimit <= 0) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout \`limit\` must be a positive number.
+                `));
+        }
+        if (parsedLimit > MAX_LIST_TIMEOUTS_LIMIT) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout \`limit\` must be at most \`${MAX_LIST_TIMEOUTS_LIMIT}\`.
+                `));
+        }
+        return {
+            includeFinished: args.includeFinished === true,
+            limit: parsedLimit,
+        };
+    },
 };
 
 /**
@@ -27577,6 +27575,7 @@ const parseTimeoutToolArgs = {
 const TimeoutToolNames = {
     set: 'set_timeout',
     cancel: 'cancel_timeout',
+    list: 'list_timeouts',
 };
 
 /**
@@ -27676,6 +27675,35 @@ function createTimeoutToolFunctions() {
                 return JSON.stringify(result);
             }
         },
+        async [TimeoutToolNames.list](args) {
+            const runtimeContext = resolveTimeoutRuntimeContext(args);
+            const { adapter, disabledResult } = getTimeoutToolRuntimeAdapterOrDisabledResult('list', runtimeContext);
+            if (!adapter || disabledResult) {
+                return JSON.stringify(disabledResult);
+            }
+            try {
+                const parsedArgs = parseTimeoutToolArgs.list(args);
+                const listedTimeouts = await adapter.listTimeouts(parsedArgs, runtimeContext);
+                const result = {
+                    action: 'list',
+                    status: 'listed',
+                    items: listedTimeouts.items,
+                    total: listedTimeouts.total,
+                };
+                return createToolExecutionEnvelope({
+                    assistantMessage: listedTimeouts.total === 1 ? 'Found 1 timeout.' : `Found ${listedTimeouts.total} timeouts.`,
+                    toolResult: result,
+                });
+            }
+            catch (error) {
+                const result = {
+                    action: 'list',
+                    status: 'error',
+                    message: error instanceof Error ? error.message : String(error),
+                };
+                return JSON.stringify(result);
+            }
+        },
     };
 }
 
@@ -27709,26 +27737,45 @@ function createTimeoutTools(existingTools = []) {
     if (!tools.some((tool) => tool.name === TimeoutToolNames.cancel)) {
         tools.push({
             name: TimeoutToolNames.cancel,
-            description: 'Cancel one previously scheduled timeout in the current chat thread.',
+            description: 'Cancel one previously scheduled timeout within the same user+agent scope, even if it was set in another chat.',
             parameters: {
                 type: 'object',
                 properties: {
                     timeoutId: {
                         type: 'string',
-                        description: 'Identifier returned earlier by `set_timeout`.',
+                        description: 'Identifier returned earlier by `set_timeout` or `list_timeouts`.',
                     },
                 },
                 required: ['timeoutId'],
             },
         });
     }
+    if (!tools.some((tool) => tool.name === TimeoutToolNames.list)) {
+        tools.push({
+            name: TimeoutToolNames.list,
+            description: 'List scheduled timeouts across all chats for this same user+agent scope so they can be reviewed or cancelled.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    includeFinished: {
+                        type: 'boolean',
+                        description: 'When true, include completed, failed, and cancelled rows in addition to active timeouts.',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum number of rows to return (default 20, max 100).',
+                    },
+                },
+            },
+        });
+    }
     return tools;
 }
 
 /**
  * `USE TIMEOUT` commitment definition.
  *
- * The `USE TIMEOUT` commitment enables thread-scoped timers that wake the same chat later.
+ * The `USE TIMEOUT` commitment enables timeout wake-ups and scoped timeout management.
  *
  * @private [🪔] Maybe export the commitments through some package
  */
@@ -27743,7 +27790,7 @@ class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of `USE TIMEOUT`.
      */
     get description() {
-        return 'Enable thread-scoped timers that can wake the same chat in the future.';
+        return 'Enable timeout wake-ups plus scoped timeout listing/cancellation across chats.';
     }
     /**
      * Icon for this commitment.
@@ -27758,14 +27805,15 @@ class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # USE TIMEOUT
 
-            Enables the agent to schedule thread-scoped timeout wake-ups.
+            Enables timeout wake-ups and timeout management for the same user+agent scope.
 
             ## Key aspects
 
             - The agent uses \`set_timeout\` to schedule a future wake-up in the same chat thread.
             - The tool returns immediately while the timeout is stored and executed by the runtime later.
             - The wake-up arrives as a new user-like timeout message in the same conversation.
-            - The agent can cancel an existing timeout by \`timeoutId\` via \`cancel_timeout\`.
+            - The agent can inspect known timeouts via \`list_timeouts\`.
+            - The agent can cancel an existing timeout by \`timeoutId\` via \`cancel_timeout\`, including timeouts created in another chat.
             - Commitment content is treated as optional timeout policy instructions.
 
             ## Examples
@@ -27794,6 +27842,7 @@ class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition {
         return {
             [TimeoutToolNames.set]: 'Set timer',
             [TimeoutToolNames.cancel]: 'Cancel timer',
+            [TimeoutToolNames.list]: 'List timers',
         };
     }
     /**
@@ -30176,2203 +30225,177 @@ async function fetchUrlContent(url) {
  */
 
 /**
- * Logical public directory marker used in `run_browser` payload paths.
+ * Cached implementation of `run_browser` when it can be resolved.
  *
- * This value is kept stable for UI parsing and `/api/browser-artifacts/*` URL mapping.
- */
-const RUN_BROWSER_ARTIFACT_PUBLIC_DIRECTORY = '.playwright-cli';
-/**
- * Runtime environment variable that overrides local artifact storage directory.
- */
-const RUN_BROWSER_ARTIFACT_STORAGE_DIRECTORY_ENV = 'RUN_BROWSER_ARTIFACT_STORAGE_DIRECTORY';
-/**
- * Default writable directory for `run_browser` screenshot/video artifacts.
+ * @private internal utility for USE BROWSER commitment
  */
-const DEFAULT_RUN_BROWSER_ARTIFACT_STORAGE_DIRECTORY = join(tmpdir(), 'promptbook', 'run-browser-artifacts');
+let cachedRunBrowserTool = null;
 /**
- * Converts Windows separators to POSIX separators for payload paths.
+ * Cached loading error to avoid repeating expensive resolution attempts.
+ *
+ * @private internal utility for USE BROWSER commitment
  */
-function toPosixPath(pathname) {
-    return pathname.split('\\').join('/');
-}
+let cachedRunBrowserToolError = null;
 /**
- * Resolves writable filesystem directory used for artifact persistence.
+ * Attempts to load the server-side `run_browser` tool lazily.
+ *
+ * @returns Loaded `run_browser` implementation
+ * @private internal utility for USE BROWSER commitment
  */
-function resolveRunBrowserArtifactStorageDirectory() {
-    const configuredStorageDirectory = process.env[RUN_BROWSER_ARTIFACT_STORAGE_DIRECTORY_ENV];
-    if (configuredStorageDirectory && configuredStorageDirectory.trim()) {
-        return configuredStorageDirectory.trim();
+function loadRunBrowserToolForNode() {
+    if (cachedRunBrowserTool !== null) {
+        return cachedRunBrowserTool;
     }
-    return DEFAULT_RUN_BROWSER_ARTIFACT_STORAGE_DIRECTORY;
-}
-/**
- * Resolves absolute filesystem path of one artifact filename.
- */
-function resolveRunBrowserArtifactFilesystemPath(artifactFilename) {
-    return join(resolveRunBrowserArtifactStorageDirectory(), artifactFilename);
-}
-/**
- * Resolves payload path of one artifact filename used by replay renderers.
- */
-function resolveRunBrowserArtifactPublicPath(artifactFilename) {
-    return toPosixPath(`${RUN_BROWSER_ARTIFACT_PUBLIC_DIRECTORY}/${artifactFilename}`);
-}
-
-/**
- * Error code used for remote-browser infrastructure outages.
- */
-const REMOTE_BROWSER_UNAVAILABLE_ERROR_CODE = 'REMOTE_BROWSER_UNAVAILABLE';
-/**
- * Error thrown when a remote Playwright browser cannot be reached.
- */
-class RemoteBrowserUnavailableError extends KnowledgeScrapeError {
-    constructor(options) {
-        var _a;
-        super(options.message);
-        this.code = REMOTE_BROWSER_UNAVAILABLE_ERROR_CODE;
-        this.isRetryable = true;
-        this.debug = options.debug;
-        this.suggestedNextSteps =
-            (_a = options.suggestedNextSteps) !== null && _a !== void 0 ? _a : [
-                'Verify remote browser infrastructure is running and reachable from Agents Server.',
-                'Check firewall and DNS routing for the remote browser host and port.',
-                'Retry later or continue with non-graphical fallback scraping.',
-            ];
-        this.cause = options.cause;
-        Object.setPrototypeOf(this, RemoteBrowserUnavailableError.prototype);
+    if (cachedRunBrowserToolError !== null) {
+        throw cachedRunBrowserToolError;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const runBrowserModule = require('../../../apps/agents-server/src/tools/run_browser');
+        if (typeof runBrowserModule.run_browser !== 'function') {
+            throw new Error('run_browser value is not a function but ' + typeof runBrowserModule.run_browser);
+        }
+        cachedRunBrowserTool = runBrowserModule.run_browser;
+        return cachedRunBrowserTool;
+    }
+    catch (error) {
+        assertsError(error);
+        cachedRunBrowserToolError = error;
+        throw error;
     }
 }
 /**
- * Returns true when an unknown value is one of the remote-browser outage errors.
+ * Resolves the server-side implementation of the `run_browser` tool for Node.js environments.
+ *
+ * This uses fully lazy resolution to keep CLI startup independent from optional browser tooling.
+ * When the server tool cannot be resolved, the fallback implementation throws a helpful error.
+ *
+ * @private internal utility for USE BROWSER commitment
  */
-function isRemoteBrowserUnavailableError(error) {
-    return error instanceof RemoteBrowserUnavailableError;
+function resolveRunBrowserToolForNode() {
+    return async (args) => {
+        try {
+            const runBrowserTool = loadRunBrowserToolForNode();
+            return await runBrowserTool(args);
+        }
+        catch (error) {
+            assertsError(error);
+            throw new EnvironmentMismatchError(spaceTrim$1((block) => `
+                        \`run_browser\` tool is not available in this environment.
+                        This commitment requires the Agents Server browser runtime with Playwright CLI.
+
+                        ${error.name}:
+                        ${block(error.message)}
+                    `));
+        }
+    };
 }
+
 /**
- * Sanitizes a remote websocket endpoint so debug payloads never expose path secrets.
+ * Resolves the server-side implementation of the send_email tool for Node.js environments.
+ *
+ * This uses a lazy require so the core package can still load even if the Agents Server
+ * module is unavailable. When the server tool cannot be resolved, a fallback implementation
+ * throws a helpful error message.
+ *
+ * @private internal utility for USE EMAIL commitment
  */
-function sanitizeRemoteBrowserEndpoint(wsEndpoint) {
-    var _a, _b;
+function resolveSendEmailToolForNode() {
     try {
-        const parsedEndpoint = new URL(wsEndpoint);
-        return {
-            protocol: parsedEndpoint.protocol || null,
-            host: parsedEndpoint.hostname || null,
-            port: parsedEndpoint.port ? Number.parseInt(parsedEndpoint.port, 10) : null,
-        };
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { send_email } = require('../../../apps/agents-server/src/tools/send_email');
+        if (typeof send_email !== 'function') {
+            throw new Error('send_email value is not a function but ' + typeof send_email);
+        }
+        return send_email;
     }
-    catch (_c) {
-        const hostPortMatch = wsEndpoint.trim().match(/^(?:wss?:\/\/)?(?<host>[^:/?#]+)(?::(?<port>\d{1,5}))?/i);
-        const host = ((_a = hostPortMatch === null || hostPortMatch === void 0 ? void 0 : hostPortMatch.groups) === null || _a === void 0 ? void 0 : _a.host) || null;
-        const parsedPort = (_b = hostPortMatch === null || hostPortMatch === void 0 ? void 0 : hostPortMatch.groups) === null || _b === void 0 ? void 0 : _b.port;
-        return {
-            protocol: wsEndpoint.startsWith('wss://') ? 'wss:' : wsEndpoint.startsWith('ws://') ? 'ws:' : null,
-            host,
-            port: parsedPort ? Number.parseInt(parsedPort, 10) : null,
+    catch (error) {
+        const normalizedError = error instanceof Error
+            ? error
+            : new Error(typeof error === 'string' ? error : JSON.stringify(error !== null && error !== void 0 ? error : 'Unknown error'));
+        return async () => {
+            throw new EnvironmentMismatchError(spaceTrim$1((block) => `
+                        \`send_email\` tool is not available in this environment.
+                        This commitment requires Agents Server runtime with wallet-backed SMTP sending.
+
+                        ${normalizedError.name}:
+                        ${block(normalizedError.message)}
+                    `));
         };
     }
 }
+
 /**
- * Extracts network-like error code from unknown error payload.
+ * Resolves the server-side `spawn_agent` tool for Node.js runtimes.
+ *
+ * Uses lazy require so core package can load outside Agents Server.
+ *
+ * @private internal utility for USE SPAWN commitment
  */
-function extractNetworkErrorCode(error) {
-    var _a;
-    if (error && typeof error === 'object') {
-        const maybeCode = error.code;
-        if (typeof maybeCode === 'string' && maybeCode.trim()) {
-            return maybeCode.trim().toUpperCase();
+function resolveSpawnAgentToolForNode() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { spawn_agent } = require('../../../apps/agents-server/src/tools/spawn_agent');
+        if (typeof spawn_agent !== 'function') {
+            throw new Error('spawn_agent value is not a function but ' + typeof spawn_agent);
         }
+        return spawn_agent;
     }
-    const message = getErrorMessage(error);
-    const match = message.match(/\b(ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ECONNRESET|EHOSTUNREACH|ENETUNREACH)\b/i);
-    return ((_a = match === null || match === void 0 ? void 0 : match[1]) === null || _a === void 0 ? void 0 : _a.toUpperCase()) || null;
-}
-/**
- * Classifies whether an unknown error most likely represents remote browser infra outage.
- */
-function isRemoteBrowserInfrastructureError(error) {
-    const networkErrorCode = extractNetworkErrorCode(error);
-    if (networkErrorCode) {
-        return true;
-    }
-    const message = getErrorMessage(error).toLowerCase();
-    const isWebSocketFailure = message.includes('websocket') ||
-        message.includes('<ws error>') ||
-        message.includes('ws connect error') ||
-        message.includes('socket hang up');
-    const hasHandshakeFailure = message.includes('unexpected server response') ||
-        message.includes('handshake') ||
-        message.includes('code=1006') ||
-        message.includes('disconnected');
-    return isWebSocketFailure && hasHandshakeFailure;
-}
-/**
- * Converts unknown thrown values into safe string messages.
- */
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-/**
- * Converts unknown errors into stack payloads that are safe to render in debug mode.
- */
-function getErrorStack(error) {
-    return error instanceof Error && error.stack ? error.stack : null;
-}
+    catch (error) {
+        const normalizedError = error instanceof Error
+            ? error
+            : new Error(typeof error === 'string' ? error : JSON.stringify(error !== null && error !== void 0 ? error : 'Unknown error'));
+        return async () => {
+            throw new EnvironmentMismatchError(spaceTrim$1((block) => `
+                        \`spawn_agent\` tool is not available in this environment.
+                        This commitment requires Agents Server runtime with agent persistence enabled.
 
-/**
- * Matches unsupported characters in snapshot file suffixes.
- */
-const SNAPSHOT_FILE_SUFFIX_UNSAFE_CHARACTER_PATTERN = /[^a-z0-9-]/g;
-/**
- * Creates one filesystem-safe optional filename suffix for a snapshot.
- */
-function createSnapshotFileSuffix(rawSuffix) {
-    if (!rawSuffix) {
-        return '';
+                        ${normalizedError.name}:
+                        ${block(normalizedError.message)}
+                    `));
+        };
     }
-    const normalized = rawSuffix
-        .trim()
-        .toLowerCase()
-        .replace(/\s+/g, '-')
-        .replace(SNAPSHOT_FILE_SUFFIX_UNSAFE_CHARACTER_PATTERN, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '');
-    return normalized;
-}
-/**
- * Resolves snapshot filename for one session and optional stage suffix.
- */
-function resolveSnapshotFilename(sessionId, fileSuffix) {
-    const safeSuffix = createSnapshotFileSuffix(fileSuffix);
-    return safeSuffix ? `${sessionId}-${safeSuffix}.png` : `${sessionId}.png`;
 }
+
 /**
- * Creates one user-facing description for an executed browser action.
+ * Collects tool functions from all commitment definitions.
+ *
+ * @returns Map of tool function implementations.
+ * @private internal helper for commitment tool registry
  */
-function formatActionSummary(action) {
-    switch (action.type) {
-        case 'navigate':
-            return `Navigate to ${action.url}`;
-        case 'click':
-            return `Click ${action.selector}`;
-        case 'type':
-            return `Type into ${action.selector}`;
-        case 'wait':
-            return `Wait ${action.milliseconds}ms`;
-        case 'scroll':
-            return action.selector ? `Scroll ${action.pixels}px in ${action.selector}` : `Scroll ${action.pixels}px on page`;
+function collectCommitmentToolFunctions() {
+    const allToolFunctions = {};
+    for (const commitmentDefinition of getAllCommitmentDefinitions()) {
+        const toolFunctions = commitmentDefinition.getToolFunctions();
+        for (const [funcName, funcImpl] of Object.entries(toolFunctions)) {
+            if (allToolFunctions[funcName] !== undefined &&
+                just(false) /* <- Note: [??] How to deal with commitment aliases */) {
+                throw new UnexpectedError(`Duplicate tool function name detected: \`${funcName}\` provided by commitment \`${commitmentDefinition.type}\``);
+            }
+            allToolFunctions[funcName] = funcImpl;
+        }
     }
+    return allToolFunctions;
 }
 /**
- * Screenshot/artifact and page-cleanup helpers for `run_browser`.
+ * Creates a proxy that resolves tool functions on demand.
  *
- * @private function of `run_browser`
+ * @param getFunctions - Provider of current tool functions.
+ * @returns Proxy exposing tool functions as properties.
+ * @private internal helper for commitment tool registry
  */
-const runBrowserArtifacts = {
-    /**
-     * Captures a screenshot artifact for the current page and returns relative path.
-     */
-    async captureSnapshot(page, sessionId, fileSuffix) {
-        const snapshotFilename = resolveSnapshotFilename(sessionId, fileSuffix);
-        const snapshotDirectoryPath = resolveRunBrowserArtifactStorageDirectory();
-        const snapshotPath = resolveRunBrowserArtifactFilesystemPath(snapshotFilename);
-        try {
-            await mkdir(snapshotDirectoryPath, { recursive: true });
-            try {
-                await page.screenshot({ path: snapshotPath, fullPage: true });
+function createToolFunctionsProxy(getFunctions) {
+    const resolveFunctions = () => getFunctions();
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
             }
-            catch (error) {
-                console.warn('[run_browser] Full-page snapshot failed, retrying viewport-only screenshot', {
-                    sessionId,
-                    snapshotFilename,
-                    error: getErrorMessage(error),
-                });
-                await page.screenshot({ path: snapshotPath, fullPage: false });
-            }
-            return resolveRunBrowserArtifactPublicPath(snapshotFilename);
-        }
-        catch (error) {
-            console.error('[run_browser] Failed to capture snapshot', {
-                sessionId,
-                snapshotFilename,
-                error: getErrorMessage(error),
-            });
-            return null;
-        }
-    },
-    /**
-     * Safely retrieves page title from current browser page.
-     */
-    async getPageTitle(page) {
-        try {
-            return await page.title();
-        }
-        catch (_a) {
-            return null;
-        }
-    },
-    /**
-     * Closes browser page and logs non-fatal cleanup errors.
-     */
-    async cleanupPage(page, sessionId) {
-        if (!page) {
-            return;
-        }
-        try {
-            await page.close();
-        }
-        catch (error) {
-            console.error('[run_browser] Failed to cleanup browser page', {
-                sessionId,
-                error: getErrorMessage(error),
-            });
-        }
-    },
-    /**
-     * Captures one screenshot artifact and enriches it with page metadata.
-     */
-    async captureSnapshotArtifact(options) {
-        const { page, sessionId, label, fileSuffix, actionIndex, action } = options;
-        const path = await this.captureSnapshot(page, sessionId, fileSuffix);
-        if (!path) {
-            return null;
-        }
-        const actionSummary = action ? formatActionSummary(action) : undefined;
-        return {
-            kind: 'screenshot',
-            label,
-            path,
-            capturedAt: new Date().toISOString(),
-            url: page.url(),
-            title: await this.getPageTitle(page),
-            actionIndex,
-            actionSummary,
-        };
-    },
-};
-
-/**
- * Shared constants used by the `run_browser` tool.
- *
- * @private internal constants of `run_browser`
- */
-const runBrowserConstants = {
-    sessionPrefix: 'agents-server-run-browser',
-    snapshotDirectory: '.playwright-cli',
-    resultSchema: 'promptbook/run-browser@1',
-    defaultWaitMs: 1000,
-    maxWaitMs: 60000,
-    defaultScrollPixels: 800,
-    defaultNavigationTimeoutMs: 20000,
-    defaultActionTimeoutMs: 15000,
-    fallbackDynamicContentWarning: 'Remote browser is unavailable. Fallback scraping was used and dynamic content may be missing.',
-    validationErrorCode: 'RUN_BROWSER_VALIDATION_ERROR',
-    navigationFailedErrorCode: 'RUN_BROWSER_NAVIGATION_FAILED',
-    actionFailedErrorCode: 'RUN_BROWSER_ACTION_FAILED',
-    cancelledErrorCode: 'RUN_BROWSER_CANCELLED',
-    unknownErrorCode: 'RUN_BROWSER_UNKNOWN_ERROR',
-};
-
-const config = ConfigChecker.from({
-    ...process.env,
-    // Note: To expose env variables to the browser, using this seemingly strange syntax:
-    //       @see https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables#exposing-environment-variables-to-the-browser
-    NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
-    NEXT_PUBLIC_VERCEL_ENV: process.env.NEXT_PUBLIC_VERCEL_ENV,
-    NEXT_PUBLIC_VERCEL_TARGET_ENV: process.env.NEXT_PUBLIC_VERCEL_TARGET_ENV,
-    NEXT_PUBLIC_VERCEL_URL: process.env.NEXT_PUBLIC_VERCEL_URL,
-    NEXT_PUBLIC_VERCEL_BRANCH_URL: process.env.NEXT_PUBLIC_VERCEL_BRANCH_URL,
-    NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL: process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL,
-    NEXT_PUBLIC_VERCEL_GIT_PROVIDER: process.env.NEXT_PUBLIC_VERCEL_GIT_PROVIDER,
-    NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER: process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER,
-    NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG: process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG,
-    NEXT_PUBLIC_VERCEL_GIT_REPO_ID: process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_ID,
-    NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
-    NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE,
-    NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF,
-    NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME,
-    NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN,
-    NEXT_PUBLIC_VERCEL_GIT_PREVIOUS_SHA: process.env.NEXT_PUBLIC_VERCEL_GIT_PREVIOUS_SHA,
-    NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID: process.env.NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
-});
-/**
- * Public URL of the deployment, e.g. "https://my-app.vercel.app"
- *
- * Note: When a request resolves through the global `_Server` registry,
- * this URL will be overridden by the matched server domain.
- */
-config.get('NEXT_PUBLIC_SITE_URL').url().value;
-/**
- * [♐️] Vercel environment: "development" | "preview" | "production"
- */
-config.get('NEXT_PUBLIC_VERCEL_ENV').value;
-/**
- * [♐️] Target environment – can be system or custom
- */
-config.get('NEXT_PUBLIC_VERCEL_TARGET_ENV').value;
-/**
- * [♐️] Deployment URL (without https://), e.g. "my-app-abc123.vercel.app"
- */
-config.get('NEXT_PUBLIC_VERCEL_URL').value;
-/**
- * [♐️] Branch URL (without https://), only for branch deployments
- */
-config.get('NEXT_PUBLIC_VERCEL_BRANCH_URL').value;
-/**
- * [♐️] Production domain of the project
- */
-config.get('NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL').value;
-/**
- * [♐️] Git provider (github | gitlab | bitbucket)
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_PROVIDER').value;
-/**
- * [♐️] Repository owner (e.g. "hejny")
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER').value;
-/**
- * [♐️] Repository slug (e.g. "my-project")
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG').value;
-/**
- * [♐️] Repository internal ID
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_REPO_ID').value;
-/**
- * [♐️] Git commit SHA (short or long)
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA').value;
-/**
- * [♐️] Commit message used for this deployment
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE').value;
-/**
- * [♐️] Branch name (ref), e.g. "main"
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF').value;
-/**
- * Author name of the commit
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME').value;
-/**
- * [♐️] Author login/username
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN').value;
-/**
- * [♐️] Previous deployment commit SHA (if exists)
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_PREVIOUS_SHA').value;
-/**
- * [♐️] Pull Request ID for PR-based deployments
- */
-config.get('NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID').value;
-/**
- * Supabase table prefix
- *
- * This remains the fallback/default prefix used before `_Server` contains records
- * or for local development requests.
- */
-config.get('SUPABASE_TABLE_PREFIX').value;
-/**
- * WebSocket endpoint URL for remote Playwright browser server (e.g., ws://browser-server:3000).
- *
- * When set, browser automation will connect to this remote server instead of launching a local browser.
- * This is useful for environments like Vercel where running a full browser locally is not possible.
- * Leave empty to use local browser mode.
- */
-const rawRemoteBrowserUrl = config.get('REMOTE_BROWSER_URL').value;
-/**
- * WebSocket endpoint URL for remote Playwright browser server (e.g., ws://browser-server:3000).
- *
- * When set, browser automation will connect to this remote server instead of launching a local browser.
- * This is useful for environments like Vercel where running a full browser locally is not possible.
- * Leave empty to use local browser mode.
- */
-const REMOTE_BROWSER_URL = typeof rawRemoteBrowserUrl === 'string' ? rawRemoteBrowserUrl : '';
-
-/**
- * Reads a positive integer value from environment variables.
- */
-function resolvePositiveIntFromEnv$1(variableName, defaultValue) {
-    const rawValue = process.env[variableName];
-    if (!rawValue || !rawValue.trim()) {
-        return defaultValue;
-    }
-    const parsed = Number.parseInt(rawValue.trim(), 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        return defaultValue;
-    }
-    return parsed;
-}
-/**
- * Runtime helpers for mode/session/timeout handling in `run_browser`.
- *
- * @private function of `run_browser`
- */
-const runBrowserRuntime = {
-    /**
-     * Creates a dedicated session id for one tool invocation.
-     */
-    createRunBrowserSessionId() {
-        return `${runBrowserConstants.sessionPrefix}-${randomUUID()}`;
-    },
-    /**
-     * Determines whether the browser tool is running in local or remote mode.
-     */
-    resolveExecutionMode() {
-        return REMOTE_BROWSER_URL && REMOTE_BROWSER_URL.trim().length > 0 ? 'remote' : 'local';
-    },
-    /**
-     * Converts the execution mode into a human-readable label.
-     */
-    formatExecutionMode(mode) {
-        return mode === 'remote' ? 'remote-browser' : 'local-browser';
-    },
-    /**
-     * Resolves timeout configuration from env defaults and optional call overrides.
-     */
-    resolveTimeoutConfiguration(overrides) {
-        const envNavigationTimeoutMs = resolvePositiveIntFromEnv$1('RUN_BROWSER_NAVIGATION_TIMEOUT_MS', runBrowserConstants.defaultNavigationTimeoutMs);
-        const envActionTimeoutMs = resolvePositiveIntFromEnv$1('RUN_BROWSER_ACTION_TIMEOUT_MS', runBrowserConstants.defaultActionTimeoutMs);
-        const navigationTimeoutMs = (overrides === null || overrides === void 0 ? void 0 : overrides.navigationMs) && Number.isFinite(overrides.navigationMs) && overrides.navigationMs > 0
-            ? Math.floor(overrides.navigationMs)
-            : envNavigationTimeoutMs;
-        const actionTimeoutMs = (overrides === null || overrides === void 0 ? void 0 : overrides.actionMs) && Number.isFinite(overrides.actionMs) && overrides.actionMs > 0
-            ? Math.floor(overrides.actionMs)
-            : envActionTimeoutMs;
-        return {
-            navigationTimeoutMs,
-            actionTimeoutMs,
-        };
-    },
-};
-
-/**
- * Error classification and cancellation helpers used by `run_browser`.
- *
- * @private function of `run_browser`
- */
-const runBrowserErrorHandling = {
-    /**
-     * Creates one tagged ParseError used for deterministic input validation failures.
-     */
-    createRunBrowserValidationError(options) {
-        const error = new ParseError(options.message);
-        error.name = 'RunBrowserValidationError';
-        error.runBrowserCode = runBrowserConstants.validationErrorCode;
-        error.isRetryable = false;
-        error.suggestedNextSteps = [
-            'Fix the action payload to match the run_browser schema.',
-            'Check selectors and required action fields before retrying.',
-        ];
-        error.debug = options.debug;
-        return error;
-    },
-    /**
-     * Creates one tagged KnowledgeScrapeError used for navigation failures.
-     */
-    createRunBrowserNavigationError(options) {
-        const error = new KnowledgeScrapeError(options.message);
-        error.name = 'RunBrowserNavigationError';
-        error.runBrowserCode = runBrowserConstants.navigationFailedErrorCode;
-        error.isRetryable = false;
-        error.suggestedNextSteps = [
-            'Verify the URL is reachable and not blocked.',
-            'Retry with a simpler action sequence.',
-        ];
-        error.debug = options.debug;
-        error.cause = options.cause;
-        return error;
-    },
-    /**
-     * Creates one tagged KnowledgeScrapeError used for action failures.
-     */
-    createRunBrowserActionError(options) {
-        const error = new KnowledgeScrapeError(options.message);
-        error.name = 'RunBrowserActionError';
-        error.runBrowserCode = runBrowserConstants.actionFailedErrorCode;
-        error.isRetryable = false;
-        error.suggestedNextSteps = [
-            'Verify selectors and action values.',
-            'Reduce the action sequence to isolate the failing step.',
-        ];
-        error.debug = options.debug;
-        error.cause = options.cause;
-        return error;
-    },
-    /**
-     * Creates one tagged KnowledgeScrapeError used for cancellation.
-     */
-    createRunBrowserCancelledError(options) {
-        const error = new KnowledgeScrapeError(options.message);
-        error.name = 'RunBrowserCancelledError';
-        error.runBrowserCode = runBrowserConstants.cancelledErrorCode;
-        error.isRetryable = true;
-        error.suggestedNextSteps = [
-            'Retry while request context is still active.',
-            'Increase timeout if operation is expected to run longer.',
-        ];
-        error.debug = options.debug;
-        error.cause = options.cause;
-        return error;
-    },
-    /**
-     * Checks whether an unknown error carries run_browser classification tags.
-     */
-    isTaggedRunBrowserError(error) {
-        if (!error || typeof error !== 'object') {
-            return false;
-        }
-        const candidate = error;
-        return (typeof candidate.runBrowserCode === 'string' &&
-            typeof candidate.isRetryable === 'boolean' &&
-            Array.isArray(candidate.suggestedNextSteps) &&
-            typeof candidate.debug === 'object' &&
-            candidate.debug !== null);
-    },
-    /**
-     * Converts unknown errors into structured tool error payloads.
-     */
-    classifyRunBrowserToolError(options) {
-        if (isRemoteBrowserUnavailableError(options.error)) {
-            return {
-                code: options.error.code,
-                message: options.error.message,
-                isRetryable: options.error.isRetryable,
-                suggestedNextSteps: options.error.suggestedNextSteps,
-                debug: {
-                    ...options.error.debug,
-                    sessionId: options.sessionId,
-                    mode: runBrowserRuntime.formatExecutionMode(options.mode),
-                },
-            };
-        }
-        if (this.isTaggedRunBrowserError(options.error)) {
-            return {
-                code: options.error.runBrowserCode,
-                message: options.error.message,
-                isRetryable: options.error.isRetryable,
-                suggestedNextSteps: options.error.suggestedNextSteps,
-                debug: {
-                    ...options.error.debug,
-                    sessionId: options.sessionId,
-                    mode: runBrowserRuntime.formatExecutionMode(options.mode),
-                },
-            };
-        }
-        const remoteBrowserEndpoint = REMOTE_BROWSER_URL && REMOTE_BROWSER_URL.trim().length > 0
-            ? sanitizeRemoteBrowserEndpoint(REMOTE_BROWSER_URL.trim())
-            : null;
-        const message = getErrorMessage(options.error);
-        return {
-            code: runBrowserConstants.unknownErrorCode,
-            message,
-            isRetryable: false,
-            suggestedNextSteps: ['Inspect debug details to identify the failing phase.', 'Retry with fewer actions.'],
-            debug: {
-                sessionId: options.sessionId,
-                mode: runBrowserRuntime.formatExecutionMode(options.mode),
-                remoteBrowserEndpoint,
-                message,
-                stack: getErrorStack(options.error),
-            },
-        };
-    },
-    /**
-     * Asserts that the run was not aborted.
-     */
-    assertNotAborted(signal, sessionId) {
-        if (!(signal === null || signal === void 0 ? void 0 : signal.aborted)) {
-            return;
-        }
-        throw this.createRunBrowserCancelledError({
-            message: 'run_browser execution was cancelled.',
-            debug: { sessionId },
-        });
-    },
-    /**
-     * Returns true when the tool error represents remote browser unavailability.
-     */
-    isRemoteBrowserUnavailableCode(code) {
-        return code === REMOTE_BROWSER_UNAVAILABLE_ERROR_CODE;
-    },
-};
-
-/**
- * In-memory observability counters for browser tool execution.
- */
-const RUN_BROWSER_OBSERVABILITY = {
-    totalRuns: 0,
-    fallbackRuns: 0,
-    errorCodeCounts: {},
-};
-/**
- * Observability counters and metric logging for `run_browser`.
- *
- * @private function of `run_browser`
- */
-const runBrowserObservability = {
-    /**
-     * Increments total-run counter and returns the updated value.
-     */
-    incrementTotalRuns() {
-        RUN_BROWSER_OBSERVABILITY.totalRuns++;
-        return RUN_BROWSER_OBSERVABILITY.totalRuns;
-    },
-    /**
-     * Returns current total run count.
-     */
-    getTotalRuns() {
-        return RUN_BROWSER_OBSERVABILITY.totalRuns;
-    },
-    /**
-     * Increments fallback counter and returns updated metrics.
-     */
-    incrementFallbackRunsAndGetMetrics() {
-        RUN_BROWSER_OBSERVABILITY.fallbackRuns++;
-        return {
-            fallbackRuns: RUN_BROWSER_OBSERVABILITY.fallbackRuns,
-            fallbackRate: RUN_BROWSER_OBSERVABILITY.totalRuns === 0
-                ? 0
-                : RUN_BROWSER_OBSERVABILITY.fallbackRuns / RUN_BROWSER_OBSERVABILITY.totalRuns,
-        };
-    },
-    /**
-     * Increments one error-code counter and returns the updated value.
-     */
-    incrementRunBrowserErrorCodeCounter(code) {
-        const currentValue = RUN_BROWSER_OBSERVABILITY.errorCodeCounts[code] || 0;
-        const nextValue = currentValue + 1;
-        RUN_BROWSER_OBSERVABILITY.errorCodeCounts[code] = nextValue;
-        return nextValue;
-    },
-    /**
-     * Writes one structured metric line for browser-tool observability.
-     */
-    logRunBrowserMetric(options) {
-        console.info('[run_browser][metric]', {
-            tool: 'run_browser',
-            mode: options.mode,
-            sessionId: options.sessionId,
-            event: options.event,
-            ...(options.payload || {}),
-        });
-    },
-};
-
-/**
- * Computes one compact preview of a fallback scrape payload.
- */
-function createContentPreview(content) {
-    const normalized = content.replace(/\s+/g, ' ').trim();
-    if (normalized.length <= 280) {
-        return normalized;
-    }
-    return `${normalized.slice(0, 277)}...`;
-}
-/**
- * Payload and markdown formatters for `run_browser` outcomes.
- *
- * @private function of `run_browser`
- */
-const runBrowserResultFormatting = {
-    /**
-     * Produces one structured payload consumed by chat UI browser replay renderers.
-     */
-    createResultPayload(options) {
-        return {
-            schema: runBrowserConstants.resultSchema,
-            sessionId: options.sessionId,
-            mode: options.mode,
-            modeUsed: options.modeUsed,
-            initialUrl: options.initialUrl,
-            finalUrl: options.finalUrl,
-            finalTitle: options.finalTitle,
-            executedActions: options.executedActions,
-            artifacts: options.artifacts,
-            warning: options.warning,
-            error: options.error,
-            fallback: options.modeUsed === 'fallback' && options.fallbackContent !== null
-                ? {
-                    scraper: 'fetch_url_content',
-                    contentPreview: createContentPreview(options.fallbackContent),
-                }
-                : null,
-            timing: options.timing,
-        };
-    },
-    /**
-     * Produces a model-friendly markdown summary from browser execution artifacts.
-     */
-    formatSuccessResult(options) {
-        const { payload, snapshotPath } = options;
-        return spaceTrim$1((block) => {
-            var _a, _b, _c;
-            return `
-                # Browser run completed
-
-                **Session:** ${payload.sessionId}
-                **Mode requested:** ${runBrowserRuntime.formatExecutionMode(payload.mode)}
-                **Mode used:** ${payload.modeUsed}
-                **Initial URL:** ${payload.initialUrl}
-                **Executed actions:** ${payload.executedActions.length}
-
-                ## Final page
-
-                - URL: ${payload.finalUrl || 'Unknown'}
-                - Title: ${payload.finalTitle || 'Unknown'}
-
-                ## Timings
-
-                - Connect: ${(_a = payload.timing.connectDurationMs) !== null && _a !== void 0 ? _a : 'Unknown'} ms
-                - Initial navigation: ${(_b = payload.timing.initialNavigationDurationMs) !== null && _b !== void 0 ? _b : 'Unknown'} ms
-                - Time to first byte: ${(_c = payload.timing.timeToFirstByteMs) !== null && _c !== void 0 ? _c : 'Unknown'} ms
-                - Total: ${payload.timing.totalDurationMs} ms
-
-                ${payload.artifacts.length === 0
-                ? ''
-                : `
-                        ## Visual replay
-
-                        ${payload.artifacts
-                    .map((artifact, index) => {
-                    const actionPart = artifact.actionSummary ? ` (${artifact.actionSummary})` : '';
-                    return `- ${index + 1}. ${artifact.label}${actionPart}: ${artifact.path}`;
-                })
-                    .join('\n')}
-                    `}
-
-                ${!snapshotPath
-                ? ''
-                : `
-                        ## Final snapshot
-
-                        ${snapshotPath}
-                    `}
-
-                ## Playback payload
-
-                \`\`\`json
-                ${JSON.stringify(payload, null, 2)}
-                \`\`\`
-
-                ${block(payload.executedActions.length === 0
-                ? ''
-                : `
-                        ## Action log
-
-                        ${payload.executedActions
-                    .map((action, index) => `- ${index + 1}. ${JSON.stringify(action)}`)
-                    .join('\n')}
-                    `)}
-
-                Note: Browser page has been automatically closed to free up resources.
-            `;
-        });
-    },
-    /**
-     * Produces a model-friendly markdown payload when fallback scraping is used.
-     */
-    formatFallbackResult(options) {
-        const { payload, fallbackContent, requestedActions } = options;
-        return spaceTrim$1(`
-            # Browser run completed with fallback
-
-            **Session:** ${payload.sessionId}
-            **Mode requested:** ${runBrowserRuntime.formatExecutionMode(payload.mode)}
-            **Mode used:** ${payload.modeUsed}
-            **Initial URL:** ${payload.initialUrl}
-            **Requested actions:** ${requestedActions}
-            **Executed actions:** ${payload.executedActions.length}
-            **Warning:** ${payload.warning || runBrowserConstants.fallbackDynamicContentWarning}
-
-            ## Extracted content
-
-            ${fallbackContent}
-
-            ## Playback payload
-
-            \`\`\`json
-            ${JSON.stringify(payload, null, 2)}
-            \`\`\`
-        `);
-    },
-    /**
-     * Produces a model-friendly markdown error payload from browser execution failures.
-     */
-    formatErrorResult(options) {
-        const { payload } = options;
-        const toolError = payload.error;
-        const suggestedNextSteps = (toolError === null || toolError === void 0 ? void 0 : toolError.suggestedNextSteps) || [];
-        return spaceTrim$1(`
-            # Browser run failed
-
-            **Session:** ${payload.sessionId}
-            **Mode requested:** ${runBrowserRuntime.formatExecutionMode(payload.mode)}
-            **Mode used:** ${payload.modeUsed}
-            **Initial URL:** ${payload.initialUrl}
-            **Error code:** ${(toolError === null || toolError === void 0 ? void 0 : toolError.code) || runBrowserConstants.unknownErrorCode}
-            **Error:** ${(toolError === null || toolError === void 0 ? void 0 : toolError.message) || 'Unknown browser tool error'}
-
-            ${suggestedNextSteps.length === 0
-            ? ''
-            : `
-                    ## Suggested next steps
-
-                    ${suggestedNextSteps.map((step) => `- ${step}`).join('\n')}
-                `}
-
-            ## Playback payload
-
-            \`\`\`json
-            ${JSON.stringify(payload, null, 2)}
-            \`\`\`
-
-            The browser tool could not complete the requested actions.
-        `);
-    },
-};
-
-/**
- * Attempts to locate the specified application on a Linux system using the 'which' command.
- * Returns the path to the executable if found, or null otherwise.
- *
- * @private within the repository
- */
-async function locateAppOnLinux({ linuxWhich, }) {
-    try {
-        const result = await $execCommand({ crashOnError: true, command: `which ${linuxWhich}` });
-        return result.trim();
-    }
-    catch (error) {
-        assertsError(error);
-        return null;
-    }
-}
-/**
- * TODO: [🧠][♿] Maybe export through `@promptbook/node`
- * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
- */
-
-/**
- * Checks if the file is executable
- *
- * @private within the repository
- */
-async function isExecutable(path, fs) {
-    try {
-        await fs.access(path, fs.constants.X_OK);
-        return true;
-    }
-    catch (error) {
-        return false;
-    }
-}
-/**
- * Note: Not [~🟢~] because it is not directly dependent on `fs
- * TODO: [🖇] What about symlinks?
- */
-
-// Note: Module `userhome` has no types available, so it is imported using `require`
-//       @see https://stackoverflow.com/questions/37000981/how-to-import-node-module-in-typescript-without-type-definitions
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const userhome = require('userhome');
-/**
- * Attempts to locate the specified application on a macOS system by checking standard application paths and using mdfind.
- * Returns the path to the executable if found, or null otherwise.
- *
- * @private within the repository
- */
-async function locateAppOnMacOs({ macOsName, }) {
-    try {
-        const toExec = `/Contents/MacOS/${macOsName}`;
-        const regPath = `/Applications/${macOsName}.app` + toExec;
-        const altPath = userhome(regPath.slice(1));
-        if (await isExecutable(regPath, $provideFilesystemForNode())) {
-            return regPath;
-        }
-        else if (await isExecutable(altPath, $provideFilesystemForNode())) {
-            return altPath;
-        }
-        const result = await $execCommand({
-            crashOnError: true,
-            command: `mdfind 'kMDItemDisplayName == "${macOsName}" && kMDItemKind == Application'`,
-        });
-        return result.trim() + toExec;
-    }
-    catch (error) {
-        assertsError(error);
-        return null;
-    }
-}
-/**
- * TODO: [🧠][♿] Maybe export through `@promptbook/node`
- * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
- */
-
-/**
- * Attempts to locate the specified application on a Windows system by searching common installation directories.
- * Returns the path to the executable if found, or null otherwise.
- *
- * @private within the repository
- */
-async function locateAppOnWindows({ appName, windowsSuffix, }) {
-    try {
-        const prefixes = [
-            process.env.LOCALAPPDATA,
-            join(process.env.LOCALAPPDATA || '', 'Programs'),
-            process.env.PROGRAMFILES,
-            process.env['PROGRAMFILES(X86)'],
-        ];
-        for (const prefix of prefixes) {
-            const path = prefix + windowsSuffix;
-            if (await isExecutable(path, $provideFilesystemForNode())) {
-                return path;
-            }
-        }
-        throw new Error(`Can not locate app ${appName} on Windows.`);
-    }
-    catch (error) {
-        assertsError(error);
-        return null;
-    }
-}
-/**
- * TODO: [🧠][♿] Maybe export through `@promptbook/node`
- * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
- */
-
-/**
- * Locates an application on the system
- *
- * @private within the repository
- */
-function locateApp(options) {
-    if (!$isRunningInNode()) {
-        throw new EnvironmentMismatchError('Locating apps works only in Node.js environment');
-    }
-    const { appName, linuxWhich, windowsSuffix, macOsName } = options;
-    if (process.platform === 'win32') {
-        if (windowsSuffix) {
-            return locateAppOnWindows({ appName, windowsSuffix });
-        }
-        else {
-            throw new Error(`${appName} is not available on Windows.`);
-        }
-    }
-    else if (process.platform === 'darwin') {
-        if (macOsName) {
-            return locateAppOnMacOs({ macOsName });
-        }
-        else {
-            throw new Error(`${appName} is not available on macOS.`);
-        }
-    }
-    else {
-        if (linuxWhich) {
-            return locateAppOnLinux({ linuxWhich });
-        }
-        else {
-            throw new Error(`${appName} is not available on Linux.`);
-        }
-    }
-}
-/**
- * TODO: [🧠][♿] Maybe export through `@promptbook/node`
- * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
- */
-
-/**
- * @@@
- *
- * @private within the repository
- */
-function locateChrome() {
-    return locateApp({
-        appName: 'Chrome',
-        linuxWhich: 'google-chrome',
-        windowsSuffix: '\\Google\\Chrome\\Application\\chrome.exe',
-        macOsName: 'Google Chrome',
-    });
-}
-
-/**
- * Creates one standard abort error for cancelled retry loops.
- *
- * @private utility for Agents Server runtime retries
- */
-function createAbortError$1() {
-    const error = new Error('Operation was aborted.');
-    error.name = 'AbortError';
-    return error;
-}
-/**
- * Throws when the supplied signal is already aborted.
- *
- * @private utility for Agents Server runtime retries
- */
-function assertNotAborted(signal) {
-    if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
-        throw createAbortError$1();
-    }
-}
-/**
- * Waits for a duration while respecting cancellation.
- *
- * @private utility for Agents Server runtime retries
- */
-async function sleepWithAbort(delayMs, signal) {
-    if (delayMs <= 0) {
-        assertNotAborted(signal);
-        return;
-    }
-    await new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
-            resolve();
-        }, delayMs);
-        const onAbort = () => {
-            clearTimeout(timeout);
-            signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
-            reject(createAbortError$1());
-        };
-        signal === null || signal === void 0 ? void 0 : signal.addEventListener('abort', onAbort, { once: true });
-    });
-}
-/**
- * Resolves the retry wait duration for one failed attempt.
- *
- * @private utility for Agents Server runtime retries
- */
-function resolveBackoffDelayMs(options) {
-    const exponentialDelay = options.initialDelayMs * Math.pow(options.backoffFactor, Math.max(0, options.attempt - 1));
-    const boundedDelay = Math.min(exponentialDelay, options.maxDelayMs);
-    const jitterDelay = boundedDelay * options.jitterRatio * Math.max(0, options.random());
-    return Math.max(0, Math.round(boundedDelay + jitterDelay));
-}
-/**
- * Retries one async operation with exponential backoff and jitter.
- *
- * @private utility for Agents Server runtime retries
- */
-async function retryWithBackoff(operation, options) {
-    var _a, _b, _c;
-    const startedAt = Date.now();
-    const totalAttempts = Math.max(1, options.retries + 1);
-    const random = (_a = options.random) !== null && _a !== void 0 ? _a : Math.random;
-    const sleep = (_b = options.sleep) !== null && _b !== void 0 ? _b : sleepWithAbort;
-    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
-        assertNotAborted(options.signal);
-        try {
-            const value = await operation(attempt);
-            return {
-                value,
-                attempts: attempt,
-                durationMs: Date.now() - startedAt,
-            };
-        }
-        catch (error) {
-            const isLastAttempt = attempt >= totalAttempts;
-            const isRetryable = options.shouldRetry ? options.shouldRetry(error, attempt) : true;
-            if (isLastAttempt || !isRetryable) {
-                throw error;
-            }
-            const delayMs = resolveBackoffDelayMs({
-                attempt,
-                initialDelayMs: options.initialDelayMs,
-                maxDelayMs: options.maxDelayMs,
-                backoffFactor: options.backoffFactor,
-                jitterRatio: options.jitterRatio,
-                random,
-            });
-            (_c = options.onRetry) === null || _c === void 0 ? void 0 : _c.call(options, {
-                attempt,
-                retries: options.retries,
-                delayMs,
-                error,
-            });
-            await sleep(delayMs, options.signal);
-        }
-    }
-    throw new Error('Retry loop exited unexpectedly.');
-}
-
-const DEFAULT_BROWSER_USER_DATA_DIR = join(tmpdir(), 'promptbook', 'browser', 'user-data');
-/**
- * Default remote browser connect timeout in milliseconds.
- */
-const DEFAULT_REMOTE_CONNECT_TIMEOUT_MS = 10000;
-/**
- * Default retry count for remote browser connection establishment.
- */
-const DEFAULT_REMOTE_CONNECT_RETRIES = 2;
-/**
- * Default initial retry delay for remote browser connection.
- */
-const DEFAULT_REMOTE_CONNECT_BACKOFF_INITIAL_MS = 250;
-/**
- * Default maximum retry delay for remote browser connection.
- */
-const DEFAULT_REMOTE_CONNECT_BACKOFF_MAX_MS = 1000;
-/**
- * Default exponential multiplier for remote browser retry delay.
- */
-const DEFAULT_REMOTE_CONNECT_BACKOFF_FACTOR = 4;
-/**
- * Default retry jitter ratio for remote browser connection.
- */
-const DEFAULT_REMOTE_CONNECT_JITTER_RATIO = 0.2;
-/**
- * In-memory metrics counters for remote browser connect attempts.
- */
-const REMOTE_BROWSER_CONNECT_METRICS = {
-    success: 0,
-    failure: 0,
-};
-/**
- * Reads a positive integer from environment variables with a fallback default.
- */
-function resolvePositiveIntFromEnv(variableName, defaultValue) {
-    const rawValue = process.env[variableName];
-    if (!rawValue || !rawValue.trim()) {
-        return defaultValue;
-    }
-    const parsed = Number.parseInt(rawValue.trim(), 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        return defaultValue;
-    }
-    return parsed;
-}
-/**
- * Reads a positive number from environment variables with a fallback default.
- */
-function resolvePositiveNumberFromEnv(variableName, defaultValue) {
-    const rawValue = process.env[variableName];
-    if (!rawValue || !rawValue.trim()) {
-        return defaultValue;
-    }
-    const parsed = Number.parseFloat(rawValue.trim());
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        return defaultValue;
-    }
-    return parsed;
-}
-/**
- * Reads a non-negative integer from environment variables with a fallback default.
- */
-function resolveNonNegativeIntFromEnv(variableName, defaultValue) {
-    const rawValue = process.env[variableName];
-    if (!rawValue || !rawValue.trim()) {
-        return defaultValue;
-    }
-    const parsed = Number.parseInt(rawValue.trim(), 10);
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        return defaultValue;
-    }
-    return parsed;
-}
-/**
- * Reads a non-negative number from environment variables with a fallback default.
- */
-function resolveNonNegativeNumberFromEnv(variableName, defaultValue) {
-    const rawValue = process.env[variableName];
-    if (!rawValue || !rawValue.trim()) {
-        return defaultValue;
-    }
-    const parsed = Number.parseFloat(rawValue.trim());
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        return defaultValue;
-    }
-    return parsed;
-}
-/**
- * Creates one standard abort error.
- */
-function createAbortError() {
-    const error = new Error('Browser connection request was aborted.');
-    error.name = 'AbortError';
-    return error;
-}
-/**
- * Provides browser context instances with support for both local and remote browser connections.
- *
- * This provider manages browser lifecycle and supports:
- * - Local mode: Launches a persistent Chromium context on the same machine
- * - Remote mode: Connects to a remote Playwright browser via WebSocket
- *
- * The remote mode is useful for environments like Vercel where running a full browser
- * is not possible due to resource constraints.
- *
- * @private internal utility for Agents Server browser tools
- */
-class BrowserConnectionProvider {
-    /**
-     * Creates a new BrowserConnectionProvider.
-     *
-     * @param options - Provider options
-     * @param options.isVerbose - Enable verbose logging
-     */
-    constructor(options = {}) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
-        this.browserContext = null;
-        this.connectionMode = null;
-        this.isVerbose = (_a = options.isVerbose) !== null && _a !== void 0 ? _a : false;
-        this.remoteConnectTimeoutMs =
-            (_b = options.remoteConnectTimeoutMs) !== null && _b !== void 0 ? _b : resolvePositiveIntFromEnv('RUN_BROWSER_CONNECT_TIMEOUT_MS', DEFAULT_REMOTE_CONNECT_TIMEOUT_MS);
-        this.remoteConnectRetries =
-            (_c = options.remoteConnectRetries) !== null && _c !== void 0 ? _c : resolveNonNegativeIntFromEnv('RUN_BROWSER_CONNECT_RETRIES', DEFAULT_REMOTE_CONNECT_RETRIES);
-        this.remoteConnectBackoffInitialMs =
-            (_d = options.remoteConnectBackoffInitialMs) !== null && _d !== void 0 ? _d : resolvePositiveIntFromEnv('RUN_BROWSER_CONNECT_BACKOFF_INITIAL_MS', DEFAULT_REMOTE_CONNECT_BACKOFF_INITIAL_MS);
-        this.remoteConnectBackoffMaxMs =
-            (_e = options.remoteConnectBackoffMaxMs) !== null && _e !== void 0 ? _e : resolvePositiveIntFromEnv('RUN_BROWSER_CONNECT_BACKOFF_MAX_MS', DEFAULT_REMOTE_CONNECT_BACKOFF_MAX_MS);
-        this.remoteConnectBackoffFactor =
-            (_f = options.remoteConnectBackoffFactor) !== null && _f !== void 0 ? _f : resolvePositiveNumberFromEnv('RUN_BROWSER_CONNECT_BACKOFF_FACTOR', DEFAULT_REMOTE_CONNECT_BACKOFF_FACTOR);
-        this.remoteConnectJitterRatio =
-            (_g = options.remoteConnectJitterRatio) !== null && _g !== void 0 ? _g : resolveNonNegativeNumberFromEnv('RUN_BROWSER_CONNECT_JITTER_RATIO', DEFAULT_REMOTE_CONNECT_JITTER_RATIO);
-        this.random = (_h = options.random) !== null && _h !== void 0 ? _h : Math.random;
-        this.sleep = options.sleep;
-    }
-    /**
-     * Gets a browser context, creating a new one if needed.
-     *
-     * This method automatically determines whether to use local or remote browser
-     * based on the REMOTE_BROWSER_URL environment variable.
-     *
-     * @returns Browser context instance
-     */
-    async getBrowserContext(options = {}) {
-        var _a;
-        if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
-            throw createAbortError();
-        }
-        // Check if we have a cached connection that's still valid
-        if (this.browserContext !== null && this.isBrowserContextAlive(this.browserContext)) {
-            return this.browserContext;
-        }
-        // Determine connection mode from configuration
-        const mode = this.resolveConnectionMode();
-        this.connectionMode = mode;
-        if (this.isVerbose) {
-            console.info('[BrowserConnectionProvider] Creating new browser context', {
-                mode: mode.type,
-                wsEndpoint: mode.type === 'remote' ? mode.wsEndpoint : undefined,
-            });
-        }
-        // Create new browser context based on mode
-        if (mode.type === 'local') {
-            this.browserContext = await this.createLocalBrowserContext();
-        }
-        else {
-            this.browserContext = await this.createRemoteBrowserContext(mode.wsEndpoint, options);
-        }
-        return this.browserContext;
-    }
-    /**
-     * Closes all pages in the current browser context.
-     *
-     * This method is useful for cleanup between agent tasks without closing
-     * the entire browser instance.
-     */
-    async closeAllPages() {
-        if (!this.browserContext) {
-            return;
-        }
-        try {
-            const pages = this.browserContext.pages();
-            if (this.isVerbose) {
-                console.info('[BrowserConnectionProvider] Closing all pages', {
-                    pageCount: pages.length,
-                });
-            }
-            await Promise.all(pages.map((page) => page.close().catch((error) => {
-                console.error('[BrowserConnectionProvider] Failed to close page', { error });
-            })));
-        }
-        catch (error) {
-            console.error('[BrowserConnectionProvider] Error closing pages', { error });
-        }
-    }
-    /**
-     * Closes the browser context and disconnects from the browser.
-     *
-     * This should be called when the browser is no longer needed to free up resources.
-     * For local mode, this closes the browser process. For remote mode, it disconnects
-     * from the remote browser but doesn't shut down the remote server.
-     */
-    async close() {
-        var _a;
-        if (!this.browserContext) {
-            return;
-        }
-        try {
-            if (this.isVerbose) {
-                console.info('[BrowserConnectionProvider] Closing browser context', {
-                    mode: (_a = this.connectionMode) === null || _a === void 0 ? void 0 : _a.type,
-                });
-            }
-            await this.browserContext.close();
-            this.browserContext = null;
-            this.connectionMode = null;
-        }
-        catch (error) {
-            console.error('[BrowserConnectionProvider] Error closing browser context', { error });
-            // Reset state even if close fails
-            this.browserContext = null;
-            this.connectionMode = null;
-        }
-    }
-    /**
-     * Checks if a browser context is still alive and connected.
-     *
-     * @param context - Browser context to check
-     * @returns True if the context is connected and usable
-     */
-    isBrowserContextAlive(context) {
-        try {
-            const browser = context.browser();
-            return browser !== null && browser.isConnected();
-        }
-        catch (_a) {
-            return false;
-        }
-    }
-    /**
-     * Determines whether to use local or remote browser based on configuration.
-     *
-     * @returns Connection mode configuration
-     */
-    resolveConnectionMode() {
-        const remoteBrowserUrl = REMOTE_BROWSER_URL;
-        if (remoteBrowserUrl && remoteBrowserUrl.trim().length > 0) {
-            return {
-                type: 'remote',
-                wsEndpoint: remoteBrowserUrl.trim(),
-            };
-        }
-        return { type: 'local' };
-    }
-    /**
-     * Creates a local browser context using persistent Chromium.
-     *
-     * @returns Local browser context
-     */
-    async createLocalBrowserContext() {
-        if (this.isVerbose) {
-            console.info('[BrowserConnectionProvider] Launching local browser context');
-        }
-        const userDataDir = join(DEFAULT_BROWSER_USER_DATA_DIR, 'run-browser');
-        await mkdir(userDataDir, { recursive: true });
-        const launchOptions = {
-            headless: false,
-            args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
-        };
-        try {
-            const chromePath = await locateChrome();
-            launchOptions.executablePath = chromePath;
-        }
-        catch (error) {
-            if (this.isVerbose) {
-                console.warn('[BrowserConnectionProvider] Could not locate system Chrome; using Playwright bundled Chromium', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-        return await chromium.launchPersistentContext(userDataDir, launchOptions);
-    }
-    /**
-     * Creates a remote browser context by connecting to a Playwright server.
-     *
-     * @param wsEndpoint - WebSocket endpoint of the remote Playwright server
-     * @returns Remote browser context
-     */
-    async createRemoteBrowserContext(wsEndpoint, options) {
-        const endpointDebug = sanitizeRemoteBrowserEndpoint(wsEndpoint);
-        const startedAt = Date.now();
-        if (this.isVerbose) {
-            console.info('[BrowserConnectionProvider] Connecting to remote browser', {
-                endpoint: endpointDebug,
-                connectTimeoutMs: this.remoteConnectTimeoutMs,
-                retries: this.remoteConnectRetries,
-            });
-        }
-        let attempts = 0;
-        try {
-            const connectResult = await retryWithBackoff(async (attempt) => {
-                attempts = attempt;
-                return await chromium.connect(wsEndpoint, {
-                    timeout: this.remoteConnectTimeoutMs,
-                });
-            }, {
-                retries: this.remoteConnectRetries,
-                initialDelayMs: this.remoteConnectBackoffInitialMs,
-                maxDelayMs: this.remoteConnectBackoffMaxMs,
-                backoffFactor: this.remoteConnectBackoffFactor,
-                jitterRatio: this.remoteConnectJitterRatio,
-                signal: options.signal,
-                shouldRetry: (error) => isRemoteBrowserInfrastructureError(error),
-                onRetry: ({ attempt, delayMs, error }) => {
-                    console.warn('[run_browser][retry]', {
-                        tool: 'run_browser',
-                        mode: 'remote-browser',
-                        sessionId: options.sessionId || null,
-                        event: 'remote_browser_connect_retry',
-                        attempt,
-                        delayMs,
-                        endpoint: endpointDebug,
-                        errorCode: extractNetworkErrorCode(error),
-                        error: getErrorMessage(error),
-                    });
-                },
-                random: this.random,
-                sleep: this.sleep,
-            });
-            const browser = connectResult.value;
-            // For remote connections, we need to create a new context
-            // Note: Remote browsers don't support persistent contexts
-            const context = await browser.newContext();
-            REMOTE_BROWSER_CONNECT_METRICS.success++;
-            console.info('[run_browser][metric]', {
-                tool: 'run_browser',
-                mode: 'remote-browser',
-                sessionId: options.sessionId || null,
-                event: 'remote_browser_connect_success',
-                attempts: connectResult.attempts,
-                connectDurationMs: connectResult.durationMs,
-                endpoint: endpointDebug,
-                counter: REMOTE_BROWSER_CONNECT_METRICS.success,
-            });
-            if (this.isVerbose) {
-                console.info('[BrowserConnectionProvider] Successfully connected to remote browser');
-            }
-            return context;
-        }
-        catch (error) {
-            REMOTE_BROWSER_CONNECT_METRICS.failure++;
-            const durationMs = Date.now() - startedAt;
-            const remoteInfraUnavailable = isRemoteBrowserInfrastructureError(error);
-            if (remoteInfraUnavailable) {
-                const remoteBrowserUnavailableError = new RemoteBrowserUnavailableError({
-                    message: `Remote browser is unavailable. Could not establish a websocket connection.`,
-                    debug: {
-                        endpoint: endpointDebug,
-                        attempts: Math.max(1, attempts),
-                        connectTimeoutMs: this.remoteConnectTimeoutMs,
-                        durationMs,
-                        networkErrorCode: extractNetworkErrorCode(error),
-                        originalMessage: getErrorMessage(error),
-                    },
-                    cause: error,
-                });
-                console.warn('[run_browser][metric]', {
-                    tool: 'run_browser',
-                    mode: 'remote-browser',
-                    sessionId: options.sessionId || null,
-                    event: 'remote_browser_connect_failure',
-                    errorCode: remoteBrowserUnavailableError.code,
-                    attempts: Math.max(1, attempts),
-                    connectDurationMs: durationMs,
-                    endpoint: endpointDebug,
-                    counter: REMOTE_BROWSER_CONNECT_METRICS.failure,
-                });
-                throw remoteBrowserUnavailableError;
-            }
-            console.error('[run_browser][metric]', {
-                tool: 'run_browser',
-                mode: 'remote-browser',
-                sessionId: options.sessionId || null,
-                event: 'remote_browser_connect_failure',
-                errorCode: 'REMOTE_BROWSER_CONNECT_ERROR',
-                attempts: Math.max(1, attempts),
-                connectDurationMs: durationMs,
-                endpoint: endpointDebug,
-                error: getErrorMessage(error),
-                counter: REMOTE_BROWSER_CONNECT_METRICS.failure,
-            });
-            throw error;
-        }
-    }
-}
-
-/**
- * Singleton instance of the browser connection provider.
- *
- * @private internal cache for `$provideBrowserForServer`
- */
-let browserProvider = null;
-/**
- * Provides a browser context for server-side operations, with caching to reuse instances.
- *
- * This function supports both local and remote browser connections based on environment configuration.
- * Use REMOTE_BROWSER_URL environment variable to configure a remote Playwright server.
- *
- * @param options - Optional runtime request options used for cancellation and logging context.
- * @returns Browser context instance
- */
-async function $provideBrowserForServer(options = {}) {
-    if (browserProvider === null) {
-        browserProvider = new BrowserConnectionProvider({ isVerbose: false });
-    }
-    return await browserProvider.getBrowserContext(options);
-}
-/**
- * TODO: [🏓] Unite `xxxForServer` and `xxxForNode` naming
- */
-
-/**
- * Attempts to compute time-to-first-byte from Playwright response timing.
- */
-function resolveTimeToFirstByteMs(response) {
-    if (!response) {
-        return null;
-    }
-    try {
-        const timing = response.request().timing();
-        if (typeof (timing === null || timing === void 0 ? void 0 : timing.responseStart) === 'number' &&
-            typeof (timing === null || timing === void 0 ? void 0 : timing.startTime) === 'number' &&
-            timing.responseStart >= timing.startTime) {
-            return Math.round(timing.responseStart - timing.startTime);
-        }
-    }
-    catch (_a) {
-        return null;
-    }
-    return null;
-}
-/**
- * Page open, action normalization and action execution helpers for `run_browser`.
- *
- * @private function of `run_browser`
- */
-const runBrowserWorkflow = {
-    /**
-     * Opens a new browser page and navigates to the requested URL.
-     */
-    async openPageWithUrl(options) {
-        runBrowserErrorHandling.assertNotAborted(options.signal, options.sessionId);
-        const connectStartedAt = Date.now();
-        const browserContext = await $provideBrowserForServer({
-            signal: options.signal,
-            sessionId: options.sessionId,
-        });
-        const connectDurationMs = Date.now() - connectStartedAt;
-        const page = await browserContext.newPage();
-        page.setDefaultNavigationTimeout(options.timeouts.navigationTimeoutMs);
-        page.setDefaultTimeout(options.timeouts.actionTimeoutMs);
-        const navigationStartedAt = Date.now();
-        try {
-            const navigationResponse = await page.goto(options.url, {
-                waitUntil: 'domcontentloaded',
-                timeout: options.timeouts.navigationTimeoutMs,
-            });
-            return {
-                page,
-                connectDurationMs,
-                initialNavigationDurationMs: Date.now() - navigationStartedAt,
-                timeToFirstByteMs: resolveTimeToFirstByteMs(navigationResponse),
-            };
-        }
-        catch (error) {
-            throw runBrowserErrorHandling.createRunBrowserNavigationError({
-                message: `Failed to navigate to \`${options.url}\`.`,
-                debug: {
-                    phase: 'initial-navigation',
-                    url: options.url,
-                    navigationTimeoutMs: options.timeouts.navigationTimeoutMs,
-                },
-                cause: error,
-            });
-        }
-    },
-    /**
-     * Validates and normalizes browser actions received from the model.
-     */
-    normalizeActions(actions) {
-        if (!actions || actions.length === 0) {
-            return [];
-        }
-        return actions.map((action, index) => this.normalizeAction(action, index));
-    },
-    /**
-     * Validates and normalizes a single action.
-     */
-    normalizeAction(action, index) {
-        var _a, _b, _c;
-        switch (action.type) {
-            case 'navigate': {
-                const url = String(action.value || '').trim();
-                if (!url) {
-                    throw runBrowserErrorHandling.createRunBrowserValidationError({
-                        message: spaceTrim$1(`Action ${index + 1}: \`navigate\` requires non-empty \`value\` URL.`),
-                        debug: {
-                            actionIndex: index + 1,
-                            actionType: action.type,
-                        },
-                    });
-                }
-                return { type: 'navigate', url };
-            }
-            case 'click': {
-                const selector = String(action.selector || '').trim();
-                if (!selector) {
-                    throw runBrowserErrorHandling.createRunBrowserValidationError({
-                        message: spaceTrim$1(`Action ${index + 1}: \`click\` requires non-empty \`selector\`.`),
-                        debug: {
-                            actionIndex: index + 1,
-                            actionType: action.type,
-                        },
-                    });
-                }
-                return { type: 'click', selector };
-            }
-            case 'type': {
-                const selector = String(action.selector || '').trim();
-                if (!selector) {
-                    throw runBrowserErrorHandling.createRunBrowserValidationError({
-                        message: spaceTrim$1(`Action ${index + 1}: \`type\` requires non-empty \`selector\`.`),
-                        debug: {
-                            actionIndex: index + 1,
-                            actionType: action.type,
-                        },
-                    });
-                }
-                const text = String((_a = action.value) !== null && _a !== void 0 ? _a : '');
-                return { type: 'type', selector, text };
-            }
-            case 'wait': {
-                const requestedValue = Number.parseInt(String((_b = action.value) !== null && _b !== void 0 ? _b : runBrowserConstants.defaultWaitMs), 10);
-                const milliseconds = Number.isFinite(requestedValue)
-                    ? Math.min(Math.max(requestedValue, 1), runBrowserConstants.maxWaitMs)
-                    : runBrowserConstants.defaultWaitMs;
-                return { type: 'wait', milliseconds };
-            }
-            case 'scroll': {
-                const requestedValue = Number.parseInt(String((_c = action.value) !== null && _c !== void 0 ? _c : runBrowserConstants.defaultScrollPixels), 10);
-                const pixels = Number.isFinite(requestedValue) ? requestedValue : runBrowserConstants.defaultScrollPixels;
-                const rawSelector = String(action.selector || '').trim();
-                return { type: 'scroll', selector: rawSelector || null, pixels };
-            }
-        }
-    },
-    /**
-     * Executes one normalized browser action on a Playwright page.
-     */
-    async executeAction(options) {
-        const { page, action, actionIndex, timeouts, signal } = options;
-        runBrowserErrorHandling.assertNotAborted(signal, `action-${actionIndex}`);
-        try {
-            switch (action.type) {
-                case 'navigate':
-                    await page.goto(action.url, {
-                        waitUntil: 'domcontentloaded',
-                        timeout: timeouts.navigationTimeoutMs,
-                    });
-                    return;
-                case 'click':
-                    await page.locator(action.selector).first().click({ timeout: timeouts.actionTimeoutMs });
-                    return;
-                case 'type':
-                    await page.locator(action.selector).first().fill(action.text, { timeout: timeouts.actionTimeoutMs });
-                    return;
-                case 'wait':
-                    if (action.milliseconds > timeouts.actionTimeoutMs) {
-                        throw runBrowserErrorHandling.createRunBrowserActionError({
-                            message: `Action ${actionIndex}: \`wait\` exceeds action timeout (${timeouts.actionTimeoutMs}ms).`,
-                            debug: {
-                                actionIndex,
-                                action,
-                                actionTimeoutMs: timeouts.actionTimeoutMs,
-                            },
-                        });
-                    }
-                    await page.waitForTimeout(action.milliseconds);
-                    return;
-                case 'scroll':
-                    if (action.selector) {
-                        await page
-                            .locator(action.selector)
-                            .first()
-                            .scrollIntoViewIfNeeded({ timeout: timeouts.actionTimeoutMs });
-                    }
-                    await page.mouse.wheel(0, action.pixels);
-                    return;
-            }
-        }
-        catch (error) {
-            if (runBrowserErrorHandling.isTaggedRunBrowserError(error)) {
-                throw error;
-            }
-            if (action.type === 'navigate') {
-                throw runBrowserErrorHandling.createRunBrowserNavigationError({
-                    message: `Action ${actionIndex}: failed to navigate to \`${action.url}\`.`,
-                    debug: {
-                        actionIndex,
-                        action,
-                        navigationTimeoutMs: timeouts.navigationTimeoutMs,
-                    },
-                    cause: error,
-                });
-            }
-            throw runBrowserErrorHandling.createRunBrowserActionError({
-                message: `Action ${actionIndex}: failed to execute \`${action.type}\`.`,
-                debug: {
-                    actionIndex,
-                    action,
-                    actionTimeoutMs: timeouts.actionTimeoutMs,
-                },
-                cause: error,
-            });
-        }
-    },
-};
-
-/**
- * Summarizes one normalized browser action in user-facing language.
- */
-function formatRunBrowserActionSummary(action) {
-    switch (action.type) {
-        case 'navigate':
-            return `Navigate to ${action.url}`;
-        case 'click':
-            return `Click ${action.selector}`;
-        case 'type':
-            return `Type into ${action.selector}`;
-        case 'wait':
-            return `Wait ${action.milliseconds}ms`;
-        case 'scroll':
-            return action.selector ? `Scroll ${action.pixels}px in ${action.selector}` : `Scroll ${action.pixels}px on page`;
-    }
-}
-/**
- * Emits one incremental browser-tool update when a hidden chat-progress listener is attached.
- */
-function emitRunBrowserProgress(args, update) {
-    emitToolCallProgressFromToolArgs(args, update);
-}
-/**
- * Returns the current timestamp in the branded ISO-8601 format used by tool-call logs.
- */
-function createRunBrowserLogTimestamp() {
-    return new Date().toISOString();
-}
-/**
- * Executes non-graphical fallback scraping.
- */
-async function runFallbackScrape(url) {
-    return await fetchUrlContent(url);
-}
-/**
- * Runs interactive browser automation through Playwright.
- *
- * @param args Tool arguments provided by the model.
- * @param internalOptions Optional runtime options for cancellation.
- * @returns Markdown summary with structured playback payload.
- */
-async function run_browser(args, internalOptions = {}) {
-    runBrowserObservability.incrementTotalRuns();
-    const startedAt = Date.now();
-    const sessionId = runBrowserRuntime.createRunBrowserSessionId();
-    const initialUrl = String(args.url || '').trim();
-    const mode = runBrowserRuntime.resolveExecutionMode();
-    const timeoutConfiguration = runBrowserRuntime.resolveTimeoutConfiguration(args.timeouts);
-    let page = null;
-    let connectDurationMs = null;
-    let initialNavigationDurationMs = null;
-    let timeToFirstByteMs = null;
-    try {
-        if (!initialUrl) {
-            throw runBrowserErrorHandling.createRunBrowserValidationError({
-                message: 'Missing required `url` argument.',
-                debug: {
-                    field: 'url',
-                },
-            });
-        }
-        const normalizedActions = runBrowserWorkflow.normalizeActions(args.actions);
-        runBrowserErrorHandling.assertNotAborted(internalOptions.signal, sessionId);
-        const openedPage = await runBrowserWorkflow.openPageWithUrl({
-            url: initialUrl,
-            sessionId,
-            timeouts: timeoutConfiguration,
-            signal: internalOptions.signal,
-        });
-        page = openedPage.page;
-        connectDurationMs = openedPage.connectDurationMs;
-        initialNavigationDurationMs = openedPage.initialNavigationDurationMs;
-        timeToFirstByteMs = openedPage.timeToFirstByteMs;
-        emitRunBrowserProgress(args, {
-            state: 'PARTIAL',
-            log: {
-                createdAt: createRunBrowserLogTimestamp(),
-                kind: 'browser-session',
-                title: 'Browser ready',
-                message: 'Opened the initial page and started the browser session.',
-                payload: {
-                    sessionId,
-                    initialUrl,
-                    connectDurationMs,
-                    initialNavigationDurationMs,
-                    timeToFirstByteMs,
-                },
-            },
-        });
-        const artifacts = [];
-        const initialArtifact = await runBrowserArtifacts.captureSnapshotArtifact({
-            page,
-            sessionId,
-            label: 'Initial page',
-            fileSuffix: 'initial',
-        });
-        if (initialArtifact) {
-            artifacts.push(initialArtifact);
-        }
-        for (const [index, action] of normalizedActions.entries()) {
-            runBrowserErrorHandling.assertNotAborted(internalOptions.signal, sessionId);
-            emitRunBrowserProgress(args, {
-                state: 'PARTIAL',
-                log: {
-                    createdAt: createRunBrowserLogTimestamp(),
-                    kind: 'browser-action',
-                    title: `Action ${index + 1} running`,
-                    message: formatRunBrowserActionSummary(action),
-                    payload: {
-                        actionIndex: index + 1,
-                        action,
-                        phase: 'running',
-                    },
-                },
-            });
-            await runBrowserWorkflow.executeAction({
-                page,
-                action,
-                actionIndex: index + 1,
-                timeouts: timeoutConfiguration,
-                signal: internalOptions.signal,
-            });
-            emitRunBrowserProgress(args, {
-                state: 'PARTIAL',
-                log: {
-                    createdAt: createRunBrowserLogTimestamp(),
-                    kind: 'browser-action',
-                    title: `Action ${index + 1} finished`,
-                    message: formatRunBrowserActionSummary(action),
-                    payload: {
-                        actionIndex: index + 1,
-                        action,
-                        phase: 'complete',
-                    },
-                },
-            });
-            const actionArtifact = await runBrowserArtifacts.captureSnapshotArtifact({
-                page,
-                sessionId,
-                label: `After action ${index + 1}`,
-                fileSuffix: `action-${String(index + 1).padStart(3, '0')}-${action.type}`,
-                actionIndex: index + 1,
-                action,
-            });
-            if (actionArtifact) {
-                artifacts.push(actionArtifact);
-            }
-        }
-        const snapshotPath = await runBrowserArtifacts.captureSnapshot(page, sessionId);
-        const finalUrl = page.url();
-        const finalTitle = await runBrowserArtifacts.getPageTitle(page);
-        if (snapshotPath) {
-            artifacts.push({
-                kind: 'screenshot',
-                label: 'Final page',
-                path: snapshotPath,
-                capturedAt: new Date().toISOString(),
-                url: finalUrl,
-                title: finalTitle,
-            });
-        }
-        const payload = runBrowserResultFormatting.createResultPayload({
-            sessionId,
-            mode,
-            modeUsed: 'remote-browser',
-            initialUrl,
-            finalUrl,
-            finalTitle,
-            executedActions: normalizedActions,
-            artifacts,
-            warning: null,
-            error: null,
-            fallbackContent: null,
-            timing: {
-                connectDurationMs,
-                initialNavigationDurationMs,
-                timeToFirstByteMs,
-                totalDurationMs: Date.now() - startedAt,
-            },
-        });
-        runBrowserObservability.logRunBrowserMetric({
-            event: 'run_browser_success',
-            sessionId,
-            mode: 'remote-browser',
-            payload: {
-                actions: normalizedActions.length,
-                connectDurationMs,
-                initialNavigationDurationMs,
-                timeToFirstByteMs,
-            },
-        });
-        return runBrowserResultFormatting.formatSuccessResult({
-            payload,
-            snapshotPath,
-        });
-    }
-    catch (error) {
-        const toolError = runBrowserErrorHandling.classifyRunBrowserToolError({
-            error,
-            sessionId,
-            mode,
-        });
-        const errorCodeCount = runBrowserObservability.incrementRunBrowserErrorCodeCounter(toolError.code);
-        if (runBrowserErrorHandling.isRemoteBrowserUnavailableCode(toolError.code) && initialUrl) {
-            const fallbackContent = await runFallbackScrape(initialUrl);
-            const { fallbackRuns, fallbackRate } = runBrowserObservability.incrementFallbackRunsAndGetMetrics();
-            emitRunBrowserProgress(args, {
-                state: 'PARTIAL',
-                log: {
-                    createdAt: createRunBrowserLogTimestamp(),
-                    kind: 'warning',
-                    level: 'warning',
-                    title: 'Fallback enabled',
-                    message: 'Remote browser was unavailable, so fallback scraping was used instead.',
-                    payload: {
-                        errorCode: toolError.code,
-                        initialUrl,
-                    },
-                },
-            });
-            const payload = runBrowserResultFormatting.createResultPayload({
-                sessionId,
-                mode,
-                modeUsed: 'fallback',
-                initialUrl,
-                finalUrl: null,
-                finalTitle: null,
-                executedActions: [],
-                artifacts: [],
-                warning: runBrowserConstants.fallbackDynamicContentWarning,
-                error: toolError,
-                fallbackContent,
-                timing: {
-                    connectDurationMs,
-                    initialNavigationDurationMs,
-                    timeToFirstByteMs,
-                    totalDurationMs: Date.now() - startedAt,
-                },
-            });
-            runBrowserObservability.logRunBrowserMetric({
-                event: 'run_browser_fallback_used',
-                sessionId,
-                mode: 'fallback',
-                payload: {
-                    errorCode: toolError.code,
-                    errorCodeCount,
-                    fallbackRuns,
-                    totalRuns: runBrowserObservability.getTotalRuns(),
-                    fallbackRate,
-                },
-            });
-            return runBrowserResultFormatting.formatFallbackResult({
-                payload,
-                fallbackContent,
-                requestedActions: Array.isArray(args.actions) ? args.actions.length : 0,
-            });
-        }
-        emitRunBrowserProgress(args, {
-            state: 'ERROR',
-            log: {
-                createdAt: createRunBrowserLogTimestamp(),
-                kind: 'error',
-                level: 'error',
-                title: 'Browser run failed',
-                message: toolError.message,
-                payload: {
-                    code: toolError.code,
-                    debug: toolError.debug,
-                },
-            },
-        });
-        const payload = runBrowserResultFormatting.createResultPayload({
-            sessionId,
-            mode,
-            modeUsed: 'remote-browser',
-            initialUrl,
-            finalUrl: page ? page.url() : null,
-            finalTitle: page ? await runBrowserArtifacts.getPageTitle(page) : null,
-            executedActions: [],
-            artifacts: [],
-            warning: null,
-            error: toolError,
-            fallbackContent: null,
-            timing: {
-                connectDurationMs,
-                initialNavigationDurationMs,
-                timeToFirstByteMs,
-                totalDurationMs: Date.now() - startedAt,
-            },
-        });
-        runBrowserObservability.logRunBrowserMetric({
-            event: 'run_browser_failed',
-            sessionId,
-            mode: 'remote-browser',
-            payload: {
-                errorCode: toolError.code,
-                errorCodeCount,
-                connectDurationMs,
-                initialNavigationDurationMs,
-                timeToFirstByteMs,
-            },
-        });
-        return runBrowserResultFormatting.formatErrorResult({
-            payload,
-        });
-    }
-    finally {
-        await runBrowserArtifacts.cleanupPage(page, sessionId);
-    }
-}
-
-/**
- * Resolves the server-side implementation of the `run_browser` tool for Node.js environments.
- *
- * This uses lazy `require` to keep the core package decoupled from Agents Server internals.
- * When the server tool cannot be resolved, the fallback implementation throws a helpful error.
- *
- * @private internal utility for USE BROWSER commitment
- */
-function resolveRunBrowserToolForNode() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        // const { run_browser } = require('../../../apps/agents-server/src/tools/run_browser');
-        if (typeof run_browser !== 'function') {
-            throw new Error('run_browser value is not a function but ' + typeof run_browser);
-        }
-        return run_browser;
-    }
-    catch (error) {
-        assertsError(error);
-        return async () => {
-            throw new EnvironmentMismatchError(spaceTrim$1((block) => `
-                        \`run_browser\` tool is not available in this environment.
-                        This commitment requires the Agents Server browser runtime with Playwright CLI.
-
-                        ${error.name}:
-                        ${block(error.message)}
-                    `));
-        };
-    }
-}
-
-/**
- * Resolves the server-side implementation of the send_email tool for Node.js environments.
- *
- * This uses a lazy require so the core package can still load even if the Agents Server
- * module is unavailable. When the server tool cannot be resolved, a fallback implementation
- * throws a helpful error message.
- *
- * @private internal utility for USE EMAIL commitment
- */
-function resolveSendEmailToolForNode() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { send_email } = require('../../../apps/agents-server/src/tools/send_email');
-        if (typeof send_email !== 'function') {
-            throw new Error('send_email value is not a function but ' + typeof send_email);
-        }
-        return send_email;
-    }
-    catch (error) {
-        const normalizedError = error instanceof Error
-            ? error
-            : new Error(typeof error === 'string' ? error : JSON.stringify(error !== null && error !== void 0 ? error : 'Unknown error'));
-        return async () => {
-            throw new EnvironmentMismatchError(spaceTrim$1((block) => `
-                        \`send_email\` tool is not available in this environment.
-                        This commitment requires Agents Server runtime with wallet-backed SMTP sending.
-
-                        ${normalizedError.name}:
-                        ${block(normalizedError.message)}
-                    `));
-        };
-    }
-}
-
-/**
- * Resolves the server-side `spawn_agent` tool for Node.js runtimes.
- *
- * Uses lazy require so core package can load outside Agents Server.
- *
- * @private internal utility for USE SPAWN commitment
- */
-function resolveSpawnAgentToolForNode() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { spawn_agent } = require('../../../apps/agents-server/src/tools/spawn_agent');
-        if (typeof spawn_agent !== 'function') {
-            throw new Error('spawn_agent value is not a function but ' + typeof spawn_agent);
-        }
-        return spawn_agent;
-    }
-    catch (error) {
-        const normalizedError = error instanceof Error
-            ? error
-            : new Error(typeof error === 'string' ? error : JSON.stringify(error !== null && error !== void 0 ? error : 'Unknown error'));
-        return async () => {
-            throw new EnvironmentMismatchError(spaceTrim$1((block) => `
-                        \`spawn_agent\` tool is not available in this environment.
-                        This commitment requires Agents Server runtime with agent persistence enabled.
-
-                        ${normalizedError.name}:
-                        ${block(normalizedError.message)}
-                    `));
-        };
-    }
-}
-
-/**
- * Collects tool functions from all commitment definitions.
- *
- * @returns Map of tool function implementations.
- * @private internal helper for commitment tool registry
- */
-function collectCommitmentToolFunctions() {
-    const allToolFunctions = {};
-    for (const commitmentDefinition of getAllCommitmentDefinitions()) {
-        const toolFunctions = commitmentDefinition.getToolFunctions();
-        for (const [funcName, funcImpl] of Object.entries(toolFunctions)) {
-            if (allToolFunctions[funcName] !== undefined &&
-                just(false) /* <- Note: [??] How to deal with commitment aliases */) {
-                throw new UnexpectedError(`Duplicate tool function name detected: \`${funcName}\` provided by commitment \`${commitmentDefinition.type}\``);
-            }
-            allToolFunctions[funcName] = funcImpl;
-        }
-    }
-    return allToolFunctions;
-}
-/**
- * Creates a proxy that resolves tool functions on demand.
- *
- * @param getFunctions - Provider of current tool functions.
- * @returns Proxy exposing tool functions as properties.
- * @private internal helper for commitment tool registry
- */
-function createToolFunctionsProxy(getFunctions) {
-    const resolveFunctions = () => getFunctions();
-    return new Proxy({}, {
-        get(_target, prop) {
-            if (typeof prop !== 'string') {
-                return undefined;
-            }
-            return resolveFunctions()[prop];
-        },
-        has(_target, prop) {
-            if (typeof prop !== 'string') {
-                return false;
+            return resolveFunctions()[prop];
+        },
+        has(_target, prop) {
+            if (typeof prop !== 'string') {
+                return false;
             }
             return prop in resolveFunctions();
         },
@@ -32459,6 +30482,155 @@ function getAllCommitmentsToolFunctionsForNode() {
  * TODO: [??] Unite `xxxForServer` and `xxxForNode` naming
  */
 
+/**
+ * Attempts to locate the specified application on a Linux system using the 'which' command.
+ * Returns the path to the executable if found, or null otherwise.
+ *
+ * @private within the repository
+ */
+async function locateAppOnLinux({ linuxWhich, }) {
+    try {
+        const result = await $execCommand({ crashOnError: true, command: `which ${linuxWhich}` });
+        return result.trim();
+    }
+    catch (error) {
+        assertsError(error);
+        return null;
+    }
+}
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */
+
+/**
+ * Checks if the file is executable
+ *
+ * @private within the repository
+ */
+async function isExecutable(path, fs) {
+    try {
+        await fs.access(path, fs.constants.X_OK);
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Note: Not [~🟢~] because it is not directly dependent on `fs
+ * TODO: [🖇] What about symlinks?
+ */
+
+// Note: Module `userhome` has no types available, so it is imported using `require`
+//       @see https://stackoverflow.com/questions/37000981/how-to-import-node-module-in-typescript-without-type-definitions
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const userhome = require('userhome');
+/**
+ * Attempts to locate the specified application on a macOS system by checking standard application paths and using mdfind.
+ * Returns the path to the executable if found, or null otherwise.
+ *
+ * @private within the repository
+ */
+async function locateAppOnMacOs({ macOsName, }) {
+    try {
+        const toExec = `/Contents/MacOS/${macOsName}`;
+        const regPath = `/Applications/${macOsName}.app` + toExec;
+        const altPath = userhome(regPath.slice(1));
+        if (await isExecutable(regPath, $provideFilesystemForNode())) {
+            return regPath;
+        }
+        else if (await isExecutable(altPath, $provideFilesystemForNode())) {
+            return altPath;
+        }
+        const result = await $execCommand({
+            crashOnError: true,
+            command: `mdfind 'kMDItemDisplayName == "${macOsName}" && kMDItemKind == Application'`,
+        });
+        return result.trim() + toExec;
+    }
+    catch (error) {
+        assertsError(error);
+        return null;
+    }
+}
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */
+
+/**
+ * Attempts to locate the specified application on a Windows system by searching common installation directories.
+ * Returns the path to the executable if found, or null otherwise.
+ *
+ * @private within the repository
+ */
+async function locateAppOnWindows({ appName, windowsSuffix, }) {
+    try {
+        const prefixes = [
+            process.env.LOCALAPPDATA,
+            join(process.env.LOCALAPPDATA || '', 'Programs'),
+            process.env.PROGRAMFILES,
+            process.env['PROGRAMFILES(X86)'],
+        ];
+        for (const prefix of prefixes) {
+            const path = prefix + windowsSuffix;
+            if (await isExecutable(path, $provideFilesystemForNode())) {
+                return path;
+            }
+        }
+        throw new Error(`Can not locate app ${appName} on Windows.`);
+    }
+    catch (error) {
+        assertsError(error);
+        return null;
+    }
+}
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */
+
+/**
+ * Locates an application on the system
+ *
+ * @private within the repository
+ */
+function locateApp(options) {
+    if (!$isRunningInNode()) {
+        throw new EnvironmentMismatchError('Locating apps works only in Node.js environment');
+    }
+    const { appName, linuxWhich, windowsSuffix, macOsName } = options;
+    if (process.platform === 'win32') {
+        if (windowsSuffix) {
+            return locateAppOnWindows({ appName, windowsSuffix });
+        }
+        else {
+            throw new Error(`${appName} is not available on Windows.`);
+        }
+    }
+    else if (process.platform === 'darwin') {
+        if (macOsName) {
+            return locateAppOnMacOs({ macOsName });
+        }
+        else {
+            throw new Error(`${appName} is not available on macOS.`);
+        }
+    }
+    else {
+        if (linuxWhich) {
+            return locateAppOnLinux({ linuxWhich });
+        }
+        else {
+            throw new Error(`${appName} is not available on Linux.`);
+        }
+    }
+}
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */
+
 /**
  * Locates the LibreOffice executable on the current system by searching platform-specific paths.
  * Returns the path to the executable if found, or null otherwise.