agent-web-interface 4.2.0 → 4.3.0

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

@@ -0,0 +1,53 @@
+/**
+ * Tool Context
+ *
+ * Shared plumbing for all tool modules (browser-tools, canvas-tools, form-tools).
+ * Centralizes session management, snapshot storage, page resolution, and element lookup.
+ */
+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;
+/**
+ * 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

@@ -0,0 +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"}

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

@@ -0,0 +1,119 @@
+/**
+ * Tool Context
+ *
+ * Shared plumbing for all tool modules (browser-tools, canvas-tools, form-tools).
+ * Centralizes session management, snapshot storage, page resolution, and element lookup.
+ */
+import { createHealthyRuntime, createRecoveredCdpRuntime } from '../state/health.types.js';
+import { SnapshotStore } from '../snapshot/index.js';
+import { getStateManager } from './execute-action.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
+// ---------------------------------------------------------------------------
+/**
+ * Resolve page_id to a PageHandle, throwing if not found.
+ * Also touches the page to mark it as MRU.
+ */
+export function resolveExistingPage(session, page_id) {
+    const handle = session.resolvePage(page_id);
+    if (!handle) {
+        throw new Error(page_id ? `Page not found: ${page_id}` : 'No page available. Navigate to a URL first.');
+    }
+    session.touchPage(handle.page_id);
+    return handle;
+}
+/**
+ * Ensure CDP session is healthy, attempting repair if needed.
+ * Call this before any CDP operation to auto-repair dead sessions.
+ */
+export async function ensureCdpSession(session, handle) {
+    if (handle.cdp.isActive()) {
+        try {
+            await handle.cdp.send('Page.getFrameTree', undefined);
+            return { handle, recovered: false, runtime_health: createHealthyRuntime() };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[RECOVERY] CDP probe failed for ${handle.page_id}: ${message}. Attempting rebind`);
+        }
+    }
+    console.warn(`[RECOVERY] CDP session dead for ${handle.page_id}, attempting rebind`);
+    const newHandle = await session.rebindCdpSession(handle.page_id);
+    return {
+        handle: newHandle,
+        recovered: true,
+        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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../../src/tools/tool-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE7F,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E,IAAI,cAAc,GAA0B,IAAI,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,cAAc,GAAG,OAAO,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC;AAE1C;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,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;AAYD;;;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;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,GAAW,EACX,QAAsB;IAEtB,MAAM,YAAY,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,kBAAkB,EAAE,CAAC;IACnD,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAE1C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,UAAU,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC9F,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -31,14 +31,29 @@ export interface FileResult {
     /** Size in bytes */
     readonly sizeBytes: number;
 }
+/**
+ * Composite result - returned as multi-content (text + image).
+ * Used when a tool needs to return both structured data and a screenshot.
+ */
+export interface CompositeResult {
+    readonly type: 'composite';
+    /** JSON-encoded structured data (e.g., canvas metadata) */
+    readonly text: string;
+    /** Annotated screenshot */
+    readonly image: ImageResult | FileResult;
+}
 /**
  * Discriminated union of all non-text tool result types.
  */
-export type ToolResult = ImageResult | FileResult;
+export type ToolResult = ImageResult | FileResult | CompositeResult;
 /**
  * Type guard for ImageResult.
  */
 export declare function isImageResult(result: unknown): result is ImageResult;
+/**
+ * Type guard for CompositeResult.
+ */
+export declare function isCompositeResult(result: unknown): result is CompositeResult;
 /**
  * Type guard for FileResult.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"tool-result.types.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-result.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAElD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,WAAW,CASpE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,UAAU,CASlE"}
+{"version":3,"file":"tool-result.types.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-result.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CAAC;AAEpE;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,WAAW,CASpE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,eAAe,CAS5E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,UAAU,CASlE"}

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

@@ -16,6 +16,17 @@ export function isImageResult(result) {
         'data' in result &&
         'mimeType' in result);
 }
+/**
+ * Type guard for CompositeResult.
+ */
+export function isCompositeResult(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'type' in result &&
+        result.type === 'composite' &&
+        'text' in result &&
+        'image' in result);
+}
 /**
  * Type guard for FileResult.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"tool-result.types.js","sourceRoot":"","sources":["../../../src/tools/tool-result.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmCH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QACf,MAAkC,CAAC,IAAI,KAAK,OAAO;QACpD,MAAM,IAAI,MAAM;QAChB,UAAU,IAAI,MAAM,CACrB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QACf,MAAkC,CAAC,IAAI,KAAK,MAAM;QACnD,MAAM,IAAI,MAAM;QAChB,UAAU,IAAI,MAAM,CACrB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-result.types.js","sourceRoot":"","sources":["../../../src/tools/tool-result.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+CH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QACf,MAAkC,CAAC,IAAI,KAAK,OAAO;QACpD,MAAM,IAAI,MAAM;QAChB,UAAU,IAAI,MAAM,CACrB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QACf,MAAkC,CAAC,IAAI,KAAK,WAAW;QACxD,MAAM,IAAI,MAAM;QAChB,OAAO,IAAI,MAAM,CAClB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QACf,MAAkC,CAAC,IAAI,KAAK,MAAM;QACnD,MAAM,IAAI,MAAM;QAChB,UAAU,IAAI,MAAM,CACrB,CAAC;AACJ,CAAC"}