donobu 5.55.0 → 5.57.0

package/dist/esm/models/AiQuery.d.ts

@@ -1,8 +1,9 @@
 import type { InteractableElement } from './InteractableElement';
+import type { ObservationRecord } from './Observation';
 /**
  * Represents a single AI decision cycle within a flow. Created at the start of
- * a query cycle with just `id` and `queriedAt`, then progressively filled in as
- * screenshots are captured and elements are discovered. The `error` field is
+ * a query cycle with just `id` and `startedAt`, then progressively filled in as
+ * the attached providers produce their observations. The `error` field is
  * populated only if the query fails.
  */
 export type AiQuery = {
@@ -11,20 +12,10 @@ export type AiQuery = {
      */
     readonly id: string;
     /**
-     * The ID of the clean (un-annotated) screenshot of the page at query time.
-     * Null until the screenshot is captured.
+     * What each observing provider (0..N) perceived this cycle — the screenshots
+     * and elements the AI saw when it made its decision. One record per provider.
      */
-    readonly cleanScreenshotId: string | null;
-    /**
-     * The ID of the annotated screenshot (with numbered element badges) sent to the AI.
-     * Null until the screenshot is captured.
-     */
-    readonly annotatedScreenshotId: string | null;
-    /**
-     * The interactable elements that were identified and sent to the AI.
-     * Null until element discovery completes.
-     */
-    readonly interactableElements: InteractableElement[] | null;
+    readonly observations: ObservationRecord[];
     /**
      * If the AI query failed, the error message. Null on success.
      */
@@ -39,4 +30,27 @@ export type AiQuery = {
      */
     readonly completedAt: number | null;
 };
+/**
+ * The raw shape a persisted query may take when read back from storage. Flows
+ * persisted before the observations refactor stored the web screenshot/element
+ * data flat on the query and have no `observations` array. Read paths normalize
+ * these into a canonical {@link AiQuery} via {@link normalizeAiQuery}, so the
+ * rest of the system (and the API) only ever sees the `observations` shape.
+ */
+export type PersistedAiQuery = Omit<AiQuery, 'observations'> & {
+    readonly observations?: ObservationRecord[];
+    /** @deprecated Legacy pre-`observations` field. */
+    readonly cleanScreenshotId?: string | null;
+    /** @deprecated Legacy pre-`observations` field. */
+    readonly annotatedScreenshotId?: string | null;
+    /** @deprecated Legacy pre-`observations` field. */
+    readonly interactableElements?: InteractableElement[] | null;
+};
+/**
+ * Lift a persisted query into the canonical `observations` shape. Idempotent:
+ * queries that already carry `observations` are returned (re-wrapped to drop
+ * any legacy fields). Legacy queries — which always carried the web
+ * screenshot/element slots — become a single {@link WebObservationRecord}.
+ */
+export declare function normalizeAiQuery(query: PersistedAiQuery): AiQuery;
 //# sourceMappingURL=AiQuery.d.ts.map

package/dist/esm/models/AiQuery.js

@@ -1,3 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAiQuery = normalizeAiQuery;
+/**
+ * Lift a persisted query into the canonical `observations` shape. Idempotent:
+ * queries that already carry `observations` are returned (re-wrapped to drop
+ * any legacy fields). Legacy queries — which always carried the web
+ * screenshot/element slots — become a single {@link WebObservationRecord}.
+ */
+function normalizeAiQuery(query) {
+    const base = {
+        id: query.id,
+        error: query.error,
+        startedAt: query.startedAt,
+        completedAt: query.completedAt,
+    };
+    if (query.observations) {
+        return { ...base, observations: query.observations };
+    }
+    const hasLegacyWebSlots = query.cleanScreenshotId !== undefined ||
+        query.annotatedScreenshotId !== undefined ||
+        query.interactableElements !== undefined;
+    if (!hasLegacyWebSlots) {
+        return { ...base, observations: [] };
+    }
+    const record = {
+        type: 'web',
+        cleanScreenshotId: query.cleanScreenshotId ?? null,
+        annotatedScreenshotId: query.annotatedScreenshotId ?? null,
+        interactableElements: query.interactableElements ?? null,
+    };
+    return { ...base, observations: [record] };
+}
 //# sourceMappingURL=AiQuery.js.map

package/dist/esm/models/ControlPanel.d.ts

@@ -21,24 +21,29 @@ export type UserAction = {
     type: 'SET_RUN_MODE';
     runMode: RunMode;
     approvePending?: boolean;
+} | {
+    type: 'STEP';
+    instruction?: string;
+} | {
+    type: 'RUN';
+    instruction?: string;
 };
 export type ControlPanelDataUpdate = {
     state: State;
+    runMode?: RunMode;
+    /** The flow's overall objective; the panel treats a non-empty value (or a
+     * typed instruction) as a "goal", which gates ⏩ Fast-forward and ▶ Play. */
+    overallObjective?: string | null;
+    /** The tools the flow can actually run (resolved from the ToolManager). */
+    allowedTools?: string[] | null;
     headline?: string;
-    /** Names of tools loaded in the flow's ToolManager. Surfaced to the UI so
-     * the control panel can offer only tools the flow can actually run. */
-    availableToolNames?: string[];
-    /** In SUPERVISED mode, the AI-proposed tool call(s) currently awaiting the
-     * user's approval. Surfaced to the UI so the user can see what they are
-     * approving or rejecting. Empty/undefined when nothing is pending. */
+    /** AI-proposed tool call(s) awaiting approval (SUPERVISED). */
     pendingToolCalls?: ProposedToolCall[];
-    /** The flow's current run mode, so the UI can render and drive the autonomy
-     * selector (Manual/Supervised/Autonomous). */
-    runMode?: RunMode;
-    /** Whether AI-driven modes (Autonomous/Supervised) are available — i.e. the
-     * flow has a GPT client. False for purely manual flows, so the UI can disable
-     * those options on the autonomy selector. */
-    canUseAi?: boolean;
+    /** Whether the flow has a GPT client (AI available at all). Not cleanly a
+     * FlowMetadata field — a client can come from env/default config, not just a
+     * named gptConfig — so it's surfaced explicitly. Drives whether the compose
+     * surface and the ▶/⏩ transport are offered at all. */
+    hasGptClient?: boolean;
 };
 export interface ControlPanel {
     /** Cheap, idempotent render update. */

package/dist/esm/models/InteractableElement.d.ts

@@ -19,5 +19,11 @@ export declare const InteractableElementSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type InteractableElement = z.infer<typeof InteractableElementSchema>;
+/**
+ * Marker line preceding the JSON element list in a perception user message.
+ * The history optimizer locates it to trim the element list from stale turns,
+ * so the producer (web observer) and consumer (history optimizer) share it.
+ */
+export declare const INTERACTABLE_ELEMENTS_MESSAGE_MARKER = "JSON mapping of annotation to interactable element...";
 export declare function interactableElementsToPrettyJson(elements: InteractableElement[]): string;
 //# sourceMappingURL=InteractableElement.d.ts.map

package/dist/esm/models/InteractableElement.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InteractableElementSchema = exports.ScrollDirectionEnum = void 0;
+exports.INTERACTABLE_ELEMENTS_MESSAGE_MARKER = exports.InteractableElementSchema = exports.ScrollDirectionEnum = void 0;
 exports.interactableElementsToPrettyJson = interactableElementsToPrettyJson;
 const v4_1 = require("zod/v4");
 exports.ScrollDirectionEnum = v4_1.z.enum(['UP', 'DOWN', 'LEFT', 'RIGHT']);
@@ -14,6 +14,12 @@ exports.InteractableElementSchema = v4_1.z.object({
     htmlSnippet: v4_1.z.string().describe('A short HTML snippet of the element.'),
     scrollable: exports.ScrollDirectionEnum.array().describe('Live scroll directions available on the element (empty = no scrolling possible).'),
 });
+/**
+ * Marker line preceding the JSON element list in a perception user message.
+ * The history optimizer locates it to trim the element list from stale turns,
+ * so the producer (web observer) and consumer (history optimizer) share it.
+ */
+exports.INTERACTABLE_ELEMENTS_MESSAGE_MARKER = 'JSON mapping of annotation to interactable element...';
 function interactableElementsToPrettyJson(elements) {
     // Create an object maintaining insertion order.
     const result = {};

package/dist/esm/models/Observation.d.ts

@@ -0,0 +1,38 @@
+import type { UserMessageItem } from './GptMessage';
+import type { InteractableElement } from './InteractableElement';
+/**
+ * The persisted record of what one provider observed in a turn. Open by design
+ * — it carries only a `type` discriminant so each target (including plugin
+ * targets) can define its own record shape. Read more by narrowing on `type`.
+ */
+export interface ObservationRecord {
+    readonly type: string;
+}
+/**
+ * Observation record for targets perceived as screenshots (e.g. web, mobile).
+ * Narrow an {@link ObservationRecord} to this shape (e.g. via
+ * `'cleanScreenshotId' in record`) to render its screenshots and elements.
+ */
+export interface ScreenshotObservationRecord extends ObservationRecord {
+    readonly cleanScreenshotId: string | null;
+    readonly annotatedScreenshotId: string | null;
+    readonly interactableElements: InteractableElement[] | null;
+}
+/** The web target's per-turn observation record. */
+export interface WebObservationRecord extends ScreenshotObservationRecord {
+    readonly type: 'web';
+}
+/**
+ * A single observing provider's contribution to one AI decision cycle.
+ *
+ * - {@link llmContent} is injected verbatim into the turn's user message (for
+ *   web: the clean screenshot, the annotated screenshot, then the element-list
+ *   text — in that order).
+ * - {@link record} is the provider-specific payload persisted on the
+ *   {@link AiQuery} for later display/debugging.
+ */
+export type Observation = {
+    readonly llmContent: UserMessageItem[];
+    readonly record: ObservationRecord;
+};
+//# sourceMappingURL=Observation.d.ts.map

package/dist/esm/models/Observation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Observation.js.map

package/dist/esm/models/ToolCallContext.d.ts

@@ -1,9 +1,9 @@
 import type { GptClient } from '../clients/GptClient';
 import type { DonobuFlowsManager } from '../managers/DonobuFlowsManager';
 import type { InteractionVisualizer } from '../managers/InteractionVisualizer';
-import type { TargetInspector } from '../managers/TargetInspector';
 import type { ControlPanel } from '../models/ControlPanel';
 import type { FlowsPersistence } from '../persistence/flows/FlowsPersistence';
+import type { TargetProvider } from '../targets/TargetProvider';
 import type { FlowMetadata } from './FlowMetadata';
 import type { ProposedToolCall } from './ProposedToolCall';
 import type { ToolCall } from './ToolCall';
@@ -13,7 +13,8 @@ import type { ToolCall } from './ToolCall';
 export type ToolCallContext = {
     readonly flowsManager: DonobuFlowsManager;
     readonly envData: Record<string, string>;
-    readonly targetInspector: TargetInspector;
+    /** The target the tool can act on, or `null` for a targetless flow. */
+    readonly provider: TargetProvider | null;
     readonly controlPanel: ControlPanel;
     readonly persistence: FlowsPersistence;
     readonly gptClient: GptClient | null;

package/dist/esm/persistence/flows/FlowsPersistenceDonobuApi.d.ts

@@ -39,8 +39,6 @@ export declare class FlowsPersistenceDonobuApi implements FlowsPersistence {
      *   polls instead.
      */
     constructor(baseUrl: string, apiKey: string, fileCache: FileUploadCache, notifyUpload?: () => void);
-    private request;
-    private jsonRequest;
     setFlowMetadata(flowMetadata: FlowMetadata): Promise<void>;
     getFlowMetadataById(flowId: string): Promise<FlowMetadata>;
     getFlowMetadataByName(flowName: string): Promise<FlowMetadata>;
@@ -72,6 +70,8 @@ export declare class FlowsPersistenceDonobuApi implements FlowsPersistence {
     setFlowFile(flowId: string, fileId: string, fileBytes: Buffer): Promise<void>;
     setBrowserState(flowId: string, browserState: BrowserStorageState): Promise<void>;
     getBrowserState(flowId: string): Promise<BrowserStorageState | null>;
+    private request;
+    private jsonRequest;
 }
 export interface CreateDonobuFlowsPersistenceOptions {
     readonly baseUrl: string;

package/dist/esm/persistence/flows/FlowsPersistenceDonobuApi.js

@@ -8,6 +8,7 @@ exports.createDonobuFlowsPersistence = createDonobuFlowsPersistence;
 exports.startDonobuParentUploader = startDonobuParentUploader;
 const path_1 = __importDefault(require("path"));
 const FlowNotFoundException_1 = require("../../exceptions/FlowNotFoundException");
+const AiQuery_1 = require("../../models/AiQuery");
 const BrowserStorageState_1 = require("../../models/BrowserStorageState");
 const MiscUtils_1 = require("../../utils/MiscUtils");
 const FileUploadCache_1 = require("../files/FileUploadCache");
@@ -50,17 +51,6 @@ class FlowsPersistenceDonobuApi {
         this.notifyUpload = notifyUpload;
     }
     // -- helpers --------------------------------------------------------
-    async request(path, init) {
-        return donobuApiFetch(this.baseUrl, this.apiKey, path, init);
-    }
-    async jsonRequest(path, method, body) {
-        return this.request(path, {
-            method,
-            headers: { 'Content-Type': 'application/json' },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
-    }
-    // -- Flow metadata -------------------------------------------------
     async setFlowMetadata(flowMetadata) {
         const response = await this.jsonRequest(`/v1/flows/${encodeURIComponent(flowMetadata.id)}/metadata`, 'PUT', {
             id: flowMetadata.id,
@@ -86,6 +76,7 @@ class FlowsPersistenceDonobuApi {
         const body = (await response.json());
         return body.record;
     }
+    // -- Flow metadata -------------------------------------------------
     async getFlowMetadataByName(flowName) {
         const params = new URLSearchParams({ name: flowName, limit: '1' });
         const response = await this.jsonRequest(`/v1/flows?${params.toString()}`, 'GET');
@@ -161,7 +152,6 @@ class FlowsPersistenceDonobuApi {
         // worker iteration to release the claim cleanly (see processOne).
         await this.fileCache.deleteFlow(flowId);
     }
-    // -- Tool calls ----------------------------------------------------
     async setToolCall(flowId, toolCall) {
         const response = await this.jsonRequest(`/v1/flows/${encodeURIComponent(flowId)}/tool-calls/${encodeURIComponent(toolCall.id)}`, 'PUT', { record: toolCall });
         if (!response.ok) {
@@ -179,13 +169,13 @@ class FlowsPersistenceDonobuApi {
         const body = (await response.json());
         return body.items;
     }
+    // -- Tool calls ----------------------------------------------------
     async deleteToolCall(flowId, toolCallId) {
         const response = await this.jsonRequest(`/v1/flows/${encodeURIComponent(flowId)}/tool-calls/${encodeURIComponent(toolCallId)}`, 'DELETE');
         if (!response.ok) {
             throw new Error(`Failed to delete tool call: ${response.status} ${response.statusText}`);
         }
     }
-    // -- AI Queries ----------------------------------------------------
     async setAiQuery(flowId, aiQuery) {
         const response = await this.jsonRequest(`/v1/flows/${encodeURIComponent(flowId)}/ai-queries/${encodeURIComponent(aiQuery.id)}`, 'PUT', { record: aiQuery });
         if (!response.ok) {
@@ -201,9 +191,9 @@ class FlowsPersistenceDonobuApi {
             throw new Error(`Failed to get AI queries: ${response.status} ${response.statusText}`);
         }
         const body = (await response.json());
-        return body.items;
+        return body.items.map(AiQuery_1.normalizeAiQuery);
     }
-    // -- Screenshots ---------------------------------------------------
+    // -- AI Queries ----------------------------------------------------
     async saveScreenShot(flowId, bytes) {
         const imageType = MiscUtils_1.MiscUtils.detectImageType(bytes);
         const fileId = `${new Date().toISOString()}.screenshot.${imageType}`;
@@ -213,7 +203,7 @@ class FlowsPersistenceDonobuApi {
     async getScreenShot(flowId, screenShotId) {
         return this.getFlowFile(flowId, screenShotId);
     }
-    // -- Video --------------------------------------------------------
+    // -- Screenshots ---------------------------------------------------
     async setVideo(flowId, bytes) {
         await this.setFlowFile(flowId, VIDEO_FILE_ID, bytes);
     }
@@ -234,7 +224,7 @@ class FlowsPersistenceDonobuApi {
             startOffset,
         };
     }
-    // -- Flow files ----------------------------------------------------
+    // -- Video --------------------------------------------------------
     /**
      * Returns bytes for a flow file. Tries the local cache first (instant
      * playback for files this machine recently uploaded; warm cache for
@@ -274,7 +264,7 @@ class FlowsPersistenceDonobuApi {
         await this.fileCache.writePending(flowId, fileId, fileBytes);
         this.notifyUpload();
     }
-    // -- Browser state -------------------------------------------------
+    // -- Flow files ----------------------------------------------------
     async setBrowserState(flowId, browserState) {
         const response = await this.jsonRequest(`/v1/flows/${encodeURIComponent(flowId)}/browser-state`, 'PUT', { record: browserState });
         if (!response.ok) {
@@ -295,6 +285,17 @@ class FlowsPersistenceDonobuApi {
         }
         return BrowserStorageState_1.BrowserStorageStateSchema.parse(body.record);
     }
+    // -- Browser state -------------------------------------------------
+    async request(path, init) {
+        return donobuApiFetch(this.baseUrl, this.apiKey, path, init);
+    }
+    async jsonRequest(path, method, body) {
+        return this.request(path, {
+            method,
+            headers: { 'Content-Type': 'application/json' },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
 }
 exports.FlowsPersistenceDonobuApi = FlowsPersistenceDonobuApi;
 // ---------------------------------------------------------------------------

package/dist/esm/persistence/flows/FlowsPersistenceSqlite.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowsPersistenceSqlite = void 0;
 const crypto_1 = require("crypto");
 const FlowNotFoundException_1 = require("../../exceptions/FlowNotFoundException");
+const AiQuery_1 = require("../../models/AiQuery");
 const BrowserStorageState_1 = require("../../models/BrowserStorageState");
 const MiscUtils_1 = require("../../utils/MiscUtils");
 const normalizeFlowMetadata_1 = require("../normalizeFlowMetadata");
@@ -215,7 +216,7 @@ class FlowsPersistenceSqlite {
         await this.getFlowMetadataById(flowId);
         const stmt = this.db.prepare('SELECT ai_query FROM ai_queries WHERE flow_id = ? ORDER BY started_at');
         const rows = stmt.all(flowId);
-        return rows.map((row) => JSON.parse(row.ai_query));
+        return rows.map((row) => (0, AiQuery_1.normalizeAiQuery)(JSON.parse(row.ai_query)));
     }
     async setVideo(flowId, bytes) {
         // Ensure flow exists.

package/dist/esm/targets/TargetProvider.d.ts

@@ -0,0 +1,110 @@
+import type { TargetInitCallbacks } from '../managers/TargetInspector';
+import type { Observation } from '../models/Observation';
+import type { FlowsPersistence } from '../persistence/flows/FlowsPersistence';
+/**
+ * A target is the external thing a flow drives to accomplish its objective —
+ * today, a web browser. Each thing a target can do is modeled as a separate
+ * optional capability role, and a provider implements only the roles it has.
+ * The engine can then ask for one capability and skip providers that lack it,
+ * instead of every target stubbing out methods it cannot support. A flow drives
+ * a list of providers (0..N), so a single flow can span multiple targets.
+ *
+ * The roles:
+ *  - {@link ObserverCapability}      — produces the per-turn perception sent to the LLM
+ *  - {@link ActionCapability}        — the handle that tools act through
+ *  - {@link LifecycleCapability}     — connection, recovery, initialization, session state
+ *  - {@link PromptSectionCapability} — the provider's slice of the system prompt
+ */
+export interface TargetProvider {
+    /** Present iff this provider produces a per-turn observation (PUSH). */
+    readonly observer?: ObserverCapability;
+    /** Present iff this provider participates in lifecycle/recovery/session. */
+    readonly lifecycle?: LifecycleCapability;
+    /**
+     * This target's slice of the system prompt: the paragraph telling the AI what
+     * it will perceive of this target and how it acts on it. Present iff the
+     * provider contributes one. The engine owns the surrounding skeleton
+     * (references, env-vars, objective, guardrails) and labels each section when
+     * more than one provider contributes.
+     */
+    readonly systemPromptSection?: string;
+    /**
+     * Present iff this provider is reachable by tools. The engine never invokes
+     * this directly; tools narrow it by `type` to reach the concrete handle.
+     */
+    readonly action?: ActionCapability;
+}
+/** Collaborators the engine hands an observer so it can persist its own record. */
+export interface ObservationContext {
+    readonly persistence: FlowsPersistence;
+    readonly flowId: string;
+}
+/**
+ * Produces the perception added to each turn's user message so the LLM can
+ * decide what to do next. The provider runs whatever perception sequence it
+ * needs and persists its own artifacts (e.g. screenshots), returning both the
+ * content for the LLM and a record of what it observed.
+ */
+export interface ObserverCapability {
+    /** Assert the underlying target is reachable; throw otherwise. */
+    ensureObservable(): void;
+    /** Capture this turn's observation. */
+    observe(ctx: ObservationContext): Promise<Observation>;
+    /**
+     * Capture a one-off snapshot outside the normal turn cadence. Omit on
+     * providers without a visual snapshot; returns `null` when nothing is
+     * capturable right now.
+     */
+    captureSnapshot?(): Promise<Buffer | null>;
+}
+/** Connection lifecycle, recovery, initialization, and session persistence. */
+export interface LifecycleCapability {
+    initialize(callbacks: TargetInitCallbacks): Promise<void>;
+    /** Whether the underlying target connection is alive. */
+    readonly connected: boolean;
+    /** Whether a thrown error means this provider's target is closed. */
+    isClosedError(error: unknown): boolean;
+    /** Throw if the target exists but is no longer alive (e.g. page closed). */
+    checkAliveOrThrow(): void;
+    /** Attempt recovery after the target is closed. */
+    handleClosed(): Promise<{
+        recovered: true;
+    } | {
+        recovered: false;
+        reason: string;
+    }>;
+    /** Persist platform-specific session state (e.g. browser storage). */
+    persistSessionState(persistence: FlowsPersistence, flowId: string): Promise<void>;
+    /** Current location identifier recorded on tool calls (e.g. page URL). */
+    getCurrentLocation(): string;
+    /** Show the interaction cursor. Optional — omit on platforms without one. */
+    showInteractionCursor?(): Promise<void>;
+    /** Hide the interaction cursor. Optional — omit on platforms without one. */
+    hideInteractionCursor?(): Promise<void>;
+    /**
+     * Force-interrupt any in-flight operation against this target so a cancelled
+     * flow's run loop unblocks at once instead of waiting for the current call to
+     * return. This only interrupts — it does not release the target's resources.
+     * Optional — targets with nothing to interrupt omit it.
+     */
+    interrupt?(): Promise<void>;
+}
+/**
+ * The handle tools act through. The base carries only the discriminant;
+ * concrete providers extend it with their own handle (e.g. web adds its
+ * {@link WebTarget} and inspector).
+ */
+export interface ActionCapability {
+    readonly type: string;
+}
+/**
+ * Location identifier for tool-call records — the target's location, or
+ * `'about:blank'` when there is no target.
+ */
+export declare function currentLocation(provider: TargetProvider | null): string;
+/**
+ * Capture a one-off visual snapshot. Returns `null` when there is no observer
+ * or it cannot produce a snapshot right now (e.g. a flow with no visual target).
+ */
+export declare function captureSnapshot(provider: TargetProvider | null): Promise<Buffer | null>;
+//# sourceMappingURL=TargetProvider.d.ts.map

package/dist/esm/targets/TargetProvider.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentLocation = currentLocation;
+exports.captureSnapshot = captureSnapshot;
+/* ------------------------------------------------------------------ */
+/*  Shared provider reads                                              */
+/*                                                                     */
+/*  Used by both the flow engine and the tool layer so the fallback    */
+/*  semantics live in one place.                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * Location identifier for tool-call records — the target's location, or
+ * `'about:blank'` when there is no target.
+ */
+function currentLocation(provider) {
+    return provider?.lifecycle?.getCurrentLocation() ?? 'about:blank';
+}
+/**
+ * Capture a one-off visual snapshot. Returns `null` when there is no observer
+ * or it cannot produce a snapshot right now (e.g. a flow with no visual target).
+ */
+async function captureSnapshot(provider) {
+    return (await provider?.observer?.captureSnapshot?.()) ?? null;
+}
+//# sourceMappingURL=TargetProvider.js.map

package/dist/esm/targets/TargetRuntime.d.ts

@@ -1,8 +1,8 @@
-import type { TargetInspector } from '../managers/TargetInspector';
 import type { ControlPanel } from '../models/ControlPanel';
 import type { CreateDonobuFlow } from '../models/CreateDonobuFlow';
 import type { FlowMetadata } from '../models/FlowMetadata';
 import type { ProposedToolCall } from '../models/ProposedToolCall';
+import type { TargetProvider } from './TargetProvider';
 /**
  * Encapsulates target-specific lifecycle and configuration for a single flow.
  *
@@ -22,8 +22,11 @@ import type { ProposedToolCall } from '../models/ProposedToolCall';
 export interface TargetRuntime {
     /** Target type identifier for tool filtering (e.g. `'web'`, `'mobile'`). */
     readonly targetType: string;
-    /** Inspector bound to the live session (browser page, mobile device, etc.). */
-    readonly inspector: TargetInspector;
+    /**
+     * The target the flow drives, or `null` for a targetless flow. The web
+     * runtime supplies one. This is the seam the engine and tools consume.
+     */
+    readonly provider: TargetProvider | null;
     /** Control panel for this flow. {@link NoOpControlPanel} if unsupported. */
     readonly controlPanel: ControlPanel;
     /**

package/dist/esm/targets/WebDialogHandler.d.ts

@@ -0,0 +1,14 @@
+import type { Dialog } from 'playwright';
+import type { DialogHost } from '../managers/TargetInspector';
+/**
+ * Builds the Playwright dialog handler for a web target — the callback that
+ * decides how to answer a browser alert/confirm/prompt. It reaches the flow
+ * engine only through the narrow {@link DialogHost} shim, which keeps this web
+ * concern out of the engine itself.
+ *
+ * The returned handler is registered on the browser context and runs as an
+ * async event callback, so it must never leak an exception (that would crash
+ * the process) — everything is wrapped in a try/catch that logs.
+ */
+export declare function createWebDialogHandler(host: DialogHost): (dialog: Dialog) => Promise<void>;
+//# sourceMappingURL=WebDialogHandler.d.ts.map