@promptbook/cli 0.111.0-7 → 0.112.0-12

package/esm/apps/agents-server/config.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+export declare const NEXT_PUBLIC_SITE_URL: URL | undefined;
+/**
+ * [♐️] Vercel environment: "development" | "preview" | "production"
+ */
+export declare const NEXT_PUBLIC_VERCEL_ENV: string | undefined;
+/**
+ * [♐️] Target environment – can be system or custom
+ */
+export declare const NEXT_PUBLIC_VERCEL_TARGET_ENV: string | undefined;
+/**
+ * [♐️] Deployment URL (without https://), e.g. "my-app-abc123.vercel.app"
+ */
+export declare const NEXT_PUBLIC_VERCEL_URL: string | undefined;
+/**
+ * [♐️] Branch URL (without https://), only for branch deployments
+ */
+export declare const NEXT_PUBLIC_VERCEL_BRANCH_URL: string | undefined;
+/**
+ * [♐️] Production domain of the project
+ */
+export declare const NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL: string | undefined;
+/**
+ * [♐️] Git provider (github | gitlab | bitbucket)
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_PROVIDER: string | undefined;
+/**
+ * [♐️] Repository owner (e.g. "hejny")
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER: string | undefined;
+/**
+ * [♐️] Repository slug (e.g. "my-project")
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG: string | undefined;
+/**
+ * [♐️] Repository internal ID
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_REPO_ID: string | undefined;
+/**
+ * [♐️] Git commit SHA (short or long)
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA: string | undefined;
+/**
+ * [♐️] Commit message used for this deployment
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE: string | undefined;
+/**
+ * [♐️] Branch name (ref), e.g. "main"
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF: string | undefined;
+/**
+ * Author name of the commit
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME: string | undefined;
+/**
+ * [♐️] Author login/username
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN: string | undefined;
+/**
+ * [♐️] Previous deployment commit SHA (if exists)
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_PREVIOUS_SHA: string | undefined;
+/**
+ * [♐️] Pull Request ID for PR-based deployments
+ */
+export declare const NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID: string | undefined;
+/**
+ * Supabase table prefix
+ *
+ * This remains the fallback/default prefix used before `_Server` contains records
+ * or for local development requests.
+ */
+export declare const SUPABASE_TABLE_PREFIX: string;
+/**
+ * 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.
+ */
+export declare const REMOTE_BROWSER_URL: string;

package/esm/apps/agents-server/src/database/acquireMigrationExecutionLock.d.ts

@@ -0,0 +1,18 @@
+import { Client } from 'pg';
+import type { DatabaseMigrationLogger } from './runDatabaseMigrations';
+/**
+ * Acquires advisory lock preventing concurrent migration execution across processes.
+ *
+ * @param client Connected PostgreSQL client.
+ * @param logger Logger used for progress output.
+ * @private function of runDatabaseMigrations
+ */
+export declare function acquireMigrationExecutionLock(client: Client, logger: DatabaseMigrationLogger): Promise<void>;
+/**
+ * Releases advisory lock used for migration execution.
+ *
+ * @param client Connected PostgreSQL client.
+ * @param logger Logger used for warnings.
+ * @private function of runDatabaseMigrations
+ */
+export declare function releaseMigrationExecutionLock(client: Client, logger: DatabaseMigrationLogger): Promise<void>;

package/esm/apps/agents-server/src/database/listRegisteredServersFromDatabase.d.ts

@@ -0,0 +1,16 @@
+import type { Client } from 'pg';
+import { type ServerRecord } from '../utils/serverRegistry';
+/**
+ * Minimal PostgreSQL client contract required by the registry reader.
+ */
+type RegisteredServersDatabaseClient = Pick<Client, 'query'>;
+/**
+ * Loads the global `_Server` registry through a PostgreSQL client.
+ *
+ * Returns an empty array when the `_Server` table does not exist yet.
+ *
+ * @param client - Connected PostgreSQL client.
+ * @returns Registered servers ordered by name.
+ */
+export declare function listRegisteredServersFromDatabase(client: RegisteredServersDatabaseClient): Promise<Array<ServerRecord>>;
+export {};

