agent-web-interface 4.4.0 → 4.5.0

package/dist/src/server/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../../src/server/server-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAA6B,MAAM,8BAA8B,CAAC;AAE7F,sBAAsB;AACtB,IAAI,YAAY,GAAsB,IAAI,CAAC;AAC3C,IAAI,cAAc,GAA0B,IAAI,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAE7B,uCAAuC;IACvC,qFAAqF;IACrF,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,cAAc,KAAK,IAAI,cAAc,EAAE,CAAC;IACxC,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,cAAc,KAAK,IAAI,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAyB;QACpC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,cAAc,EAAE,MAAM,CAAC,cAAc;KACtC,CAAC;IAEF,MAAM,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,YAAY,GAAG,IAAI,CAAC;IACpB,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../../src/server/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAE5D,mBAAmB;AACnB,IAAI,YAAY,GAAsB,IAAI,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,YAAY,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC"}

package/dist/src/server/tool-registrar.types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool Registrar Types
+ *
+ * Defines the minimal interface for registering MCP tools.
+ * Used by both BrowserAutomationServer (stdio) and HttpGateway (HTTP).
+ *
+ * @module server/tool-registrar.types
+ */
+import type { ZodRawShape } from 'zod';
+/**
+ * Minimal interface for registering tools on an MCP server.
+ *
+ * Implemented by:
+ * - BrowserAutomationServer (stdio transport with logging/error wrapping)
+ * - HttpToolRegistrar (HTTP transport, wraps McpServer.registerTool)
+ */
+export interface ToolRegistrar {
+    registerTool(name: string, definition: {
+        title: string;
+        description?: string;
+        inputSchema: ZodRawShape;
+        outputSchema?: ZodRawShape;
+    }, handler: (input: unknown) => Promise<unknown>): void;
+}
+//# sourceMappingURL=tool-registrar.types.d.ts.map

package/dist/src/server/tool-registrar.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registrar.types.d.ts","sourceRoot":"","sources":["../../../src/server/tool-registrar.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,WAAW,CAAC;QACzB,YAAY,CAAC,EAAE,WAAW,CAAC;KAC5B,EACD,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAC5C,IAAI,CAAC;CACT"}

package/dist/src/server/tool-registrar.types.js

@@ -0,0 +1,10 @@
+/**
+ * Tool Registrar Types
+ *
+ * Defines the minimal interface for registering MCP tools.
+ * Used by both BrowserAutomationServer (stdio) and HttpGateway (HTTP).
+ *
+ * @module server/tool-registrar.types
+ */
+export {};
+//# sourceMappingURL=tool-registrar.types.js.map

