@mind-harness/mh-browser 0.1.2 → 0.1.4

package/lib/typert.host.js

@@ -44,7 +44,7 @@ const $remote = createTypertRemoteInfo({
         create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
         jsonSchema: {"type":"object","properties":{"status":{"type":"string","enum":["revealed","not-handing-over","no-tab"]}},"required":["status"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":571,"column":9},
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":610,"column":9},
     },
   },
 }, z)
@@ -65,10 +65,17 @@ export const TYPERT = {
         "key": "mhBrowser",
         "exportName": "MhBrowserService",
         "members": [
+          {
+            "kind": "method",
+            "name": "declareAgentViewOrigin",
+            "signature": "declareAgentViewOrigin(origin: string): void",
+            "summary": "Remember an origin whose pages offer Agent Views.",
+            "jsDoc": "/** Remember an origin whose pages offer Agent Views. A missing page does not remove it. */"
+          },
           {
             "kind": "method",
             "name": "open",
-            "signature": "async open( owner: string, items: { url: string; waitFor?: WaitFor }[], signal?: AbortSignal, ): Promise<(PageView | PageError)[]>"
+            "signature": "async open( owner: string, items: { url: string; waitFor?: WaitFor; snapshot?: boolean }[], signal?: AbortSignal, ): Promise<(PageView | PageError)[]>"
           },
           {
             "kind": "method",
@@ -141,7 +148,7 @@ export const TYPERT = {
           {
             "kind": "method",
             "name": "fetch",
-            "signature": "async fetch( url: string, opts?: { accept?: string; ifNoneMatch?: string }, ): Promise<FetchResponseBody | { kind: 'error'; reason: string }>"
+            "signature": "async fetch( url: string, opts?: { accept?: string; ifNoneMatch?: string; signal?: AbortSignal }, ): Promise<FetchResponseBody | { kind: 'error'; reason: string }>"
           },
           {
             "kind": "method",
@@ -161,7 +168,7 @@ export const TYPERT = {
           {
             "kind": "method",
             "name": "act",
-            "signature": "async act( owner: string, tab: string, action: ActAction, signal?: AbortSignal, ): Promise<PageView>"
+            "signature": "async act(owner: string, tab: string, op: PageOp, signal?: AbortSignal): Promise<PageView>"
           },
           {
             "kind": "method",
@@ -183,12 +190,12 @@ export const TYPERT = {
           {
             "kind": "method",
             "name": "invoke",
-            "signature": "invoke( owner: string, page: string, call: InvokeCall, opts?: { signal?: AbortSignal; readFile?: (value: unknown) => Promise<string> }, ): Promise<InvokeSent>"
+            "signature": "invoke( owner: string, _page: string, call: InvokeCall, opts?: { signal?: AbortSignal; readFile?: (value: unknown) => Promise<string> }, ): Promise<InvokeSent>"
           },
           {
             "kind": "method",
             "name": "download",
-            "signature": "async download( owner: string, url: string, root: string, signal?: AbortSignal, ): Promise<Download>",
+            "signature": "async download( _owner: string, url: string, root: string, signal?: AbortSignal, ): Promise<Download>",
             "summary": "Not queued: it opens no tab, and a long body must not hold up the Session's other calls.",
             "jsDoc": "/**\n * Not queued: it opens no tab, and a long body must not hold up the\n * Session's other calls. `root` is the directory the session may write.\n */"
           },
@@ -255,10 +262,6 @@ export const TYPERT = {
           }
         ],
         "types": [
-          {
-            "name": "ActAction",
-            "declaration": "export type ActAction = { kind: 'click'; ref: string; double?: boolean; button?: 'left' | 'right' | 'middle'; modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>; } | { kind: 'select'; ref: string; values: string[]; } | { kind: 'press'; key: string; ref?: string; } | { kind: 'fill'; fields: { ref: string; value: string; }[]; } | { kind: 'upload'; ref: string; files: string[]; } | { kind: 'dialog'; accept: boolean; promptText?: string; } | { kind: 'back'; } | { kind: 'wait'; text?: string; textGone?: string; time?: number; } | { kind: 'look'; };"
-          },
           {
             "name": "ActionResponse",
             "declaration": "export interface ActionResponse {\n    name: string;\n    status?: number;\n    location?: string;\n    mediaType?: string;\n    body?: string;\n    bytes?: number;\n    lost?: boolean;\n}"
@@ -285,19 +288,27 @@ export const TYPERT = {
           },
           {
             "name": "InvokeCall",
-            "declaration": "export interface InvokeCall {\n    name: string;\n    item?: string;\n    input?: Record<string, unknown>;\n    seen: SeenView | 'not-in-context';\n}"
+            "declaration": "export interface InvokeCall {\n    name: string;\n    item?: string;\n    input?: Record<string, unknown>;\n    shown: { url: string; text: string; };\n}"
           },
           {
             "name": "InvokeSent",
             "declaration": "export interface InvokeSent {\n    schemaRejected: boolean;\n    response?: ActionResponse;\n    page: PageView | PageError;\n}"
           },
+          {
+            "name": "Modifier",
+            "declaration": "export type Modifier = 'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift';"
+          },
           {
             "name": "PageError",
             "declaration": "export interface PageError {\n    tab?: TabId;\n    url: string;\n    reason: string;\n}"
           },
+          {
+            "name": "PageOp",
+            "declaration": "export type PageOp = (Target & { kind: 'click'; doubleClick?: boolean; button?: 'left' | 'right' | 'middle'; modifiers?: Modifier[]; }) | (Target & { kind: 'hover'; }) | (Target & { kind: 'select_option'; values: string[]; }) | { kind: 'drag'; startTarget: string; startElement?: string; endTarget: string; endElement?: string; } | (Target & { kind: 'type'; text: string; submit?: boolean; slowly?: boolean; }) | { kind: 'fill_form'; fields: (Target & { name: string; type: 'textbox' | 'checkbox' | 'radio' | 'combobox' | 'slider'; value: string; })[]; } | { kind: 'press_key'; key: string; } | { kind: 'file_upload'; paths?: string[]; } | { kind: 'handle_dialog'; accept: boolean; promptText?: string; } | { kind: 'navigate_back'; } | { kind: 'wait_for'; text?: string; textGone?: string; time?: number; } | { kind: 'snapshot'; target?: string; depth?: number; boxes?: boolean; } | { kind: 'find'; text?: string; regex?: string; maxResults?: number; } | { kind: 'take_screenshot'; element?: string; target?: string; type?: 'png' | 'jpeg' | 'webp'; fullPage?: boolean; scale?: 'css' | 'device'; } | { kind: 'evaluate'; element?: string; target?: string; function: string; callId: string; };"
+          },
           {
             "name": "PageView",
-            "declaration": "export interface PageView {\n    tab: TabId;\n    url: string;\n    title: string;\n    observedAt: string;\n    representation: { kind: 'agent-view'; text: string; version?: string; href?: string; } | { kind: 'snapshot'; text: string; agentViewError?: string; agentView?: { version?: string; }; };\n    fragment?: string;\n    status?: number;\n    mediaType?: string;\n    body?: string;\n    inPresence: boolean;\n    dialog?: Dialog;\n    incomplete?: { load: boolean; pendingRequests: number; };\n    waited?: { met: 'text' | 'textGone' | 'time' | false; seconds: number; };\n    download?: Download;\n}"
+            "declaration": "export interface PageView {\n    tab?: TabId;\n    url: string;\n    title: string;\n    observedAt: string;\n    representation: { kind: 'agent-view'; text: string; version?: string; href?: string; } | { kind: 'snapshot'; text: string; agentViewError?: string; agentView?: { version?: string; }; };\n    fragment?: string;\n    status?: number;\n    mediaType?: string;\n    body?: string;\n    inPresence: boolean;\n    headerOnly?: boolean;\n    dialog?: Dialog;\n    incomplete?: { load: boolean; pendingRequests: number; };\n    waited?: { met: 'text' | 'textGone' | 'time' | false; seconds: number; };\n    download?: Download;\n    summary?: string;\n    detail?: string;\n    writes?: { method: string; origin: string; fromCall: boolean; count: number; }[];\n    shot?: { mediaType: 'image/png' | 'image/jpeg' | 'image/webp'; bytes: Uint8Array; };\n}"
           },
           {
             "name": "PendingOp",
@@ -323,10 +334,6 @@ export const TYPERT = {
             "name": "PresenceSource",
             "declaration": "export type PresenceSource = (typeof PRESENCE_SOURCES)[number];"
           },
-          {
-            "name": "SeenView",
-            "declaration": "export interface SeenView {\n    digest: string;\n    version?: string;\n}"
-          },
           {
             "name": "TabId",
             "declaration": "export type TabId = string;"
@@ -339,6 +346,10 @@ export const TYPERT = {
             "name": "Taken",
             "declaration": "export interface Taken {\n    operations: number;\n    tabs: string[];\n    from: string;\n    to: string;\n    tab?: string;\n}"
           },
+          {
+            "name": "Target",
+            "declaration": "export interface Target {\n    target: string;\n    element?: string;\n}"
+          },
           {
             "name": "TestHooks",
             "declaration": "export interface TestHooks {\n    crash(): Promise<void>;\n    page(owner: string, tab: string): unknown;\n}"

package/lib/typert.remote-client.js

@@ -44,7 +44,7 @@ export const TYPERT_REMOTE = createTypertRemoteInfo({
         create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
         jsonSchema: {"type":"object","properties":{"status":{"type":"string","enum":["revealed","not-handing-over","no-tab"]}},"required":["status"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":571,"column":9},
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":610,"column":9},
     },
   },
 }, z)

package/lib/types/render/envelope.d.ts

@@ -1,8 +1,10 @@
 import type { PageError, PageView, TabInfo } from '../types.ts';
+/** Every element the service writes around site text. */
+export declare const FRAMES: string[];
 /**
- * Escape a closer a site could use to end a frame the service opened. Only
- * its opening `</name` is rewritten, so a closer cut off before `>` is caught
- * and no site text is dropped.
+ * Escape a closer a site could use to end a frame the service opened, and an
+ * opener it could use to pass its text off as one. Only `</name` and `<name`
+ * are rewritten, so a tag cut off before `>` is caught and no site text is dropped.
  */
 export declare function escapeBody(text: string): string;
 /** Escape text the service writes into an attribute. */
@@ -59,11 +61,28 @@ export declare function renderAbsent(input: {
  * `omitInPresence`: the page's body is the same one presence carries, so a
  * page in presence gets only its attributes.
  */
-export declare function renderOutcome(pages: Array<PageView | PageError>, tabs: TabInfo[], closed: string[], screenshot?: string, omitInPresence?: boolean): string;
+export declare function renderOutcome(pages: Array<PageView | PageError>, screenshot?: string, omitInPresence?: boolean): string;
+/** One attached `<tabs>` list, the comparison key for the next result. */
+export interface TabSnap {
+    tabs: {
+        id: string;
+        url: string;
+        presence: boolean;
+        changed: boolean;
+        inUse: boolean;
+    }[];
+    closed: string[];
+}
+export declare function tabSnap(tabs: TabInfo[], closed: string[]): TabSnap;
+/**
+ * Attach the full list when this session has not attached one yet, when the
+ * tab key changed, or when this result closed something. Title is not a change.
+ */
+export declare function tabsChanged(previous: TabSnap | undefined, next: TabSnap): boolean;
 export interface PageReading {
     url: string;
     tab?: string;
-    representation: 'agent-view' | 'snapshot';
+    representation: 'agent-view' | 'snapshot' | 'header';
     version?: string;
     digest?: string;
     /** The `id` the Agent View declares; `browser_invoke` takes it as well as `url`. */

package/lib/types/representation/agent-view.d.ts

@@ -1,5 +1,7 @@
 export declare const AGENT_VIEW_VERSION = "0.1";
 export declare const AGENT_VIEW_ACCEPT = "text/markdown; variant=agent-view";
+/** Accept on the page address when its origin is known to offer Agent Views. */
+export declare const PAGE_ACCEPT = "text/markdown; variant=agent-view, text/html;q=0.9, */*;q=0.8";
 export interface AgentViewRequest {
     method: string;
     url: string;

package/lib/types/representation/agent-view.js

@@ -2,6 +2,8 @@ import { createHash } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 export const AGENT_VIEW_VERSION = '0.1';
 export const AGENT_VIEW_ACCEPT = 'text/markdown; variant=agent-view';
+/** Accept on the page address when its origin is known to offer Agent Views. */
+export const PAGE_ACCEPT = 'text/markdown; variant=agent-view, text/html;q=0.9, */*;q=0.8';
 const FENCE_OPEN = /```agent-view\b/g;
 const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE']);
 const PLACEHOLDER = /\{[^{}]+\}/;

package/lib/types/representation/read.d.ts

@@ -22,6 +22,7 @@ export interface MainDocument {
     mediaType?: string;
     finalUrl: string;
     link?: string;
+    etag?: string;
     body: string;
 }
 type FetchText = (url: string, accept: string, ifNoneMatch?: string) => Promise<FetchResponse>;

package/lib/types/service/actions.d.ts

@@ -1,7 +1,10 @@
-import type { Page } from 'playwright';
-import type { ActAction } from '../types.ts';
-/** Run one snapshot action. Dialog, wait, and look are handled by the service. */
-export declare function runAction(page: Page, action: Exclude<ActAction, {
-    kind: 'dialog' | 'wait' | 'look';
-}>, signal: AbortSignal | undefined): Promise<boolean>;
+import type { Locator, Page } from 'playwright';
+import type { PageOp } from '../types.ts';
+/** A page operation returns a snapshot after it. The rest return one sentence. */
+export declare function showsSnapshot(op: PageOp): boolean;
+/** The sentence for an operation whose result has no snapshot. */
+export declare function summaryOf(op: PageOp): string | undefined;
+/** Run one snapshot action. Dialog, wait, upload, find, and evaluate are handled by the service. */
+export declare function runAction(page: Page, op: PageOp, snapshot: string, signal: AbortSignal | undefined): Promise<boolean>;
+export declare function locate(page: Page, target: string, snapshot: string): Promise<Locator>;
 //# sourceMappingURL=actions.d.ts.map

package/lib/types/service/control.d.ts

@@ -1,19 +1,28 @@
 /**
- * Who holds the browser for one session. Person input outside a service
- * dispatch moves it to the person and aborts the action still waiting.
- * A model handover keeps the hold until hand-back or a stopped call.
+ * Who holds each tab of one session. Person input outside a service dispatch
+ * moves that tab to the person and aborts the action still waiting on it.
+ * A handover that names no tab holds every tab until hand-back.
  */
 export declare class Control {
     private readonly who;
     private readonly holding;
+    /** A handover that named no tab: every tab of the session is the person's. */
+    private readonly blanket;
     private readonly inflight;
     private readonly operations;
     private readonly tabs;
     private readonly since;
     private readonly named;
+    /** Whether the person holds any tab, or a handover is waiting. */
     of(owner: string): 'model' | 'person';
-    /** Abort this session's waiting action when the caller aborts or the person takes over. */
-    link(owner: string, caller: AbortSignal | undefined): {
+    /** The person holds this tab until they hand it back. */
+    ofTab(owner: string, tab: string): 'model' | 'person';
+    /**
+     * Abort this waiting action when the caller aborts, or when the person
+     * takes the tab it is running on. A call with no tab (the request channel)
+     * ends only when its caller aborts.
+     */
+    link(owner: string, caller: AbortSignal | undefined, tab?: string): {
         signal: AbortSignal;
         release(): void;
     };
@@ -37,6 +46,7 @@ export declare class Control {
     takePerson(owner: string): Taken | undefined;
     /** The Session is gone. Its in-flight calls are aborted. */
     forget(owner: string): void;
+    private abort;
     private clear;
 }
 export interface Taken {

package/lib/types/service/evaluate.d.ts

@@ -0,0 +1,36 @@
+import type { Dialog, Locator, Page } from 'playwright';
+export interface WriteNote {
+    method: string;
+    origin: string;
+    fromCall: boolean;
+}
+/** Write requests grouped by method, target site, and who sent them. */
+export interface WriteCount extends WriteNote {
+    count: number;
+}
+export type Evaluated = {
+    kind: 'value';
+    value: string;
+    writes: WriteCount[];
+} | {
+    kind: 'navigated';
+    writes: WriteCount[];
+} | {
+    kind: 'dialog';
+    dialog: Dialog;
+    writes: WriteCount[];
+} | {
+    kind: 'stopped';
+    writes: WriteCount[];
+};
+/**
+ * Run the expression in the page and collect write requests.
+ * A request is from this call when its initiator stack, including parents,
+ * has a frame from the sourceURL marker. Anything else is contemporaneous.
+ * GET, HEAD, and OPTIONS are not writes. A dialog, a stop, or a navigation
+ * ends the wait; requests already sent are reported either way.
+ */
+export declare function evaluateMarked(page: Page, source: string, target: Locator | undefined, callId: string, signal: AbortSignal | undefined, dialog: Promise<Dialog>): Promise<Evaluated>;
+/** One line per group: `POST https://site × 2 (this call)`. */
+export declare function formatWrites(writes: readonly WriteCount[]): string;
+//# sourceMappingURL=evaluate.d.ts.map

package/lib/types/service/find.d.ts

@@ -0,0 +1,7 @@
+/** Search one snapshot. The header and the miss sentence are what the model reads. */
+export declare function findInSnapshot(snapshot: string, query: {
+    text?: string;
+    regex?: string;
+    maxResults?: number;
+}): string;
+//# sourceMappingURL=find.d.ts.map

package/lib/types/service/invoke.d.ts

@@ -20,12 +20,11 @@ export type SendResult = {
     kind: 'lost';
 };
 export interface InvokeHost {
-    idleView(url: string): Promise<PageView | undefined>;
     open(url: string): Promise<PageView | PageError>;
-    navigate(tab: string, url: string): Promise<PageView | PageError>;
-    reload(url: string, tab: string): Promise<PageView | PageError>;
+    /** Reload other idle tabs on this address; an occupied one is left, marked changed. */
+    refreshIdle(url: string, exceptTab: string | undefined): Promise<void>;
     send(request: SendRequest): Promise<SendResult>;
     readFile(value: unknown): Promise<string>;
 }
-export declare function runInvoke(host: InvokeHost, pageUrl: string, call: InvokeCall): Promise<InvokeSent>;
+export declare function runInvoke(host: InvokeHost, call: InvokeCall): Promise<InvokeSent>;
 //# sourceMappingURL=invoke.d.ts.map

package/lib/types/service/service.d.ts

@@ -3,7 +3,7 @@ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { BrowserConfig } from '../config.ts';
 import type { HeldPage, PresenceReceipt, PresenceRecord, PresenceSource } from '../presence/record.ts';
 import type { PendingOp } from '../presence/fold.ts';
-import type { ActAction, Download, FetchResponseBody, InvokeCall, InvokeSent, PageError, PageView, TabInfo, WaitFor } from '../types.ts';
+import type { Download, FetchResponseBody, InvokeCall, InvokeSent, PageError, PageOp, PageView, TabInfo, WaitFor } from '../types.ts';
 import { type Taken } from './control.ts';
 import { testHooks, type TestHooks } from './test-hooks.ts';
 declare module '@deepseek-ai/cordis' {
@@ -46,10 +46,17 @@ export declare class MhBrowserService extends TypertRemoteService {
     private readonly workspaces;
     private readonly control;
     private readonly personTouch;
+    /** Origins that have served a readable Agent View. Memory only; a restart clears it. */
+    private readonly agentViewOrigins;
+    /** The last Agent View read for a page address, so a later read can send If-None-Match. */
+    private readonly documents;
     constructor(ctx: Context, config: BrowserConfig);
+    /** Remember an origin whose pages offer Agent Views. A missing page does not remove it. */
+    declareAgentViewOrigin(origin: string): void;
     open(owner: string, items: {
         url: string;
         waitFor?: WaitFor;
+        snapshot?: boolean;
     }[], signal?: AbortSignal): Promise<(PageView | PageError)[]>;
     view(owner: string, tab: string, signal?: AbortSignal): Promise<PageView | PageError>;
     /** Pages whose current representation is already in the model's presence. */
@@ -91,6 +98,7 @@ export declare class MhBrowserService extends TypertRemoteService {
     fetch(url: string, opts?: {
         accept?: string;
         ifNoneMatch?: string;
+        signal?: AbortSignal;
     }): Promise<FetchResponseBody | {
         kind: 'error';
         reason: string;
@@ -98,12 +106,12 @@ export declare class MhBrowserService extends TypertRemoteService {
     pushPath(owner: string, tab: string, path: string): Promise<void>;
     started(): Promise<void>;
     [testHooks](): TestHooks;
-    act(owner: string, tab: string, action: ActAction, signal?: AbortSignal): Promise<PageView>;
+    act(owner: string, tab: string, op: PageOp, signal?: AbortSignal): Promise<PageView>;
     holdHandover(owner: string, tab: string): void;
     releaseHandover(owner: string): void;
     /** `undefined` when no screenshot can be taken now: a dialog is open, or the page refused. */
     capture(owner: string, tab: string, signal?: AbortSignal): Promise<Uint8Array | undefined>;
-    invoke(owner: string, page: string, call: InvokeCall, opts?: {
+    invoke(owner: string, _page: string, call: InvokeCall, opts?: {
         signal?: AbortSignal;
         readFile?: (value: unknown) => Promise<string>;
     }): Promise<InvokeSent>;
@@ -111,7 +119,7 @@ export declare class MhBrowserService extends TypertRemoteService {
      * Not queued: it opens no tab, and a long body must not hold up the
      * Session's other calls. `root` is the directory the session may write.
      */
-    download(owner: string, url: string, root: string, signal?: AbortSignal): Promise<Download>;
+    download(_owner: string, url: string, root: string, signal?: AbortSignal): Promise<Download>;
     controlOf(owner: string): 'model' | 'person';
     /** Presence registers this. A hand-back calls it with the touched presence pages. */
     bindPersonTouch(fn: (owner: string, urls: string[]) => void): () => void;
@@ -140,8 +148,44 @@ export declare class MhBrowserService extends TypertRemoteService {
      * hand-back. A handover that is still waiting on its card is not.
      */
     takePersonHandback(owner: string): HandBack | undefined;
+    /**
+     * Read one address. A known origin is tried on the request channel first.
+     * A readable Agent View found on a tab this call opened is returned without
+     * the tab, and that tab is not listed as closed.
+     */
+    private openAddress;
+    /** A tab this call opened can be closed again unless the person took it or it holds input. */
+    private closable;
+    private knownOrigin;
+    private rememberOrigin;
+    /** A readable Agent View puts its origin on the list and keeps the document for the next read. */
+    private keepAgentView;
+    /**
+     * Read a known origin without a tab. `undefined` means this page has to be
+     * opened in a tab: nothing declared, the declaration could not be read, or
+     * the request failed. The origin stays on the list either way. A stop
+     * ends the read without falling back to a tab.
+     */
+    private readKnown;
+    /** One page from a document, with no tab. */
+    private pageOfShown;
+    /**
+     * GET that follows same-origin redirects only. `undefined` when it cannot.
+     * A body that is neither text nor an Agent View is not read: the page then
+     * goes to a tab, which loads it anyway.
+     */
+    private fetchSameOrigin;
     private openOne;
     private perform;
+    /**
+     * `browser_evaluate`. A dialog the function opens is held like any other; a
+     * stop or a takeover ends the wait and still reports the writes already sent.
+     */
+    private evaluateOn;
+    private uploadHeld;
+    private shoot;
+    /** A snapshot limited to a target, a depth, or boxes. Refs still resolve against the full one. */
+    private scopedSnapshot;
     /** A file chooser the action opened. The tab stays in use until it navigates. */
     private chooserHeld;
     private refreshSnapshot;
@@ -151,18 +195,21 @@ export declare class MhBrowserService extends TypertRemoteService {
     private fetchForRead;
     private aria;
     private pageFromShown;
-    /** Read one presence page. A tab opened only for this read is closed again. */
+    /**
+     * Read one presence page. A known origin is read on the request channel,
+     * with If-None-Match when the document was read before. Anything else uses
+     * a tab already on the address, or opens one and closes it again.
+     */
     private observePresence;
     private tabOn;
     private refreshView;
-    private idleView;
-    /** The most recently touched idle tab on this address. */
+    /** The most recently touched idle tab on this address. A tab the person holds is left alone. */
     private idleTabOn;
     /** Only Session windows are capped; the person's window is theirs to close. */
     private enforceCap;
-    private navigateOwned;
+    /** Other tabs on this address: idle ones reload, occupied or taken ones are marked. */
+    private refreshIdle;
     private navigateTab;
-    private reloadSame;
     private sendAction;
     private saveResponse;
     private attachDownload;

package/lib/types/service/windows.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserContext, Dialog, Download, Page } from 'playwright';
+import type { BrowserContext, Dialog, Download, FileChooser, Page } from 'playwright';
 import { type OwnerId, type TabId, type TabInfo } from '../types.ts';
 export interface LiveTab {
     id: TabId;
@@ -17,6 +17,8 @@ export interface LiveTab {
     inputHeld: boolean;
     /** An unaccepted dialog keeps the tab occupied across navigations. */
     dialogHeld: boolean;
+    /** A file chooser opened by an action, until upload or navigation. */
+    fileChooser: FileChooser | undefined;
     /** `browser_handover` named this tab and the person has not handed it back. */
     handoverHeld: boolean;
     inPresence: boolean;
@@ -127,8 +129,11 @@ export declare class Windows {
     openBlank(owner: OwnerId): Promise<LiveTab>;
     private createTab;
     private keep;
-    /** Close one tab the service opened for a presence check. */
-    closeTab(tab: LiveTab, note: string): Promise<void>;
+    /**
+     * Close one tab. `note` is listed in the next `<tabs>` block. A tab the
+     * model was never shown (an Agent View discovered on a new tab) omits it.
+     */
+    closeTab(tab: LiveTab, note?: string): Promise<void>;
     closeOwner(owner: OwnerId): Promise<void>;
     private closePage;
     /** A tab leaves the registry. The window closes with its last tab. */

package/lib/types/tools/delivery.d.ts

@@ -9,8 +9,8 @@ export interface Delivery {
     /** The `id` its Agent View declares. A log written before it was recorded has none. */
     id?: string;
     callId?: string;
-    /** Cleared once a prune shadows it, the surface replaces it, or a summary compacts it. */
-    inContext: boolean;
+    /** The page body the model was shown. Absent when the result carried only a header. */
+    text?: string;
     kind: 'tool' | 'presence';
 }
 /** What the model was shown in this session. Plain JSON: it is a session projection state. */
@@ -30,11 +30,9 @@ export declare const META_BY = "mh-browser";
 export declare const NOT_DELIVERED_REASON = "this address was not shown to you in this session";
 export declare function initDeliveries(): DeliveryState;
 /**
- * One event folded into the delivery record. A tool result shadowed by
- * `compaction/prune` or replaced on the surface is out of context, and its
- * replacement is not a new delivery; a summary puts everything before it out
- * of context, presence reminders included: the replacement baseline that
- * follows the summary is the delivery that counts.
+ * One event folded into the delivery record. Compaction does not revoke a
+ * delivery. A later result with the same call id is the replacement a prune
+ * appends, so it does not replace the text the model was shown.
  */
 export declare function applyDelivery(state: DeliveryState, event: LogEvent): DeliveryState;
 export declare function foldDeliveries(events: readonly LogEvent[]): DeliveryState;
@@ -42,18 +40,18 @@ export declare function foldDeliveries(events: readonly LogEvent[]): DeliverySta
  * The Agent View of this address the model saw last, and whether it is still
  * in context. A page shown only as a snapshot has no Agent View digest.
  */
-export declare function latestSeen(state: DeliveryState, url: string): SeenView | 'not-in-context' | undefined;
+export declare function latestSeen(state: DeliveryState, url: string): SeenView | undefined;
 export type ResolvedPage = {
     url: string;
-    seen: SeenView | 'not-in-context';
+    text: string;
 } | {
     ambiguous: string[];
 };
 /**
  * The document `page` names: the one shown at that address, else the one whose
  * Agent View declares that `id`. One `id` can name several documents, such as
- * the pages of a collection; when more than one is in context and they
- * differ, the caller must pick an address.
+ * the pages of a collection; when they differ, the caller must pick an address.
+ * `text` is the body the model was shown for that document.
  */
 export declare function resolvePage(state: DeliveryState, page: string): ResolvedPage | undefined;
 /**

package/lib/types/tools/page-ops.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+export declare const PAGE_OPERATION_NAMES: readonly ["browser_click", "browser_hover", "browser_select_option", "browser_drag", "browser_type", "browser_fill_form", "browser_press_key", "browser_file_upload", "browser_handle_dialog", "browser_navigate_back", "browser_wait_for", "browser_snapshot", "browser_find", "browser_take_screenshot", "browser_evaluate"];
+export declare function pageOperationTools(ctx: Context): ToolDefinition[];
+export declare function pageOperationTool(ctx: Context, name: string): ToolDefinition;
+//# sourceMappingURL=page-ops.d.ts.map

package/lib/types/tools/paths.d.ts

@@ -1,3 +1,16 @@
+import type { WriteTarget } from '../service/service.ts';
 /** Resolve upload paths and reject anything outside the session's cwd. */
 export declare function filesInWorkspace(cwd: string | undefined, files: string[]): Promise<string[]>;
+/** Refuse a filename that leaves the session's write root, without creating it. */
+export declare function assertInside(target: WriteTarget, filename: string): Promise<void>;
+/**
+ * Write `filename` under the session's write root. A path that leaves the
+ * root is refused, through a symbolic link as well: the deepest existing
+ * directory is checked before any is created, and the file itself is not
+ * followed if it is a link.
+ */
+export declare function writeInside(target: WriteTarget, filename: string, data: string | Uint8Array): Promise<{
+    path: string;
+    bytes: number;
+}>;
 //# sourceMappingURL=paths.d.ts.map

package/lib/types/tools/tab-log.d.ts

@@ -1,15 +1,29 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { LogReader } from '../projections.ts';
+import { type TabSnap } from '../render/envelope.ts';
 import type { ToolSession } from './session.ts';
-/** Tabs an mh-browser result named and no later result reported closed. Plain JSON: a session projection state. */
+/**
+ * Tabs an mh-browser result named, the tab of the latest result, and the last
+ * `<tabs>` list attached. Plain JSON: a session projection state.
+ * A log written before `snap` existed has none, so the next result attaches the full list.
+ */
 export interface TabLogState {
     open: string[];
+    lastTab?: string;
+    snap?: TabSnap;
 }
 export declare function initTabLog(): TabLogState;
 export declare function applyTabLog(state: TabLogState, event: {
     type: string;
     data: unknown;
+    surfaceOp?: unknown;
 }): TabLogState;
+/** The `<tabs>` suffix for this result, and the snap to store when it is attached. */
+export declare function tabBlock(ctx: Context, reader: LogReader, session: ToolSession): {
+    suffix: string;
+    closed: string[];
+    snap?: TabSnap;
+};
 /**
  * The closed notes for this result: the service's own, then each tab an
  * earlier result named that is gone without a note, as after a browser restart.