agent-web-interface 4.4.0 → 4.5.0

package/dist/src/tools/response-builder.js

@@ -5,42 +5,7 @@
  * - State tools return `<state>...</state>` (via StateManager)
  * - Data tools return `<result type="...">...</result>` (via builders here)
  */
-import { getStateManager } from './state-manager-registry.js';
 import { escapeXml, xmlAttr } from '../lib/text-utils.js';
-// ============================================================================
-// State Response Builders (for mutation/navigation tools)
-// ============================================================================
-/**
- * Build an XML state response for a page snapshot.
- *
- * This is the standard way to generate a response for tools that:
- * - Launch/connect browsers
- * - Navigate to URLs
- * - Capture snapshots directly
- * - Perform mutations (click, type, etc.)
- *
- * @param pageId - The page identifier
- * @param snapshot - The captured snapshot
- * @returns XML state response string
- */
-export function buildStateResponse(pageId, snapshot) {
-    const stateManager = getStateManager(pageId);
-    return stateManager.generateResponse(snapshot);
-}
-/**
- * Build an error response.
- *
- * This provides a consistent error format across all tools.
- *
- * @param pageId - The page identifier
- * @param error - The error message or Error object
- * @returns XML state response string with error
- */
-export function buildErrorResponse(pageId, error) {
-    const stateManager = getStateManager(pageId);
-    const errorMessage = error instanceof Error ? error.message : error;
-    return stateManager.generateErrorResponse(errorMessage);
-}
 /**
  * Build XML response for list_pages tool.
  *
@@ -66,16 +31,6 @@ export function buildClosePageResponse(pageId) {
   <closed page_id="${escapeXml(pageId)}" />
 </result>`;
 }
-/**
- * Build XML response for close_session tool.
- *
- * @returns XML result string
- */
-export function buildCloseSessionResponse() {
-    return `<result type="close_session" status="success">
-  <closed />
-</result>`;
-}
 /**
  * Build XML response for find_elements tool.
  *
@@ -105,11 +60,13 @@ export function buildFindElementsResponse(pageId, snapshotId, matches) {
             if (m.state.enabled !== undefined)
                 attrs.push(`enabled="${m.state.enabled ? 'true' : 'false'}"`);
             if (m.state.checked)
-                attrs.push(`checked="true"`);
+                attrs.push(`checked="${m.state.checked === 'mixed' ? 'mixed' : 'true'}"`);
             if (m.state.expanded)
                 attrs.push(`expanded="true"`);
             if (m.state.selected)
                 attrs.push(`selected="true"`);
+            if (m.state.pressed)
+                attrs.push(`pressed="true"`);
             if (m.state.focused)
                 attrs.push(`focused="true"`);
         }
@@ -129,6 +86,31 @@ export function buildFindElementsResponse(pageId, snapshotId, matches) {
     lines.push(`</result>`);
     return lines.join('\n');
 }
+/**
+ * Build XML response for read_page tool.
+ *
+ * @param article - Extracted article metadata and content
+ * @returns XML result string
+ */
+export function buildReadPageResponse(article) {
+    const metaAttrs = [xmlAttr('title', article.title)];
+    if (article.byline)
+        metaAttrs.push(xmlAttr('byline', article.byline));
+    if (article.excerpt)
+        metaAttrs.push(xmlAttr('excerpt', article.excerpt));
+    if (article.siteName)
+        metaAttrs.push(xmlAttr('site_name', article.siteName));
+    if (article.lang)
+        metaAttrs.push(xmlAttr('lang', article.lang));
+    const lines = [];
+    lines.push('<result type="read_page">');
+    lines.push(`  <metadata ${metaAttrs.join(' ')} />`);
+    lines.push(`  <content length="${article.length}">`);
+    lines.push(escapeXml(article.textContent.trim()));
+    lines.push('  </content>');
+    lines.push('</result>');
+    return lines.join('\n');
+}
 /**
  * Build XML response for get_element_details tool.
  *
@@ -171,11 +153,13 @@ export function buildGetElementDetailsResponse(_pageId, _snapshotId, node) {
         if (node.state.enabled === false)
             attrs.push('enabled="false"');
         if (node.state.checked)
-            attrs.push('checked="true"');
+            attrs.push(`checked="${node.state.checked === 'mixed' ? 'mixed' : 'true'}"`);
         if (node.state.expanded)
             attrs.push('expanded="true"');
         if (node.state.selected)
             attrs.push('selected="true"');
+        if (node.state.pressed)
+            attrs.push('pressed="true"');
         if (node.state.focused)
             attrs.push('focused="true"');
         if (node.state.required)

package/dist/src/tools/response-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"response-builder.js","sourceRoot":"","sources":["../../../src/tools/response-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"response-builder.js","sourceRoot":"","sources":["../../../src/tools/response-builder.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/stale-element-retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stale-element-retry.d.ts","sourceRoot":"","sources":["../../../src/tools/stale-element-retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASzD;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAChD,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAA;CAAE,GAC1E,OAAO,CAAC,uBAAuB,CAAC,CA4ClC"}
+{"version":3,"file":"stale-element-retry.d.ts","sourceRoot":"","sources":["../../../src/tools/stale-element-retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASzD;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;CACvB;AA8CD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAChD,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAA;CAAE,GAC1E,OAAO,CAAC,uBAAuB,CAAC,CA0ClC"}

package/dist/src/tools/stale-element-retry.js

@@ -17,6 +17,41 @@ export function isStaleElementError(err) {
         message.includes('node is detached from document') ||
         message.includes('node has been deleted'));
 }
+/**
+ * Find the best matching node in a fresh snapshot using label+kind plus
+ * location-based disambiguation scoring.
+ *
+ * Candidates must match on label and kind. Among those, we score by how many
+ * `where` properties (region, heading_context, group_id) also match. Ties are
+ * broken by choosing the node whose backend_node_id is closest to the original,
+ * as a proxy for DOM proximity.
+ */
+function findBestMatch(original, freshNodes) {
+    const candidates = freshNodes.filter((n) => n.label === original.label && n.kind === original.kind);
+    if (candidates.length <= 1)
+        return candidates[0];
+    // Score each candidate by matching where-properties
+    const scored = candidates.map((candidate) => {
+        let score = 0;
+        if (candidate.where.region === original.where.region)
+            score++;
+        if (original.where.heading_context != null &&
+            candidate.where.heading_context === original.where.heading_context)
+            score++;
+        if (original.where.group_id != null && candidate.where.group_id === original.where.group_id)
+            score++;
+        return { candidate, score };
+    });
+    // Sort: highest score first, then closest backend_node_id as tiebreaker
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        const distA = Math.abs(a.candidate.backend_node_id - original.backend_node_id);
+        const distB = Math.abs(b.candidate.backend_node_id - original.backend_node_id);
+        return distA - distB;
+    });
+    return scored[0].candidate;
+}
 /**
  * Handle stale element retry logic.
  *
@@ -35,8 +70,8 @@ export async function handleStaleElementRetry(handle, node, action, capture, sna
         if (snapshotStore) {
             snapshotStore.store(handle.page_id, freshSnapshot);
         }
-        // Find element by label in fresh snapshot
-        const freshNode = freshSnapshot.nodes.find((n) => n.label === node.label && n.kind === node.kind);
+        // Find element by label+kind, then disambiguate using location context
+        const freshNode = findBestMatch(node, freshSnapshot.nodes);
         if (!freshNode) {
             return {
                 success: false,

package/dist/src/tools/stale-element-retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"stale-element-retry.js","sourceRoot":"","sources":["../../../src/tools/stale-element-retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAC1C,OAAO,CACL,OAAO,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACtD,OAAO,CAAC,QAAQ,CAAC,6CAA6C,CAAC;QAC/D,OAAO,CAAC,QAAQ,CAAC,gCAAgC,CAAC;QAClD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAC1C,CAAC;AACJ,CAAC;AAWD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAAkB,EAClB,IAAkB,EAClB,MAAgD,EAChD,OAA0B,EAC1B,aAA2E;IAE3E,IAAI,CAAC;QACH,yBAAyB;QACzB,MAAM,aAAa,GAAG,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC;QAEjD,oCAAoC;QACpC,IAAI,aAAa,EAAE,CAAC;YAClB,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACrD,CAAC;QAED,0CAA0C;QAC1C,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CACtD,CAAC;QAEF,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,0CAA0C,IAAI,CAAC,KAAK,EAAE;gBAC7D,OAAO,EAAE;oBACP,MAAM,EAAE,mBAAmB;oBAC3B,GAAG,EAAE,EAAE,EAAE,wCAAwC;oBACjD,gBAAgB,EAAE,IAAI,CAAC,KAAK;iBAC7B;aACF,CAAC;QACJ,CAAC;QAED,0CAA0C;QAC1C,MAAM,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QAExC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,IAAI,EAAE;SAC5E,CAAC;IACJ,CAAC;IAAC,OAAO,QAAQ,EAAE,CAAC;QAClB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EACH,QAAQ,YAAY,KAAK;gBACvB,CAAC,CAAC,iBAAiB,QAAQ,CAAC,OAAO,EAAE;gBACrC,CAAC,CAAC,iBAAiB,MAAM,CAAC,QAAQ,CAAC,EAAE;YACzC,OAAO,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,IAAI,EAAE;SAC5E,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"stale-element-retry.js","sourceRoot":"","sources":["../../../src/tools/stale-element-retry.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/tool-context.d.ts

@@ -1,53 +1,21 @@
 /**
  * Tool Context
  *
- * Shared plumbing for all tool modules (browser-tools, canvas-tools, form-tools).
- * Centralizes session management, snapshot storage, page resolution, and element lookup.
+ * Implementation helpers used by SessionController for page resolution
+ * and CDP session health. These accept a SessionManager parameter rather
+ * than using module-level singletons.
  */
 import type { SessionManager } from '../browser/session-manager.js';
 import type { PageHandle } from '../browser/page-registry.js';