package/esm/apps/agents-server/src/database/migratePrefix.d.ts

@@ -0,0 +1,57 @@
+import { Client } from 'pg';
+import type { DatabaseMigrationAppliedBy, DatabaseMigrationLogger } from './runDatabaseMigrations';
+/**
+ * Context for one prefix migration pass.
+ *
+ * @private function of runDatabaseMigrations
+ */
+export type MigratePrefixOptions = {
+    /**
+     * Prefix to migrate.
+     */
+    readonly prefix: string;
+    /**
+     * Marker for migration records.
+     */
+    readonly appliedBy: DatabaseMigrationAppliedBy;
+    /**
+     * Fallback value used when old migration records have missing `appliedBy`.
+     */
+    readonly manualAppliedByDefault: DatabaseMigrationAppliedBy;
+    /**
+     * Connected PostgreSQL client.
+     */
+    readonly client: Client;
+    /**
+     * Logger for progress output.
+     */
+    readonly logger: DatabaseMigrationLogger;
+    /**
+     * Sorted list of SQL migration filenames.
+     */
+    readonly migrationFiles: ReadonlyArray<string>;
+    /**
+     * Path to migrations directory.
+     */
+    readonly migrationsDirectory: string;
+    /**
+     * If true, print SQL before execution.
+     */
+    readonly logSqlStatements: boolean;
+};
+/**
+ * Applies pending migrations for one prefix inside the current transaction.
+ *
+ * @param options Prefix migration options.
+ * @returns Number of newly applied migrations.
+ * @private function of runDatabaseMigrations
+ */
+export declare function applyPendingMigrationsForPrefix(options: MigratePrefixOptions): Promise<number>;
+/**
+ * Runs migrations for one prefix in a single transaction.
+ *
+ * @param options Prefix migration options.
+ * @returns Number of newly applied migrations.
+ * @private function of runDatabaseMigrations
+ */
+export declare function migratePrefix(options: MigratePrefixOptions): Promise<number>;

package/esm/apps/agents-server/src/database/resolveMigrationsDirectory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Finds migrations directory in known runtime locations.
+ *
+ * @returns Absolute path to migrations directory.
+ * @private function of runDatabaseMigrations
+ */
+export declare function resolveMigrationsDirectory(): string;
+/**
+ * Reads migration files from directory and sorts them lexicographically.
+ *
+ * @param migrationsDirectory Directory containing SQL migrations.
+ * @returns Sorted SQL migration filenames.
+ * @private function of runDatabaseMigrations
+ */
+export declare function readMigrationFiles(migrationsDirectory: string): Array<string>;

package/esm/apps/agents-server/src/database/runDatabaseMigrations.d.ts

