@promptbook/node 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/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;

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

@@ -0,0 +1,36 @@
+import type { RunBrowserModeUsed } from './RunBrowserArgs';
+/**
+ * Observability counters and metric logging for `run_browser`.
+ *
+ * @private function of `run_browser`
+ */
+export declare const runBrowserObservability: {
+    /**
+     * Increments total-run counter and returns the updated value.
+     */
+    incrementTotalRuns(): number;
+    /**
+     * Returns current total run count.
+     */
+    getTotalRuns(): number;
+    /**
+     * Increments fallback counter and returns updated metrics.
+     */
+    incrementFallbackRunsAndGetMetrics(): {
+        readonly fallbackRuns: number;
+        readonly fallbackRate: number;
+    };
+    /**
+     * Increments one error-code counter and returns the updated value.
+     */
+    incrementRunBrowserErrorCodeCounter(code: string): number;
+    /**
+     * Writes one structured metric line for browser-tool observability.
+     */
+    logRunBrowserMetric(options: {
+        readonly event: string;
+        readonly sessionId: string;
+        readonly mode: RunBrowserModeUsed;
+        readonly payload?: Record<string, unknown>;
+    }): void;
+};

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

@@ -0,0 +1,47 @@
+import type { NormalizedRunBrowserAction, RunBrowserArtifact, RunBrowserExecutionMode, RunBrowserModeUsed, RunBrowserResultPayload } from './RunBrowserArgs';
+import type { RunBrowserToolError } from './runBrowserErrors';
+/**
+ * Payload and markdown formatters for `run_browser` outcomes.
+ *
+ * @private function of `run_browser`
+ */
+export declare const runBrowserResultFormatting: {
+    /**
+     * Produces one structured payload consumed by chat UI browser replay renderers.
+     */
+    createResultPayload(options: {
+        readonly sessionId: string;
+        readonly mode: RunBrowserExecutionMode;
+        readonly modeUsed: RunBrowserModeUsed;
+        readonly initialUrl: string;
+        readonly finalUrl: string | null;
+        readonly finalTitle: string | null;
+        readonly executedActions: ReadonlyArray<NormalizedRunBrowserAction>;
+        readonly artifacts: ReadonlyArray<RunBrowserArtifact>;
+        readonly warning: string | null;
+        readonly error: RunBrowserToolError | null;
+        readonly fallbackContent: string | null;
+        readonly timing: RunBrowserResultPayload['timing'];
+    }): RunBrowserResultPayload;
+    /**
+     * Produces a model-friendly markdown summary from browser execution artifacts.
+     */
+    formatSuccessResult(options: {
+        readonly payload: RunBrowserResultPayload;
+        readonly snapshotPath: string | null;
+    }): string;
+    /**
+     * Produces a model-friendly markdown payload when fallback scraping is used.
+     */
+    formatFallbackResult(options: {
+        readonly payload: RunBrowserResultPayload;
+        readonly fallbackContent: string;
+        readonly requestedActions: number;
+    }): string;
+    /**
+     * Produces a model-friendly markdown error payload from browser execution failures.
+     */
+    formatErrorResult(options: {
+        readonly payload: RunBrowserResultPayload;
+    }): string;
+};

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

@@ -0,0 +1,24 @@
+import type { RunBrowserArgs, RunBrowserExecutionMode, RunBrowserTimeoutConfiguration } from './RunBrowserArgs';
+/**
+ * Runtime helpers for mode/session/timeout handling in `run_browser`.
+ *
+ * @private function of `run_browser`
+ */
+export declare const runBrowserRuntime: {
+    /**
+     * Creates a dedicated session id for one tool invocation.
+     */
+    createRunBrowserSessionId(): string;
+    /**
+     * Determines whether the browser tool is running in local or remote mode.
+     */
+    resolveExecutionMode(): RunBrowserExecutionMode;
+    /**
+     * Converts the execution mode into a human-readable label.
+     */
+    formatExecutionMode(mode: RunBrowserExecutionMode): string;
+    /**
+     * Resolves timeout configuration from env defaults and optional call overrides.
+     */
+    resolveTimeoutConfiguration(overrides: RunBrowserArgs['timeouts'] | undefined): RunBrowserTimeoutConfiguration;
+};

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

@@ -0,0 +1,36 @@
+import type { Page } from 'playwright';
+import type { NormalizedRunBrowserAction, OpenPageWithUrlResult, RunBrowserAction, RunBrowserTimeoutConfiguration } from './RunBrowserArgs';
+/**
+ * Page open, action normalization and action execution helpers for `run_browser`.
+ *
+ * @private function of `run_browser`
+ */
+export declare const runBrowserWorkflow: {
+    /**
+     * Opens a new browser page and navigates to the requested URL.
+     */
+    openPageWithUrl(options: {
+        readonly url: string;
+        readonly sessionId: string;
+        readonly timeouts: RunBrowserTimeoutConfiguration;
+        readonly signal?: AbortSignal;
+    }): Promise<OpenPageWithUrlResult>;
+    /**
+     * Validates and normalizes browser actions received from the model.
+     */
+    normalizeActions(actions: ReadonlyArray<RunBrowserAction> | undefined): Array<NormalizedRunBrowserAction>;
+    /**
+     * Validates and normalizes a single action.
+     */
+    normalizeAction(action: RunBrowserAction, index: number): NormalizedRunBrowserAction;
+    /**
+     * Executes one normalized browser action on a Playwright page.
+     */
+    executeAction(options: {
+        readonly page: Page;
+        readonly action: NormalizedRunBrowserAction;
+        readonly actionIndex: number;
+        readonly timeouts: RunBrowserTimeoutConfiguration;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+};

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

@@ -0,0 +1,11 @@
+import type { RunBrowserInternalOptions } from './RunBrowserArgs';
+export type { RunBrowserActionType, RunBrowserAction, RunBrowserArgs } from './RunBrowserArgs';
+import type { RunBrowserArgs } from './RunBrowserArgs';
+/**
+ * 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.
+ */
+export declare function run_browser(args: RunBrowserArgs, internalOptions?: RunBrowserInternalOptions): Promise<string>;