-import type { BaseSnapshot, ReadableNode } from '../snapshot/snapshot.types.js';
-import type { RuntimeHealth } from '../state/health.types.js';
-import { SnapshotStore } from '../snapshot/index.js';
-/**
- * Initialize shared tool context with a session manager.
- * Must be called once before using any tool handlers.
- */
-export declare function initializeToolContext(manager: SessionManager): void;
-/**
- * Get the session manager, throwing if not initialized.
- */
-export declare function getSessionManager(): SessionManager;
-/**
- * Get the shared snapshot store instance.
- */
-export declare function getSnapshotStore(): SnapshotStore;
+import type { CdpSessionResult } from './tool-context.types.js';
 /**
  * Resolve page_id to a PageHandle, throwing if not found.
  * Also touches the page to mark it as MRU.
  */
 export declare function resolveExistingPage(session: SessionManager, page_id: string | undefined): PageHandle;
-export interface CdpSessionResult {
-    handle: PageHandle;
-    recovered: boolean;
-    runtime_health: RuntimeHealth;
-}
 /**
  * Ensure CDP session is healthy, attempting repair if needed.
  * Call this before any CDP operation to auto-repair dead sessions.
  */
 export declare function ensureCdpSession(session: SessionManager, handle: PageHandle): Promise<CdpSessionResult>;