@@ -0,0 +1,120 @@
+import { type ServerRecord } from '../utils/serverRegistry';
+/**
+ * Allowed values describing who applied a migration record.
+ */
+export declare const DATABASE_MIGRATION_APPLIED_BY: {
+    readonly AUTOMATIC: "AUTOMATIC";
+    readonly MANUAL: "MANUAL";
+};
+/**
+ * Value used in migration history to indicate whether a migration was applied automatically or manually.
+ */
+export type DatabaseMigrationAppliedBy = (typeof DATABASE_MIGRATION_APPLIED_BY)[keyof typeof DATABASE_MIGRATION_APPLIED_BY];
+/**
+ * Minimal logger contract used by the migration runner.
+ */
+export type DatabaseMigrationLogger = Pick<Console, 'error' | 'info' | 'warn'>;
+/**
+ * Resolved runtime configuration required for running SQL migrations.
+ */
+export type DatabaseMigrationRuntimeConfiguration = {
+    /**
+     * Prefixes for all table namespaces that should be migrated.
+     */
+    readonly prefixes: ReadonlyArray<string>;
+    /**
+     * Registered servers loaded from the global `_Server` table.
+     */
+    readonly registeredServers: ReadonlyArray<ServerRecord>;
+    /**
+     * Connection string for PostgreSQL used by migration runner.
+     */
+    readonly connectionString: string;
+};
+/**
+ * Options controlling one migration execution.
+ */
+export type RunDatabaseMigrationsOptions = {
+    /**
+     * Prefixes that should be migrated.
+     */
+    readonly prefixes: ReadonlyArray<string>;
+    /**
+     * Registered servers used for `--only=production|preview|<server-name>` expansion.
+     */
+    readonly registeredServers?: ReadonlyArray<ServerRecord>;
+    /**
+     * PostgreSQL connection string.
+     */
+    readonly connectionString: string;
+    /**
+     * Whether migration records should be marked as automatic or manual.
+     */
+    readonly appliedBy: DatabaseMigrationAppliedBy;
+    /**
+     * Optional subset of migration targets to process.
+     */
+    readonly onlyTargets?: ReadonlyArray<string> | null;
+    /**
+     * Optional custom migrations directory.
+     */
+    readonly migrationsDirectory?: string;
+    /**
+     * Logger used for progress output.
+     */
+    readonly logger?: DatabaseMigrationLogger;
+    /**
+     * If true, prints every SQL migration body before execution.
+     */
+    readonly logSqlStatements?: boolean;
+};
+/**
+ * Result of one prefix migration run.
+ */
+export type DatabaseMigrationPrefixResult = {
+    /**
+     * Prefix that was processed.
+     */
+    readonly prefix: string;
+    /**
+     * Number of newly applied migration files.
+     */
+    readonly appliedCount: number;
+};
+/**
+ * Result of full migration run across all selected prefixes.
+ */
+export type RunDatabaseMigrationsResult = {
+    /**
+     * Prefixes that were processed.
+     */
+    readonly processedPrefixes: ReadonlyArray<string>;
+    /**
+     * Number of SQL migration files discovered on disk.
+     */
+    readonly totalMigrationFiles: number;
+    /**
+     * Per-prefix summary.
+     */
+    readonly perPrefix: ReadonlyArray<DatabaseMigrationPrefixResult>;
+};
+/**
+ * Reads migration runtime configuration from environment variables and `_Server`.
+ *
+ * @param logger - Logger used for warnings.
+ * @returns Parsed configuration or `null` when migration should be skipped.
+ */
+export declare function resolveDatabaseMigrationRuntimeConfiguration(logger?: DatabaseMigrationLogger): Promise<DatabaseMigrationRuntimeConfiguration | null>;
+/**
+ * Executes pending SQL migrations for selected prefixes.
+ *
+ * @param options - Migration execution options.
+ * @returns Aggregated migration summary.
+ */
+export declare function runDatabaseMigrations(options: RunDatabaseMigrationsOptions): Promise<RunDatabaseMigrationsResult>;
+/**
+ * Resolves PostgreSQL connection string from supported environment variables.
+ *
+ * @returns Connection string or `null` when not found.
+ */
+export declare function resolveDatabaseMigrationConnectionStringFromEnvironment(): string | null;

package/esm/apps/agents-server/src/database/selectPrefixesForMigration.d.ts

@@ -0,0 +1,13 @@
+import { type ServerRecord } from '../utils/serverRegistry';
+/**
+ * Selects prefixes to migrate and validates `--only` targets.
+ *
+ * Targets may reference environment groups (`production`, `preview`),
+ * registered server names, or raw table prefixes.
+ *
+ * @param configuredPrefixes - Prefixes available for migration.
+ * @param registeredServers - Servers known from the global `_Server` registry.
+ * @param onlyTargets - Optional CLI filter.
+ * @returns Prefixes selected for this run.
+ */
+export declare function selectPrefixesForMigration(configuredPrefixes: ReadonlyArray<string>, registeredServers: ReadonlyArray<ServerRecord>, onlyTargets: ReadonlyArray<string> | null | undefined): Array<string>;

package/esm/apps/agents-server/src/tools/$provideBrowserForServer.d.ts

