dsh-builtin-browser 0.4.1 → 0.4.5

package/lib/browser-electron/provider.d.ts

@@ -20,8 +20,13 @@ export interface ElectronBrowserViewHost {
      * Create a new browser view and return a handle to its webContents-like
      * surface. The host owns windowing (adding the view to the window, sizing,
      * removal); the provider owns CDP-driven behavior.
+     * @param owner - the conversation this view serves. A host shared by several conversations
+     *   needs it to keep one conversation's page out of another's; a host with one conversation per
+     *   process may ignore it. It is per VIEW and not per host on purpose: the desktop's host is a
+     *   single instance that every conversation runs through, so an owner held there would be one
+     *   conversation's id applied to all of them.
      */
-    createView(): ElectronViewHandle;
+    createView(owner?: string): ElectronViewHandle;
     /**
      * Destroy a view created by this host. Called on session close; idempotent
      * for an already-destroyed view.
@@ -61,6 +66,18 @@ export interface ElectronBrowserViewHost {
      * of failing only at first use.
      */
     available?(): boolean;
+    /**
+     * Tell the human that a toolbar action the agent could not complete has failed.
+     *
+     * Optional. Declared rather than reached through a cast because this is what issue #16 was:
+     * the call used to be unbound, so `this` inside the host's implementation was undefined and
+     * its first statement threw — inside an async catch, which turned it into an unhandled
+     * rejection that took the whole DSH process down. A declared member is checkable; a cast is
+     * not.
+     * @param windowId - the window the action came from.
+     * @param message - what to show the human.
+     */
+    notifyUserActionError?(windowId: string, message: string): void;
     /**
      * Optional: associate a view with a window group. Views grouped under the
      * same `windowId` share one window (one window per browser session); a host
@@ -96,7 +113,12 @@ export interface ElectronBrowserViewHost {
      * (settings: ui.closeWithSession) has to be asked for explicitly there.
      * @returns a promise that settles once the release was attempted.
      */
-    releasePage?(): Promise<void>;
+    /**
+     * Release this carrier's browser pages for one conversation.
+     * @param owner - the conversation whose pages to close. Omit to close every conversation's,
+     *   which is only correct from a teardown that is itself global.
+     */
+    releasePage?(owner?: string): Promise<void>;
     /**
      * Fold the carrier's presentation away while keeping the page alive.
      *
@@ -175,6 +197,42 @@ export interface ElectronViewHandle {
      * then behaves exactly as before.
      */
     focus?(): Promise<void>;
+    /**
+     * Save a URL straight to disk, when the backing view can do that itself.
+     *
+     * Optional. Declared here rather than reached through a structural cast at the call site:
+     * a cast tells the compiler nothing, so a host that implements the interface without this
+     * method compiles and then silently does nothing.
+     * @param url - the URL to fetch.
+     * @param savePath - where to write it.
+     */
+    download?(url: string, savePath: string): Promise<void>;
+    /**
+     * Export this view's cookies. Optional; see {@link download} for why it is declared.
+     * @returns the cookies, scoped to the view's own page.
+     */
+    flushAuth?(): Promise<readonly ExportedCookie[]>;
+    /**
+     * Import cookies into this view. Optional.
+     * @param cookies - the cookies to write.
+     * @returns how many were accepted.
+     */
+    restoreAuth?(cookies: readonly ExportedCookie[]): Promise<number>;
+    /**
+     * Capture this view natively, returning the image and its measured size.
+     *
+     * Optional. The size is part of the contract because the caller's own tool schema declares
+     * `width`/`height`; a host that can measure the image should say so here rather than leaving
+     * the provider to guess.
+     * @param opts - format, quality and downscale bounds.
+     * @returns the encoded image and the pixel size the caller will receive.
+     */
+    capture?(opts?: ScreenshotOptions): Promise<{
+        base64: string;
+        mime: string;
+        width?: number;
+        height?: number;
+    }>;
 }
 /** Provider config: navigation admission defaults and snapshot caps. */
 export interface ElectronBrowserProviderConfig {
@@ -204,7 +262,16 @@ export interface ElectronBrowserProviderConfig {
     readonly settings?: () => BrowserSettings;
     /** Maximum snapshot elements before truncation. Default 60. */
     readonly snapshotMaxElements?: number;
-    /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+    /**
+     * Explicit content cap, overriding the per-format default when set.
+     *
+     * Honoured again, and it is worth saying why that is a fix rather than a feature: this was
+     * `config.contentMaxChars ?? 100_000`, one number for every format, and when the caps became
+     * per-format (html and json 50 000, otherwise 20 000) the field was left assigned and never
+     * read. A configuration knob that silently does nothing is worse than no knob — it is an
+     * operator's decision that quietly went nowhere. Leaving it unset means the per-format
+     * default; setting it means the operator meant it.
+     */
     readonly contentMaxChars?: number;
     /**
      * Directory `browser_download` save paths must resolve inside (prevents a
@@ -390,8 +457,26 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * Chromium drops `Input.*` events for a view with no display surface, so this
      * runs before click/type/key and fails loudly (BROWSER_VIEW_NOT_PRESENTED)
      * rather than reporting a success the page never saw.
+     * @param s - the session whose active view must be presented.
+     * @param signal - optional cancellation.
+     * @returns the view the session's active tab has AFTER the presentation barrier.
      */
     private present;
+    /**
+     * Refuse to send synthesized input to a view that is no longer the one it was located
+     * against.
+     *
+     * `locateHandle` was captured before a page-side locate that can consume its whole
+     * 10s budget; the session's active tab is re-read afterwards. If they differ, the human
+     * switched tabs mid-flight (the product's whole point is that they can take over), and
+     * the coordinates belong to one page while the dispatch would go to another. Comparing
+     * the handles turns that into a loud, retryable error instead of input the caller
+     * believes landed.
+     * @param session - the session id, for the message.
+     * @param locateHandle - the view the locate ran in.
+     * @param liveHandle - the view that is active now.
+     */
+    private assertSameView;
     /**
      * Give the view web focus before synthesizing keyboard input.
      *
@@ -498,6 +583,22 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * of text (`a@href` yields an absolute URL).
      */
     scrape(session: BrowserSessionId, request: BrowserScrapeRequest, signal?: AbortSignal): Promise<BrowserScrapeResult>;
+    /**
+     * Refuse an action the settings have switched off.
+     *
+     * These switches belong to the OPERATOR. The settings document is written through the
+     * plugin's own panel and no tool can reach it, so — unlike `browser_restrict`, which the
+     * model owns and can lift at will — a refusal here stands for as long as the setting does.
+     * That is the point of them: a deployment can take page-script execution, downloads, or
+     * login-state writes off the table without relying on the model's cooperation.
+     *
+     * Read through `settingsSource` on every call rather than captured at construction, so
+     * flipping a switch applies to the next command instead of the next restart — the same
+     * rule the credentials gate follows.
+     * @param action - which switch to consult.
+     * @throws BrowserError when that switch is off.
+     */
+    private assertActionAllowed;
     /**
      * Admit a caller-supplied save path for a file the browser writes to disk.
      * ONE gate for both `browser_download` and `browser_screenshot`: the path
@@ -540,6 +641,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<{
         readonly dataUrl: string;
         readonly path?: string;
+        readonly width?: number;
+        readonly height?: number;
     }>;
     /**
      * Build the data URL and optionally write the image to disk. The caller's