-/**
- * Require snapshot for a page, throwing a consistent error if missing.
- */
-export declare function requireSnapshot(pageId: string): BaseSnapshot;
-/**
- * Resolve element by eid for action tools.
- * Looks up element in registry and finds corresponding node in snapshot.
- * Includes proactive staleness detection before CDP interaction.
- *
- * @throws {ElementNotFoundError} If eid not found in registry
- * @throws {StaleElementError} If eid reference is stale or element not in current snapshot
- */
-export declare function resolveElementByEid(pageId: string, eid: string, snapshot: BaseSnapshot): ReadableNode;
 //# sourceMappingURL=tool-context.d.ts.map

package/dist/src/tools/tool-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAUrD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAEnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAQD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,UAAU,CASZ;AAMD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,aAAa,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAM5D;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,YAAY,GACrB,YAAY,CAmBd"}
+{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAMhE;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,UAAU,CASZ;AAMD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAoB3B"}

package/dist/src/tools/tool-context.js

@@ -1,43 +1,11 @@
 /**
  * Tool Context
  *
- * Shared plumbing for all tool modules (browser-tools, canvas-tools, form-tools).
- * Centralizes session management, snapshot storage, page resolution, and element lookup.
+ * Implementation helpers used by SessionController for page resolution
+ * and CDP session health. These accept a SessionManager parameter rather
+ * than using module-level singletons.
  */
 import { createHealthyRuntime, createRecoveredCdpRuntime } from '../state/health.types.js';
-import { SnapshotStore } from '../snapshot/index.js';
-import { getStateManager } from './state-manager-registry.js';
-import { ElementNotFoundError, StaleElementError, SnapshotRequiredError } from './errors.js';
-// ---------------------------------------------------------------------------
-// Session Manager Singleton
-// ---------------------------------------------------------------------------
-let sessionManager = null;
-/**
- * Initialize shared tool context with a session manager.
- * Must be called once before using any tool handlers.
- */
-export function initializeToolContext(manager) {
-    sessionManager = manager;
-}
-/**
- * Get the session manager, throwing if not initialized.
- */
-export function getSessionManager() {
-    if (!sessionManager) {
-        throw new Error('Tools not initialized. Call initializeToolContext() first.');
-    }
-    return sessionManager;
-}
-// ---------------------------------------------------------------------------
-// Snapshot Store Singleton
-// ---------------------------------------------------------------------------
-const snapshotStore = new SnapshotStore();
-/**
- * Get the shared snapshot store instance.
- */
-export function getSnapshotStore() {
-    return snapshotStore;
-}
 // ---------------------------------------------------------------------------
 // Page Resolution
 // ---------------------------------------------------------------------------
@@ -53,6 +21,9 @@ export function resolveExistingPage(session, page_id) {
     session.touchPage(handle.page_id);
     return handle;
 }
+// ---------------------------------------------------------------------------
+// CDP Session Health
+// ---------------------------------------------------------------------------
 /**
  * Ensure CDP session is healthy, attempting repair if needed.
  * Call this before any CDP operation to auto-repair dead sessions.
@@ -76,44 +47,4 @@ export async function ensureCdpSession(session, handle) {
         runtime_health: createRecoveredCdpRuntime('HEALTHY'),
     };
 }
-// ---------------------------------------------------------------------------
-// Snapshot Resolution
-// ---------------------------------------------------------------------------
-/**
- * Require snapshot for a page, throwing a consistent error if missing.
- */
-export function requireSnapshot(pageId) {
-    const snap = snapshotStore.getByPageId(pageId);
-    if (!snap) {
-        throw new SnapshotRequiredError(pageId);
-    }
-    return snap;
-}
-// ---------------------------------------------------------------------------
-// Element Resolution
-// ---------------------------------------------------------------------------
-/**
- * Resolve element by eid for action tools.
- * Looks up element in registry and finds corresponding node in snapshot.
- * Includes proactive staleness detection before CDP interaction.
- *
- * @throws {ElementNotFoundError} If eid not found in registry
- * @throws {StaleElementError} If eid reference is stale or element not in current snapshot
- */
-export function resolveElementByEid(pageId, eid, snapshot) {
-    const stateManager = 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;
-}
 //# sourceMappingURL=tool-context.js.map

package/dist/src/tools/tool-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../../src/tools/tool-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../../src/tools/tool-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAG3F,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAuB,EACvB,OAA2B;IAE3B,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,OAAO,CAAC,CAAC,CAAC,mBAAmB,OAAO,EAAE,CAAC,CAAC,CAAC,6CAA6C,CACvF,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAuB,EACvB,MAAkB;IAElB,IAAI,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YACtD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,EAAE,CAAC;QAC9E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CACV,mCAAmC,MAAM,CAAC,OAAO,KAAK,OAAO,qBAAqB,CACnF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,mCAAmC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;IACrF,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,IAAI;QACf,cAAc,EAAE,yBAAyB,CAAC,SAAS,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/src/tools/tool-context.types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Tool Context Types
+ *
+ * Defines the ToolContext interface that all tool handlers receive as a parameter.
+ * This decouples tool handlers from global singletons, enabling multi-tenancy
+ * where each session has its own isolated context.
+ *
+ * @module tools/tool-context.types
+ */
+import type { SessionManager } from '../browser/session-manager.js';
+import type { PageHandle } from '../browser/page-registry.js';
+import type { BaseSnapshot, ReadableNode } from '../snapshot/snapshot.types.js';
+import type { SnapshotStore } from '../snapshot/snapshot-store.js';
+import type { StateManager } from '../state/state-manager.js';
+import type { DependencyTracker } from '../form/dependency-tracker.js';
+import type { ObservationAccumulator } from '../observation/observation-accumulator.js';
+import type { RuntimeHealth } from '../state/health.types.js';
+import type { BrowserSessionConfig } from '../browser/browser-session-config.js';
+/**
+ * Result of ensuring a CDP session is healthy.
+ */
+export interface CdpSessionResult {
+    handle: PageHandle;
+    recovered: boolean;
+    runtime_health: RuntimeHealth;
+}
+/**
+ * Result of capturing a snapshot with recovery.
+ */
+export interface SnapshotCaptureResult {
+    snapshot: BaseSnapshot;
+    handle: PageHandle;
+    runtime_health: RuntimeHealth;
+}
+/**
+ * Context interface for tool handler execution.
+ *
+ * Provides all per-session state that tool handlers need.
+ * Replaces module-level singletons with an injectable context object.
+ *
+ * In single-tenant (stdio) mode, a DefaultToolContext wraps the existing singletons.
+ * In multi-tenant (HTTP) mode, a SessionController implements this interface directly.
+ */
+export interface ToolContext {
+    /** Unique session identifier */
+    readonly sessionId: string;
+    /**
+     * Ensure the session's browser is ready.
+     * Lazily launches/connects based on the session's BrowserSessionConfig.
+     * Idempotent — returns immediately if already running.
+     */
+    ensureBrowser(): Promise<void>;
+    /**
+     * Set the browser configuration for this session.
+     * Must be called before the browser is launched/connected.
+     * @throws Error if browser is already running
+     */
+    setBrowserConfig(config: BrowserSessionConfig): void;
+    /**
+     * Check if browser configuration can be changed.
+     * Returns true if no browser is running (allows config before 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).
+     * After this call, canReconfigure() returns true.
+     */
+    resetBrowser(): Promise<void>;
+    /**
+     * Resolve page_id to a PageHandle, returning undefined if not found.
+     */
+    resolvePage(pageId?: string): PageHandle | undefined;
+    /**
+     * Resolve page_id to a PageHandle, creating a new page if needed.
+     */
+    resolvePageOrCreate(pageId?: string): Promise<PageHandle>;
+    /**
+     * Resolve page_id to a PageHandle, throwing if not found.
+     * Also touches the page to mark it as MRU.
+     */
+    resolveExistingPage(pageId?: string): PageHandle;
+    /**
+     * Touch a page to mark it as most recently used.
+     */
+    touchPage(pageId: string): void;
+    /**
+     * Close a page and clean up its resources.
+     */
+    closePage(pageId: string): Promise<boolean>;
+    /**
+     * Sync with browser context to pick up unregistered pages.
+     * Returns all registered pages after sync.
+     */
+    syncPages(): Promise<PageHandle[]>;
+    /**
+     * Navigate a page to a URL.
+     */
+    navigateTo(pageId: string, url: string): Promise<void>;
+    /** Get the session manager for browser lifecycle operations. */
+    getSessionManager(): SessionManager;
+    /** Get the snapshot store for this session. */
+    getSnapshotStore(): SnapshotStore;
+    /** Get or create a state manager for a specific page. */
+    getStateManager(pageId: string): StateManager;
+    /** Remove the state manager for a page (on page close). */
+    removeStateManager(pageId: string): void;
+    /** Clear all state managers (on session close). */
+    clearAllStateManagers(): void;
+    /** Get the dependency tracker for this session. */
+    getDependencyTracker(): DependencyTracker;
+    /** Get the observation accumulator for this session. */
+    getObservationAccumulator(): ObservationAccumulator;
+    /**
+     * Ensure CDP session is healthy, attempting repair if needed.
+     * Call this before any CDP operation to auto-repair dead sessions.
+     */
+    ensureCdpSession(handle: PageHandle): Promise<CdpSessionResult>;
+    /**
+     * Capture a snapshot with stabilization and CDP recovery when empty.
+     */
+    captureSnapshotWithRecovery(handle: PageHandle, pageId: string): Promise<SnapshotCaptureResult>;
+    /**
+     * Require a snapshot for a page, throwing if none exists.
+     */
+    requireSnapshot(pageId: string): BaseSnapshot;
+    /**
+     * Resolve an element by eid from the snapshot.
+     * Includes proactive staleness detection.
+     *
+     * @throws {ElementNotFoundError} If eid not found in registry
+     * @throws {StaleElementError} If eid reference is stale
+     */
+    resolveElementByEid(pageId: string, eid: string, snapshot: BaseSnapshot): ReadableNode;
+    /**
+     * Close the session and clean up all resources (browser, snapshots, state, etc.).
+     * Implementations should be idempotent — repeated calls are safe no-ops.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=tool-context.types.d.ts.map

package/dist/src/tools/tool-context.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.types.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-context.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,aAAa,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,cAAc,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAM3B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAErD;;;OAGG;IACH,cAAc,IAAI,OAAO,CAAC;IAE1B;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAM9B;;OAEG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAErD;;OAEG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE1D;;;OAGG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAEjD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE5C;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEnC;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAMvD,gEAAgE;IAChE,iBAAiB,IAAI,cAAc,CAAC;IAEpC,+CAA+C;IAC/C,gBAAgB,IAAI,aAAa,CAAC;IAElC,yDAAyD;IACzD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IAE9C,2DAA2D;IAC3D,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC,mDAAmD;IACnD,qBAAqB,IAAI,IAAI,CAAC;IAE9B,mDAAmD;IACnD,oBAAoB,IAAI,iBAAiB,CAAC;IAE1C,wDAAwD;IACxD,yBAAyB,IAAI,sBAAsB,CAAC;IAMpD;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAMhE;;OAEG;IACH,2BAA2B,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAMhG;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IAE9C;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,YAAY,CAAC;IAMvF;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/src/tools/tool-context.types.js

@@ -0,0 +1,11 @@
+/**
+ * Tool Context Types
+ *
+ * Defines the ToolContext interface that all tool handlers receive as a parameter.
+ * This decouples tool handlers from global singletons, enabling multi-tenancy
+ * where each session has its own isolated context.
+ *
+ * @module tools/tool-context.types
+ */
+export {};
+//# sourceMappingURL=tool-context.types.js.map

package/dist/src/tools/tool-context.types.js.map

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

package/dist/src/tools/tool-registration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool Registration
+ *
+ * Extracts all 23 MCP tool registrations into a reusable function.
+ * Used by both stdio (index.ts) and HTTP (http-gateway.ts) entry points.
+ */
+import type { ToolContext } from './tool-context.types.js';
+import type { ToolRegistrar } from '../server/tool-registrar.types.js';
+export type { ToolRegistrar } from '../server/tool-registrar.types.js';
+/**
+ * Context resolver function type.
+ * Returns a ToolContext for the current request.
+ */
+export type ContextResolver = () => ToolContext | Promise<ToolContext>;
+/**
+ * Register all browser automation tools on an MCP server.
+ *
+ * Browser initialization is session-scoped: each ToolContext owns its own
+ * SessionManager and lazily launches/connects via ctx.ensureBrowser().
+ *
+ * @param server - The MCP server instance
+ * @param resolveCtx - Function that returns the ToolContext for the current request
+ */
+export declare function registerAllTools(server: ToolRegistrar, resolveCtx: ContextResolver): void;
+//# sourceMappingURL=tool-registration.d.ts.map

package/dist/src/tools/tool-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registration.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-registration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE,YAAY,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AA4CvE;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAKvE;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI,CA0RzF"}