package/dist/src/server/tool-registrar.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registrar.types.js","sourceRoot":"","sources":["../../../src/server/tool-registrar.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/src/server/tool-result-handler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool Result Handler
+ *
+ * Shared result-wrapping logic for converting tool handler return values
+ * into MCP-compatible content arrays. Used by both BrowserAutomationServer
+ * (stdio) and HttpToolRegistrar (HTTP) to avoid duplication.
+ *
+ * @module server/tool-result-handler
+ */
+/** MCP text content */
+interface TextContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** MCP image content */
+interface ImageContent {
+    readonly type: 'image';
+    readonly data: string;
+    readonly mimeType: string;
+}
+/** Union of MCP content types produced by this module */
+export type Content = TextContent | ImageContent;
+/** Formatted tool result ready for MCP response */
+export interface FormattedToolResult {
+    [key: string]: unknown;
+    content: Content[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/**
+ * Format a tool handler result into an MCP-compatible content array.
+ *
+ * Handles CompositeResult, ImageResult, FileResult, structured output,
+ * plain strings, and arbitrary objects (JSON-stringified).
+ *
+ * @param result - The raw return value from a tool handler
+ * @param hasOutputSchema - Whether the tool definition has an outputSchema
+ * @returns MCP-compatible content array with optional structuredContent
+ */
+export declare function formatToolResult(result: unknown, hasOutputSchema?: boolean): FormattedToolResult;
+/**
+ * Format an error into an MCP-compatible error response.
+ *
+ * @param error - The caught error
+ * @returns MCP-compatible error content
+ */
+export declare function formatToolError(error: unknown): FormattedToolResult;
+/**
+ * Wrap a tool handler with logging, timing, and MCP result formatting.
+ *
+ * Shared by both BrowserAutomationServer (stdio) and HttpToolRegistrar (HTTP)
+ * to avoid duplicating the try/catch/timing/logging boilerplate.
+ *
+ * @param name - Tool name used in log messages
+ * @param handler - The raw tool handler function
+ * @param hasOutputSchema - Whether the tool definition has an outputSchema
+ * @returns A wrapped handler that returns a FormattedToolResult
+ */
+export declare function wrapToolHandler<T>(name: string, handler: (input: T) => Promise<unknown>, hasOutputSchema: boolean): (input: T) => Promise<FormattedToolResult>;
+export {};
+//# sourceMappingURL=tool-result-handler.d.ts.map

package/dist/src/server/tool-result-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-handler.d.ts","sourceRoot":"","sources":["../../../src/server/tool-result-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,uBAAuB;AACvB,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAwB;AACxB,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,yDAAyD;AACzD,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;AAEjD,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,eAAe,UAAQ,GAAG,mBAAmB,CAqE9F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAYnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EACvC,eAAe,EAAE,OAAO,GACvB,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAmB5C"}

package/dist/src/server/tool-result-handler.js

@@ -0,0 +1,137 @@
+/**
+ * Tool Result Handler
+ *
+ * Shared result-wrapping logic for converting tool handler return values
+ * into MCP-compatible content arrays. Used by both BrowserAutomationServer
+ * (stdio) and HttpToolRegistrar (HTTP) to avoid duplication.
+ *
+ * @module server/tool-result-handler
+ */
+import { isCompositeResult, isImageResult, isFileResult } from '../tools/tool-result.types.js';
+import { getLogger } from '../shared/services/logging.service.js';
+/**
+ * Format a tool handler result into an MCP-compatible content array.
+ *
+ * Handles CompositeResult, ImageResult, FileResult, structured output,
+ * plain strings, and arbitrary objects (JSON-stringified).
+ *
+ * @param result - The raw return value from a tool handler
+ * @param hasOutputSchema - Whether the tool definition has an outputSchema
+ * @returns MCP-compatible content array with optional structuredContent
+ */
+export function formatToolResult(result, hasOutputSchema = false) {
+    // Composite result - return as multi-content (text + image)
+    if (isCompositeResult(result)) {
+        if (isImageResult(result.image)) {
+            return {
+                content: [
+                    { type: 'text', text: result.text },
+                    {
+                        type: 'image',
+                        data: result.image.data,
+                        mimeType: result.image.mimeType,
+                    },
+                ],
+            };
+        }
+        else {
+            // FileResult fallback - return text + file path
+            const sizeMB = (result.image.sizeBytes / 1024 / 1024).toFixed(2);
+            return {
+                content: [
+                    { type: 'text', text: result.text },
+                    {
+                        type: 'text',
+                        text: `Screenshot saved to: ${result.image.path} (${sizeMB} MB, ${result.image.mimeType})`,
+                    },
+                ],
+            };
+        }
+    }
+    // Image result - return as MCP ImageContent (inline base64)
+    if (isImageResult(result)) {
+        return {
+            content: [
+                {
+                    type: 'image',
+                    data: result.data,
+                    mimeType: result.mimeType,
+                },
+            ],
+        };
+    }
+    // File result - return file path as text (for large screenshots)
+    if (isFileResult(result)) {
+        const sizeMB = (result.sizeBytes / 1024 / 1024).toFixed(2);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Screenshot saved to: ${result.path} (${sizeMB} MB, ${result.mimeType})`,
+                },
+            ],
+        };
+    }
+    // When outputSchema is defined, return structuredContent for MCP validation
+    if (hasOutputSchema) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+            structuredContent: result,
+        };
+    }
+    // If result is already a string (e.g., XML), use it directly
+    // Otherwise JSON.stringify it
+    const textContent = typeof result === 'string' ? result : JSON.stringify(result);
+    return {
+        content: [{ type: 'text', text: textContent }],
+    };
+}
+/**
+ * Format an error into an MCP-compatible error response.
+ *
+ * @param error - The caught error
+ * @returns MCP-compatible error content
+ */
+export function formatToolError(error) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: error instanceof Error ? error.message : String(error),
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Wrap a tool handler with logging, timing, and MCP result formatting.
+ *
+ * Shared by both BrowserAutomationServer (stdio) and HttpToolRegistrar (HTTP)
+ * to avoid duplicating the try/catch/timing/logging boilerplate.
+ *
+ * @param name - Tool name used in log messages
+ * @param handler - The raw tool handler function
+ * @param hasOutputSchema - Whether the tool definition has an outputSchema
+ * @returns A wrapped handler that returns a FormattedToolResult
+ */
+export function wrapToolHandler(name, handler, hasOutputSchema) {
+    const logger = getLogger();
+    return async (input) => {
+        const startTime = Date.now();
+        logger.debug(`Executing tool: ${name}`);
+        try {
+            const result = await handler(input);
+            const executionTime = Date.now() - startTime;
+            logger.debug(`Tool ${name} completed in ${executionTime}ms`);
+            return formatToolResult(result, hasOutputSchema);
+        }
+        catch (error) {
+            const executionTime = Date.now() - startTime;
+            logger.error(`Tool ${name} failed after ${executionTime}ms`, error instanceof Error ? error : undefined);
+            return formatToolError(error);
+        }
+    };
+}
+//# sourceMappingURL=tool-result-handler.js.map

package/dist/src/server/tool-result-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-handler.js","sourceRoot":"","sources":["../../../src/server/tool-result-handler.ts"],"names":[],"mappings":"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"}

package/dist/src/session/session-controller.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Session Controller
+ *
+ * Per-tenant state container that implements ToolContext.
+ * Each agent/session gets its own SessionController instance
+ * with isolated pages, snapshots, state managers, and registries.
+ *
+ * Each session owns its own SessionManager and browser lifecycle,
+ * configured independently via BrowserSessionConfig.
+ *
+ * @module session/session-controller
+ */
+import type { BaseSnapshot, ReadableNode } from '../snapshot/snapshot.types.js';
+import { SessionManager } from '../browser/session-manager.js';
+import { SnapshotStore } from '../snapshot/snapshot-store.js';
+import { StateManager } from '../state/state-manager.js';
+import { DependencyTracker } from '../form/dependency-tracker.js';
+import { ObservationAccumulator } from '../observation/observation-accumulator.js';
+import type { ToolContext, CdpSessionResult, SnapshotCaptureResult } from '../tools/tool-context.types.js';
+import { type BrowserSessionConfig } from '../browser/browser-session-config.js';
+import type { PageHandle } from '../browser/page-registry.js';
+/**
+ * Session state machine.
+ */
+export type SessionState = 'initializing' | 'active' | 'closing' | 'closed';
+/**
+ * SessionController configuration.
+ */
+export interface SessionControllerOptions {
+    /** Unique session identifier */
+    sessionId: string;
+    /** Optional browser configuration for this session */
+    browserConfig?: BrowserSessionConfig;
+}
+/**
+ * Per-tenant session controller implementing ToolContext.
+ *
+ * Owns all per-session state:
+ * - SessionManager (per-session browser lifecycle)
+ * - SnapshotStore (per-session snapshot cache)
+ * - StateManagers (one per page)
+ * - DependencyTracker (per-session form dependencies)
+ * - ObservationAccumulator (per-session DOM mutation tracking)
+ */
+export declare class SessionController implements ToolContext {
+    readonly sessionId: string;
+    private _sessionManager;
+    private _browserConfig;
+    private readonly _snapshotStore;
+    private readonly _stateManagers;
+    private readonly _dependencyTracker;
+    private readonly _observationAccumulator;
+    /** Deduplication promise for concurrent ensureBrowser() calls */
+    private _ensureBrowserPromise;
+    /** Unsubscribe from SessionManager state changes (cleanup in close()) */
+    private _unsubStateChange;
+    private _state;
+    private _lastActivity;
+    constructor(options: SessionControllerOptions);
+    /** Get the current session state. */
+    get state(): SessionState;
+    /** Touch the session to update last activity timestamp. */
+    touch(): void;
+    /** Get the time of last activity. */
+    get lastActivity(): number;
+    /**
+     * Close the session and clean up all resources, including the owned browser.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if browser configuration can be changed.
+     * Returns true when no browser is running (before first launch or after crash).
+     */
+    canReconfigure(): boolean;
+    /**
+     * Shut down the current browser and clear session state so the browser
+     * can be reconfigured (e.g., switch from a launched browser to auto_connect).
+     */
+    resetBrowser(): Promise<void>;
+    /**
+     * Set the browser configuration for this session.
+     *
+     * Must be called before the browser is launched/connected (i.e., before
+     * the first browser-touching tool call). Throws if browser is already running.
+     */
+    setBrowserConfig(config: BrowserSessionConfig): void;
+    /**
+     * Ensure the session's browser is ready.
+     *
+     * Lazily creates a SessionManager and launches/connects based on
+     * the session's BrowserSessionConfig. Idempotent — returns immediately
+     * if the browser is already running. Concurrent calls are deduplicated.
+     */
+    ensureBrowser(): Promise<void>;
+    resolvePage(pageId?: string): PageHandle | undefined;
+    resolvePageOrCreate(pageId?: string): Promise<PageHandle>;
+    resolveExistingPage(pageId?: string): PageHandle;
+    touchPage(pageId: string): void;
+    closePage(pageId: string): Promise<boolean>;
+    syncPages(): Promise<PageHandle[]>;
+    navigateTo(pageId: string, url: string): Promise<void>;
+    getSessionManager(): SessionManager;
+    getSnapshotStore(): SnapshotStore;
+    getStateManager(pageId: string): StateManager;
+    removeStateManager(pageId: string): void;
+    clearAllStateManagers(): void;
+    getDependencyTracker(): DependencyTracker;
+    getObservationAccumulator(): ObservationAccumulator;
+    ensureCdpSession(handle: PageHandle): Promise<CdpSessionResult>;
+    captureSnapshotWithRecovery(handle: PageHandle, pageId: string): Promise<SnapshotCaptureResult>;
+    requireSnapshot(pageId: string): BaseSnapshot;
+    resolveElementByEid(pageId: string, eid: string, snapshot: BaseSnapshot): ReadableNode;
+    /**
+     * Get or lazily create the session's own SessionManager.
+     */
+    private getOrCreateSessionManager;
+    /**
+     * Clear stale per-page state (snapshots, state managers, dependencies).
+     * Called when the browser crashes or disconnects unexpectedly.
+     */
+    private clearSessionState;
+}
+//# sourceMappingURL=session-controller.d.ts.map

package/dist/src/session/session-controller.d.ts.map

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

package/dist/src/session/session-controller.js

@@ -0,0 +1,273 @@
+/**
+ * Session Controller
+ *
+ * Per-tenant state container that implements ToolContext.
+ * Each agent/session gets its own SessionController instance
+ * with isolated pages, snapshots, state managers, and registries.
+ *
+ * Each session owns its own SessionManager and browser lifecycle,
+ * configured independently via BrowserSessionConfig.
+ *
+ * @module session/session-controller
+ */
+import { SessionManager } from '../browser/session-manager.js';
+import { SnapshotStore } from '../snapshot/snapshot-store.js';
+import { StateManager } from '../state/state-manager.js';
+import { DependencyTracker } from '../form/dependency-tracker.js';
+import { ObservationAccumulator } from '../observation/observation-accumulator.js';
+import { ensureCdpSession as ensureCdpSessionImpl, resolveExistingPage as resolveExistingPageImpl, } from '../tools/tool-context.js';
+import { captureSnapshotWithRecovery as captureSnapshotWithRecoveryImpl } from '../tools/action-context.js';
+import { ElementNotFoundError, StaleElementError, SnapshotRequiredError } from '../tools/errors.js';
+import { defaultBrowserConfig, } from '../browser/browser-session-config.js';
+import { ensureBrowserReady } from '../browser/ensure-browser.js';
+import { getLogger } from '../shared/services/logging.service.js';
+const logger = getLogger();
+/**
+ * Per-tenant session controller implementing ToolContext.
+ *
+ * Owns all per-session state:
+ * - SessionManager (per-session browser lifecycle)
+ * - SnapshotStore (per-session snapshot cache)
+ * - StateManagers (one per page)
+ * - DependencyTracker (per-session form dependencies)
+ * - ObservationAccumulator (per-session DOM mutation tracking)
+ */
+export class SessionController {
+    sessionId;
+    _sessionManager = null;
+    _browserConfig;
+    _snapshotStore;
+    _stateManagers = new Map();
+    _dependencyTracker;
+    _observationAccumulator;
+    /** Deduplication promise for concurrent ensureBrowser() calls */
+    _ensureBrowserPromise = null;
+    /** Unsubscribe from SessionManager state changes (cleanup in close()) */
+    _unsubStateChange = null;
+    _state = 'initializing';
+    _lastActivity = Date.now();
+    constructor(options) {
+        this.sessionId = options.sessionId;
+        this._browserConfig = options.browserConfig ?? defaultBrowserConfig();
+        this._snapshotStore = new SnapshotStore();
+        this._dependencyTracker = new DependencyTracker();
+        this._observationAccumulator = new ObservationAccumulator();
+        this._state = 'active';
+    }
+    // ---------------------------------------------------------------------------
+    // Session lifecycle
+    // ---------------------------------------------------------------------------
+    /** Get the current session state. */
+    get state() {
+        return this._state;
+    }
+    /** Touch the session to update last activity timestamp. */
+    touch() {
+        this._lastActivity = Date.now();
+    }
+    /** Get the time of last activity. */
+    get lastActivity() {
+        return this._lastActivity;
+    }
+    /**
+     * Close the session and clean up all resources, including the owned browser.
+     */
+    async close() {
+        if (this._state === 'closing' || this._state === 'closed')
+            return;
+        this._state = 'closing';
+        this._unsubStateChange?.();
+        this._unsubStateChange = null;
+        this._snapshotStore.destroy();
+        this._stateManagers.clear();
+        this._dependencyTracker.clearAll();
+        // Shut down the owned browser
+        if (this._sessionManager) {
+            try {
+                await this._sessionManager.shutdown();
+            }
+            catch (err) {
+                logger.error('Error shutting down session browser', err instanceof Error ? err : undefined, { sessionId: this.sessionId });
+            }
+            this._sessionManager = null;
+        }
+        this._state = 'closed';
+    }
+    // ---------------------------------------------------------------------------
+    // Browser lifecycle (ToolContext implementation)
+    // ---------------------------------------------------------------------------
+    /**
+     * Check if browser configuration can be changed.
+     * Returns true when no browser is running (before first launch or after crash).
+     */
+    canReconfigure() {
+        if (this._ensureBrowserPromise)
+            return false;
+        return !(this._sessionManager?.isRunning() ?? false);
+    }
+    /**
+     * Shut down the current browser and clear session state so the browser
+     * can be reconfigured (e.g., switch from a launched browser to auto_connect).
+     */
+    async resetBrowser() {
+        if (this._sessionManager) {
+            await this._sessionManager.shutdown();
+        }
+        this.clearSessionState();
+    }
+    /**
+     * Set the browser configuration for this session.
+     *
+     * Must be called before the browser is launched/connected (i.e., before
+     * the first browser-touching tool call). Throws if browser is already running.
+     */
+    setBrowserConfig(config) {
+        if (!this.canReconfigure()) {
+            throw new Error('Cannot change browser configuration while the browser is running.');
+        }
+        const overrides = Object.fromEntries(Object.entries(config).filter(([, v]) => v !== undefined));
+        this._browserConfig = { ...this._browserConfig, ...overrides };
+    }
+    /**
+     * Ensure the session's browser is ready.
+     *
+     * Lazily creates a SessionManager and launches/connects based on
+     * the session's BrowserSessionConfig. Idempotent — returns immediately
+     * if the browser is already running. Concurrent calls are deduplicated.
+     */
+    async ensureBrowser() {
+        // Deduplicate concurrent calls — all callers await the same promise
+        if (this._ensureBrowserPromise) {
+            await this._ensureBrowserPromise;
+            return;
+        }
+        const session = this.getOrCreateSessionManager();
+        // ensureBrowserReady handles the isRunning() fast-path internally
+        this._ensureBrowserPromise = ensureBrowserReady(session, this._browserConfig);
+        try {
+            await this._ensureBrowserPromise;
+        }
+        finally {
+            this._ensureBrowserPromise = null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Page lifecycle (ToolContext implementation)
+    // ---------------------------------------------------------------------------
+    resolvePage(pageId) {
+        this.touch();
+        return this.getSessionManager().resolvePage(pageId);
+    }
+    async resolvePageOrCreate(pageId) {
+        this.touch();
+        return this.getSessionManager().resolvePageOrCreate(pageId);
+    }
+    resolveExistingPage(pageId) {
+        this.touch();
+        return resolveExistingPageImpl(this.getSessionManager(), pageId);
+    }
+    touchPage(pageId) {
+        this.getSessionManager().touchPage(pageId);
+    }
+    async closePage(pageId) {
+        return this.getSessionManager().closePage(pageId);
+    }
+    async syncPages() {
+        return this.getSessionManager().syncPages();
+    }
+    async navigateTo(pageId, url) {
+        await this.getSessionManager().navigateTo(pageId, url);
+    }
+    // ---------------------------------------------------------------------------
+    // State access (ToolContext implementation)
+    // ---------------------------------------------------------------------------
+    getSessionManager() {
+        return this.getOrCreateSessionManager();
+    }
+    getSnapshotStore() {
+        return this._snapshotStore;
+    }
+    getStateManager(pageId) {
+        if (!this._stateManagers.has(pageId)) {
+            this._stateManagers.set(pageId, new StateManager({ pageId }));
+        }
+        return this._stateManagers.get(pageId);
+    }
+    removeStateManager(pageId) {
+        this._stateManagers.delete(pageId);
+    }
+    clearAllStateManagers() {
+        this._stateManagers.clear();
+    }
+    getDependencyTracker() {
+        return this._dependencyTracker;
+    }
+    getObservationAccumulator() {
+        return this._observationAccumulator;
+    }
+    // ---------------------------------------------------------------------------
+    // CDP health (ToolContext implementation)
+    // ---------------------------------------------------------------------------
+    async ensureCdpSession(handle) {
+        return ensureCdpSessionImpl(this.getSessionManager(), handle);
+    }
+    // ---------------------------------------------------------------------------
+    // Snapshot capture (ToolContext implementation)
+    // ---------------------------------------------------------------------------
+    async captureSnapshotWithRecovery(handle, pageId) {
+        return captureSnapshotWithRecoveryImpl(this, handle, pageId);
+    }
+    // ---------------------------------------------------------------------------
+    // Element resolution (ToolContext implementation)
+    // ---------------------------------------------------------------------------
+    requireSnapshot(pageId) {
+        const snap = this._snapshotStore.getByPageId(pageId);
+        if (!snap) {
+            throw new SnapshotRequiredError(pageId);
+        }
+        return snap;
+    }
+    resolveElementByEid(pageId, eid, snapshot) {
+        const stateManager = this.getStateManager(pageId);
+        const registry = stateManager.getElementRegistry();
+        const elementRef = registry.getByEid(eid);
+        if (!elementRef) {
+            throw new ElementNotFoundError(eid);
+        }
+        if (registry.isStale(eid)) {
+            throw new StaleElementError(eid);
+        }
+        const node = snapshot.nodes.find((n) => n.backend_node_id === elementRef.ref.backend_node_id);
+        if (!node) {
+            throw new StaleElementError(eid);
+        }
+        return node;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Get or lazily create the session's own SessionManager.
+     */
+    getOrCreateSessionManager() {
+        if (!this._sessionManager) {
+            this._sessionManager = new SessionManager();
+            this._unsubStateChange = this._sessionManager.onStateChange((event) => {
+                if (event.currentState === 'failed') {
+                    this.clearSessionState();
+                }
+            });
+        }
+        return this._sessionManager;
+    }
+    /**
+     * Clear stale per-page state (snapshots, state managers, dependencies).
+     * Called when the browser crashes or disconnects unexpectedly.
+     */
+    clearSessionState() {
+        this._snapshotStore.clear();
+        this._stateManagers.clear();
+        this._dependencyTracker.clearAll();
+    }
+}
+//# sourceMappingURL=session-controller.js.map