@@ -0,0 +1,28 @@
+import { BrowserContext } from 'playwright';
+import { type BrowserContextRequestOptions } from './BrowserConnectionProvider';
+/**
+ * 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
+ */
+export declare function $provideBrowserForServer(options?: BrowserContextRequestOptions): Promise<BrowserContext>;
+/**
+ * Closes all open pages in the current browser context.
+ *
+ * This function is useful for cleanup between agent tasks to avoid memory leaks.
+ * It does not close the browser instance itself, allowing it to be reused.
+ */
+export declare function $closeBrowserPages(): Promise<void>;
+/**
+ * Closes the browser context and disconnects from the browser.
+ *
+ * This should be called during server shutdown or when the browser is no longer needed.
+ */
+export declare function $closeBrowser(): Promise<void>;
+/**
+ * TODO: [🏓] Unite `xxxForServer` and `xxxForNode` naming
+ */

package/esm/apps/agents-server/src/tools/BrowserConnectionProvider.d.ts

@@ -0,0 +1,142 @@
+import { BrowserContext } from 'playwright';
+/**
+ * Runtime options used while acquiring a browser context.
+ *
+ * @private internal type for `BrowserConnectionProvider`
+ */
+export type BrowserContextRequestOptions = {
+    /**
+     * Optional signal to cancel connect retries and waits.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional browser run session identifier for structured logs.
+     */
+    readonly sessionId?: string;
+};
+/**
+ * Constructor options for BrowserConnectionProvider.
+ *
+ * @private internal type for `BrowserConnectionProvider`
+ */
+type BrowserConnectionProviderOptions = {
+    /**
+     * Enable verbose provider-level logs.
+     */
+    readonly isVerbose?: boolean;
+    /**
+     * Connect timeout for one remote Playwright websocket attempt.
+     */
+    readonly remoteConnectTimeoutMs?: number;
+    /**
+     * Number of retries after the initial remote connect attempt.
+     */
+    readonly remoteConnectRetries?: number;
+    /**
+     * Initial retry delay in milliseconds.
+     */
+    readonly remoteConnectBackoffInitialMs?: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     */
+    readonly remoteConnectBackoffMaxMs?: number;
+    /**
+     * Retry delay multiplier.
+     */
+    readonly remoteConnectBackoffFactor?: number;
+    /**
+     * Retry jitter ratio.
+     */
+    readonly remoteConnectJitterRatio?: number;
+    /**
+     * Optional random provider used by retry jitter.
+     */
+    readonly random?: () => number;
+    /**
+     * Optional sleep provider for retry waits.
+     */
+    readonly sleep?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+};
+/**
+ * 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
+ */
+export declare class BrowserConnectionProvider {
+    private browserContext;
+    private connectionMode;
+    private readonly isVerbose;
+    private readonly remoteConnectTimeoutMs;
+    private readonly remoteConnectRetries;
+    private readonly remoteConnectBackoffInitialMs;
+    private readonly remoteConnectBackoffMaxMs;
+    private readonly remoteConnectBackoffFactor;
+    private readonly remoteConnectJitterRatio;
+    private readonly random;
+    private readonly sleep?;
+    /**
+     * Creates a new BrowserConnectionProvider.
+     *
+     * @param options - Provider options
+     * @param options.isVerbose - Enable verbose logging
+     */
+    constructor(options?: BrowserConnectionProviderOptions);
+    /**
+     * 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
+     */
+    getBrowserContext(options?: BrowserContextRequestOptions): Promise<BrowserContext>;
+    /**
+     * Closes all pages in the current browser context.
+     *
+     * This method is useful for cleanup between agent tasks without closing
+     * the entire browser instance.
+     */
+    closeAllPages(): Promise<void>;
+    /**
+     * 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.
+     */
+    close(): Promise<void>;
+    /**
+     * 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
+     */
+    private isBrowserContextAlive;
+    /**
+     * Determines whether to use local or remote browser based on configuration.
+     *
+     * @returns Connection mode configuration
+     */
+    private resolveConnectionMode;
+    /**
+     * Creates a local browser context using persistent Chromium.
+     *
+     * @returns Local browser context
+     */
+    private createLocalBrowserContext;
+    /**
+     * Creates a remote browser context by connecting to a Playwright server.
+     *
+     * @param wsEndpoint - WebSocket endpoint of the remote Playwright server
+     * @returns Remote browser context
+     */
+    private createRemoteBrowserContext;
+}
+export {};

package/esm/apps/agents-server/src/tools/runBrowserArtifacts.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from 'playwright';
+import type { CaptureSnapshotArtifactOptions, RunBrowserArtifact } from './RunBrowserArgs';
+/**
+ * Screenshot/artifact and page-cleanup helpers for `run_browser`.
+ *
+ * @private function of `run_browser`
+ */
+export declare const runBrowserArtifacts: {
+    /**
+     * Captures a screenshot artifact for the current page and returns relative path.
+     */
+    captureSnapshot(page: Page, sessionId: string, fileSuffix?: string): Promise<string | null>;
+    /**
+     * Safely retrieves page title from current browser page.
+     */
+    getPageTitle(page: Page): Promise<string | null>;
+    /**
+     * Closes browser page and logs non-fatal cleanup errors.
+     */
+    cleanupPage(page: Page | null, sessionId: string): Promise<void>;
+    /**
+     * Captures one screenshot artifact and enriches it with page metadata.
+     */
+    captureSnapshotArtifact(options: CaptureSnapshotArtifactOptions): Promise<RunBrowserArtifact | null>;
+};

package/esm/apps/agents-server/src/tools/runBrowserConstants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared constants used by the `run_browser` tool.
+ *
+ * @private internal constants of `run_browser`
+ */
+export declare const runBrowserConstants: {
+    readonly sessionPrefix: "agents-server-run-browser";
+    readonly snapshotDirectory: ".playwright-cli";
+    readonly resultSchema: "promptbook/run-browser@1";
+    readonly defaultWaitMs: 1000;
+    readonly maxWaitMs: 60000;
+    readonly defaultScrollPixels: 800;
+    readonly defaultNavigationTimeoutMs: 20000;
+    readonly defaultActionTimeoutMs: 15000;
+    readonly fallbackDynamicContentWarning: "Remote browser is unavailable. Fallback scraping was used and dynamic content may be missing.";
+    readonly validationErrorCode: "RUN_BROWSER_VALIDATION_ERROR";
+    readonly navigationFailedErrorCode: "RUN_BROWSER_NAVIGATION_FAILED";
+    readonly actionFailedErrorCode: "RUN_BROWSER_ACTION_FAILED";
+    readonly cancelledErrorCode: "RUN_BROWSER_CANCELLED";
+    readonly unknownErrorCode: "RUN_BROWSER_UNKNOWN_ERROR";
+};

package/esm/apps/agents-server/src/tools/runBrowserErrorHandling.d.ts

@@ -0,0 +1,60 @@
+import type { RunBrowserExecutionMode, TaggedRunBrowserError } from './RunBrowserArgs';
+import { type RunBrowserToolError } from './runBrowserErrors';
+/**
+ * Error classification and cancellation helpers used by `run_browser`.
+ *
+ * @private function of `run_browser`
+ */
+export declare const runBrowserErrorHandling: {
+    /**
+     * Creates one tagged ParseError used for deterministic input validation failures.
+     */
+    createRunBrowserValidationError(options: {
+        readonly message: string;
+        readonly debug: Record<string, unknown>;
+    }): TaggedRunBrowserError;
+    /**
+     * Creates one tagged KnowledgeScrapeError used for navigation failures.
+     */
+    createRunBrowserNavigationError(options: {
+        readonly message: string;
+        readonly debug: Record<string, unknown>;
+        readonly cause?: unknown;
+    }): TaggedRunBrowserError;
+    /**
+     * Creates one tagged KnowledgeScrapeError used for action failures.
+     */
+    createRunBrowserActionError(options: {
+        readonly message: string;
+        readonly debug: Record<string, unknown>;
+        readonly cause?: unknown;
+    }): TaggedRunBrowserError;
+    /**
+     * Creates one tagged KnowledgeScrapeError used for cancellation.
+     */
+    createRunBrowserCancelledError(options: {
+        readonly message: string;
+        readonly debug: Record<string, unknown>;
+        readonly cause?: unknown;
+    }): TaggedRunBrowserError;
+    /**
+     * Checks whether an unknown error carries run_browser classification tags.
+     */
+    isTaggedRunBrowserError(error: unknown): error is TaggedRunBrowserError;
+    /**
+     * Converts unknown errors into structured tool error payloads.
+     */
+    classifyRunBrowserToolError(options: {
+        readonly error: unknown;
+        readonly sessionId: string;
+        readonly mode: RunBrowserExecutionMode;
+    }): RunBrowserToolError;
+    /**
+     * Asserts that the run was not aborted.
+     */
+    assertNotAborted(signal: AbortSignal | undefined, sessionId: string): void;
+    /**
+     * Returns true when the tool error represents remote browser unavailability.
+     */
+    isRemoteBrowserUnavailableCode(code: string): boolean;
+};

package/esm/apps/agents-server/src/tools/runBrowserErrors.d.ts

@@ -0,0 +1,73 @@
+import { KnowledgeScrapeError } from '../../../../src/errors/KnowledgeScrapeError';
+/**
+ * Structured error payload returned by the `run_browser` tool.
+ */
+export type RunBrowserToolError = {
+    readonly code: string;
+    readonly message: string;
+    readonly isRetryable: boolean;
+    readonly suggestedNextSteps: ReadonlyArray<string>;
+    readonly debug: Record<string, unknown>;
+};
+/**
+ * Metadata describing the sanitized remote browser endpoint used for debugging.
+ */
+export type RemoteBrowserEndpointDebug = {
+    readonly protocol: string | null;
+    readonly host: string | null;
+    readonly port: number | null;
+};
+/**
+ * Structured details captured when remote browser infrastructure is unavailable.
+ */
+export type RemoteBrowserUnavailableDebug = {
+    readonly endpoint: RemoteBrowserEndpointDebug;
+    readonly attempts: number;
+    readonly connectTimeoutMs: number;
+    readonly durationMs: number;
+    readonly networkErrorCode: string | null;
+    readonly originalMessage: string;
+};
+/**
+ * Error code used for remote-browser infrastructure outages.
+ */
+export declare const REMOTE_BROWSER_UNAVAILABLE_ERROR_CODE = "REMOTE_BROWSER_UNAVAILABLE";
+/**
+ * Error thrown when a remote Playwright browser cannot be reached.
+ */
+export declare class RemoteBrowserUnavailableError extends KnowledgeScrapeError {
+    readonly code = "REMOTE_BROWSER_UNAVAILABLE";
+    readonly isRetryable = true;
+    readonly suggestedNextSteps: ReadonlyArray<string>;
+    readonly debug: RemoteBrowserUnavailableDebug;
+    constructor(options: {
+        readonly message: string;
+        readonly debug: RemoteBrowserUnavailableDebug;
+        readonly suggestedNextSteps?: ReadonlyArray<string>;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * Returns true when an unknown value is one of the remote-browser outage errors.
+ */
+export declare function isRemoteBrowserUnavailableError(error: unknown): error is RemoteBrowserUnavailableError;
+/**
+ * Sanitizes a remote websocket endpoint so debug payloads never expose path secrets.
+ */
+export declare function sanitizeRemoteBrowserEndpoint(wsEndpoint: string): RemoteBrowserEndpointDebug;
+/**
+ * Extracts network-like error code from unknown error payload.
+ */
+export declare function extractNetworkErrorCode(error: unknown): string | null;
+/**
+ * Classifies whether an unknown error most likely represents remote browser infra outage.
+ */
+export declare function isRemoteBrowserInfrastructureError(error: unknown): boolean;
+/**
+ * Converts unknown thrown values into safe string messages.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Converts unknown errors into stack payloads that are safe to render in debug mode.
+ */
+export declare function getErrorStack(error: unknown): string | null;