@mehmoodqureshi/chrome-mcp 0.6.6 → 0.7.0

package/dist/src/executor/extension-executor.js

@@ -22,6 +22,15 @@ const workspace_1 = require("../bridge/workspace");
  * pre-check precision for half the traffic — never enforcement itself.
  */
 const ACTIVE_URL_TTL_MS = 1_000;
+/** Flatten frame options into the params a wire command carries. */
+function frameParams(o) {
+    if (!o)
+        return {};
+    return {
+        ...(o.frameId !== undefined ? { frameId: o.frameId } : {}),
+        ...(o.allFrames ? { allFrames: true } : {}),
+    };
+}
 /** Flatten a Target into the params a wire command carries. */
 function targetParams(t) {
     if (!t)
@@ -107,36 +116,36 @@ class ExtensionExecutor {
     }
     // -- interaction --------------------------------------------------------
     async click(t, opts) {
-        return (await this.send('click', { ...targetParams(t), button: opts?.button, clickCount: opts?.clickCount, trusted: opts?.trusted }, { tabId: opts?.tabId }));
+        return (await this.send('click', { ...targetParams(t), ...frameParams(opts), button: opts?.button, clickCount: opts?.clickCount, trusted: opts?.trusted }, { tabId: opts?.tabId }));
     }
     async type(t, text, opts) {
-        return (await this.send('type', { ...targetParams(t), text, clear: opts?.clear, pressEnter: opts?.pressEnter, keyEvents: opts?.keyEvents, trusted: opts?.trusted }, { tabId: opts?.tabId }));
+        return (await this.send('type', { ...targetParams(t), ...frameParams(opts), text, clear: opts?.clear, pressEnter: opts?.pressEnter, keyEvents: opts?.keyEvents, trusted: opts?.trusted }, { tabId: opts?.tabId }));
     }
     async selectOption(t, values, opts) {
-        return (await this.send('select_option', { ...targetParams(t), values }, { tabId: opts?.tabId }));
+        return (await this.send('select_option', { ...targetParams(t), ...frameParams(opts), values }, { tabId: opts?.tabId }));
     }
     async fill(t, value, opts) {
         // No dedicated wire method: a cleared insertText is the fill primitive.
-        return (await this.send('type', { ...targetParams(t), text: value, clear: true, keyEvents: false }, { tabId: opts?.tabId }));
+        return (await this.send('type', { ...targetParams(t), ...frameParams(opts), text: value, clear: true, keyEvents: false }, { tabId: opts?.tabId }));
     }
     async press(key, opts) {
         return (await this.send('press', { key, modifiers: opts?.modifiers }, { tabId: opts?.tabId }));
     }
     async hover(t, opts) {
-        return (await this.send('hover', { ...targetParams(t) }, { tabId: opts?.tabId }));
+        return (await this.send('hover', { ...targetParams(t), ...frameParams(opts) }, { tabId: opts?.tabId }));
     }
     async scroll(opts) {
-        return (await this.send('scroll', { x: opts.x, y: opts.y, deltaX: opts.deltaX, deltaY: opts.deltaY, ...targetParams(opts.target) }, { tabId: opts.tabId }));
+        return (await this.send('scroll', { x: opts.x, y: opts.y, deltaX: opts.deltaX, deltaY: opts.deltaY, ...targetParams(opts.target), ...frameParams(opts) }, { tabId: opts.tabId }));
     }
     // -- read ---------------------------------------------------------------
     async getText(t, opts) {
-        return (await this.send('get_text', { ...targetParams(t) }, { tabId: opts?.tabId }));
+        return (await this.send('get_text', { ...targetParams(t), ...frameParams(opts) }, { tabId: opts?.tabId }));
     }
     async getHtml(t, opts) {
-        return (await this.send('get_html', { ...targetParams(t), outer: opts?.outer }, { tabId: opts?.tabId }));
+        return (await this.send('get_html', { ...targetParams(t), ...frameParams(opts), outer: opts?.outer }, { tabId: opts?.tabId }));
     }
     async snapshot(opts) {
-        return (await this.send('snapshot', { interactiveOnly: opts?.interactiveOnly, max: opts?.max }, { tabId: opts?.tabId }));
+        return (await this.send('snapshot', { interactiveOnly: opts?.interactiveOnly, max: opts?.max, ...frameParams(opts) }, { tabId: opts?.tabId }));
     }
     async getCookies(opts) {
         return (await this.send('get_cookies', { url: opts?.url }, { tabId: opts?.tabId }));
@@ -145,14 +154,14 @@ class ExtensionExecutor {
         return (await this.send('storage', { op: args.op, key: args.key, value: args.value, session: args.session }, { tabId: args.tabId }));
     }
     async screenshot(opts) {
-        return (await this.send('screenshot', { fullPage: opts?.fullPage, ...targetParams(opts?.target) }, { tabId: opts?.tabId }));
+        return (await this.send('screenshot', { fullPage: opts?.fullPage, ...targetParams(opts?.target), ...frameParams(opts) }, { tabId: opts?.tabId }));
     }
     async eval(expression, opts) {
-        const result = (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise }, { tabId: opts?.tabId }));
+        const result = (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise, ...frameParams(opts) }, { tabId: opts?.tabId }));
         return (0, types_1.truncateEvalResult)(result);
     }
     async waitFor(opts) {
-        return (await this.send('wait_for', { selector: opts.selector, textContains: opts.textContains, gone: opts.gone, timeoutMs: opts.timeoutMs }, { tabId: opts.tabId, timeoutMs: opts.timeoutMs ? opts.timeoutMs + 5_000 : undefined }));
+        return (await this.send('wait_for', { selector: opts.selector, textContains: opts.textContains, gone: opts.gone, timeoutMs: opts.timeoutMs, ...frameParams(opts) }, { tabId: opts.tabId, timeoutMs: opts.timeoutMs ? opts.timeoutMs + 5_000 : undefined }));
     }
     // -- privileged ---------------------------------------------------------
     async download(args) {
@@ -176,6 +185,38 @@ class ExtensionExecutor {
     async uploadFile(t, files, opts) {
         return (await this.send('upload_file', { ...targetParams(t), files }, { tabId: opts?.tabId }));
     }
+    // -- optional capabilities ----------------------------------------------
+    async framesList(opts) {
+        const res = (await this.send('frames_list', {}, { tabId: opts?.tabId }));
+        return res.frames ?? [];
+    }
+    async observers(args) {
+        return (await this.send('observers', {
+            ...frameParams(args),
+            console: args.console,
+            network: args.network,
+            dialogs: args.dialogs,
+            sinceSeq: args.sinceSeq,
+            limit: args.limit,
+            clear: args.clear,
+            setPolicy: args.setPolicy,
+            promptText: args.promptText,
+            includeResources: args.includeResources,
+        }, { tabId: args.tabId }));
+    }
+    async printPdf(opts) {
+        return (await this.send('print_pdf', {
+            landscape: opts?.landscape,
+            printBackground: opts?.printBackground,
+            scale: opts?.scale,
+            paperWidth: opts?.paperWidth,
+            paperHeight: opts?.paperHeight,
+            pageRanges: opts?.pageRanges,
+            preferCSSPageSize: opts?.preferCSSPageSize,
+        }, 
+        // A large page can take a while through Chrome's print pipeline.
+        { tabId: opts?.tabId, timeoutMs: 60_000 }));
+    }
 }
 exports.ExtensionExecutor = ExtensionExecutor;
 //# sourceMappingURL=extension-executor.js.map

package/dist/src/executor/stub-executor.d.ts

@@ -7,7 +7,7 @@
  *   2. Drives the dispatch/policy/envelope tests with deterministic, canned
  *      values (and a couple of forced-failure switches).
  */
-import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type NavResult, type ScreenshotResult, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult } from './types';
+import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type FrameInfo, type NavResult, type ObserverArgs, type ObserverReadResult, type PdfResult, type ScreenshotResult, type SnapshotNode, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult } from './types';
 export interface StubOptions {
     /** URL of the (single) active tab — used to exercise the domain policy gate. */
     activeUrl?: string;
@@ -32,6 +32,31 @@ export interface StubOptions {
     /** When true, tabs exist but none is flagged active — the case the gate used to
      *  paper over by silently gating against `tabs[0]`. */
     noActiveTab?: boolean;
+    /** Text returned by `getText`. Set it large to exercise the output cap. */
+    textPayload?: string;
+    /** HTML returned by `getHtml`. Set it large to exercise the output cap. */
+    htmlPayload?: string;
+    /**
+     * How many of the first content reads reject with `EXTENSION_DISCONNECTED`
+     * before one succeeds — models MV3 recycling the service worker mid-command,
+     * the fault the dispatch layer retries once.
+     */
+    disconnectReads?: number;
+    /**
+     * Same, but for the mutating `type` path. Mutations are deliberately NOT
+     * retried — repeating a write could submit a form twice — so a test can assert
+     * exactly one attempt was made.
+     */
+    disconnectWrites?: number;
+    /** Nodes the stub snapshot reports — lets a test drive locator resolution and
+     *  the snapshot diff without a browser. Mutate between calls to model a page
+     *  changing under an action. */
+    snapshotNodes?: SnapshotNode[];
+    /** Frames the stub reports for `frames_list`. */
+    frames?: FrameInfo[];
+    /** What the in-page observers return. Absent = the hook is not installed,
+     *  which is the case the tools must report clearly rather than as an empty list. */
+    observers?: ObserverReadResult;
 }
 export declare class StubExecutor implements Executor {
     readonly backend: BackendKind;
@@ -39,15 +64,31 @@ export declare class StubExecutor implements Executor {
     private readonly evalThrows;
     private readonly tabsListThrows;
     private readonly noTabs;
+    private readonly textPayload;
+    private readonly htmlPayload;
+    private remainingDisconnects;
+    private remainingWriteDisconnects;
     private readonly blankTabUrl;
     private readonly cached;
     private readonly backgroundTabs;
     private readonly noActiveTab;
+    /** Mutable so a test can change the page between two snapshots. */
+    snapshotNodes: SnapshotNode[];
+    private readonly frames;
+    private readonly observerState?;
+    /** The last observer args received, so a test can assert what was requested. */
+    lastObserverArgs?: ObserverArgs;
     /** How many times the gate actually asked for the tab list — the round-trip
      *  counter the caching path exists to keep at zero. */
     tabsListCalls: number;
     private ready;
     constructor(opts?: StubOptions);
+    /** Fail this read if a scripted disconnect is still pending, then consume it. */
+    private maybeDisconnect;
+    /** How many scripted disconnects are left (lets a test assert one was consumed). */
+    get pendingDisconnects(): number;
+    /** Same for the write path — a mutating call must consume exactly one. */
+    get pendingWriteDisconnects(): number;
     private tab;
     cachedActiveUrl(): string | null;
     status(): ExecutorStatus;
@@ -98,4 +139,7 @@ export declare class StubExecutor implements Executor {
         suggestedName?: string;
     }): Promise<DownloadResult>;
     uploadFile(): Promise<ActionOk>;
+    framesList(): Promise<FrameInfo[]>;
+    observers(args: ObserverArgs): Promise<ObserverReadResult>;
+    printPdf(): Promise<PdfResult>;
 }

package/dist/src/executor/stub-executor.js

@@ -20,10 +20,20 @@ class StubExecutor {
     evalThrows;
     tabsListThrows;
     noTabs;
+    textPayload;
+    htmlPayload;
+    remainingDisconnects;
+    remainingWriteDisconnects;
     blankTabUrl;
     cached;
     backgroundTabs;
     noActiveTab;
+    /** Mutable so a test can change the page between two snapshots. */
+    snapshotNodes;
+    frames;
+    observerState;
+    /** The last observer args received, so a test can assert what was requested. */
+    lastObserverArgs;
     /** How many times the gate actually asked for the tab list — the round-trip
      *  counter the caching path exists to keep at zero. */
     tabsListCalls = 0;
@@ -37,6 +47,28 @@ class StubExecutor {
         this.cached = opts.cachedUrl ?? null;
         this.backgroundTabs = opts.backgroundTabs ?? [];
         this.noActiveTab = opts.noActiveTab ?? false;
+        this.textPayload = opts.textPayload ?? 'stub text';
+        this.htmlPayload = opts.htmlPayload ?? '<html><body><a href="https://example.com">Example</a></body></html>';
+        this.remainingDisconnects = opts.disconnectReads ?? 0;
+        this.remainingWriteDisconnects = opts.disconnectWrites ?? 0;
+        this.snapshotNodes = opts.snapshotNodes ?? [{ ref: 'e1', role: 'link', name: 'Example', tag: 'a' }];
+        this.frames = opts.frames ?? [{ frameId: 0, top: true, url: opts.activeUrl ?? 'about:blank', title: 'Stub Page' }];
+        this.observerState = opts.observers;
+    }
+    /** Fail this read if a scripted disconnect is still pending, then consume it. */
+    maybeDisconnect() {
+        if (this.remainingDisconnects <= 0)
+            return;
+        this.remainingDisconnects--;
+        throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub: service worker recycled mid-command');
+    }
+    /** How many scripted disconnects are left (lets a test assert one was consumed). */
+    get pendingDisconnects() {
+        return this.remainingDisconnects;
+    }
+    /** Same for the write path — a mutating call must consume exactly one. */
+    get pendingWriteDisconnects() {
+        return this.remainingWriteDisconnects;
     }
     tab() {
         return {
@@ -113,6 +145,10 @@ class StubExecutor {
         return ok;
     }
     async type() {
+        if (this.remainingWriteDisconnects > 0) {
+            this.remainingWriteDisconnects--;
+            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub: service worker recycled mid-command');
+        }
         return ok;
     }
     async fill() {
@@ -131,18 +167,15 @@ class StubExecutor {
         return ok;
     }
     async getText(_t) {
-        return { text: 'stub text', ref: 'el_stub_1' };
+        this.maybeDisconnect();
+        return { text: this.textPayload, ref: 'el_stub_1' };
     }
     async getHtml() {
-        return { html: '<html><body><a href="https://example.com">Example</a></body></html>' };
+        this.maybeDisconnect();
+        return { html: this.htmlPayload };
     }
     async snapshot() {
-        return {
-            url: this.url,
-            title: 'Stub Page',
-            nodes: [{ ref: 'e1', role: 'link', name: 'Example', tag: 'a' }],
-            truncated: false,
-        };
+        return { url: this.url, title: 'Stub Page', nodes: this.snapshotNodes, truncated: false };
     }
     async getCookies() {
         return { cookies: [{ name: 'stub', value: '1', domain: 'example.com', path: '/', secure: true, httpOnly: false }] };
@@ -174,6 +207,18 @@ class StubExecutor {
     async uploadFile() {
         return ok;
     }
+    // -- optional capabilities ----------------------------------------------
+    async framesList() {
+        return this.frames;
+    }
+    async observers(args) {
+        this.lastObserverArgs = args;
+        return this.observerState ?? { installed: false };
+    }
+    async printPdf() {
+        // "%PDF-1.4" in base64 — enough for a caller to assert real bytes landed.
+        return { dataBase64: 'JVBERi0xLjQK', mimeType: 'application/pdf', url: this.url, title: 'Stub Page' };
+    }
 }
 exports.StubExecutor = StubExecutor;
 //# sourceMappingURL=stub-executor.js.map

package/dist/src/executor/types.d.ts

@@ -9,6 +9,8 @@
  * Helpers (extract_links / read_as_markdown / fill_form) are composed in
  * `mcp/helpers.ts` from these primitives; only `download` is privileged.
  */
+import type { ObserverReadResult, DialogPolicy } from '../../shared/observers';
+export type { ObserverReadResult, DialogPolicy };
 export type BackendKind = 'extension' | 'cdp';
 export type WaitUntil = 'load' | 'domcontentloaded' | 'networkidle';
 export type KeyModifier = 'Alt' | 'Control' | 'Meta' | 'Shift';
@@ -32,6 +34,44 @@ export type Target = {
  * reconnect (a mismatch becomes a clean `STALE_TAB`, not a wrong-tab action).
  */
 export type TabId = string;
+/**
+ * Which frame(s) of a tab a call acts on. Omitted = the top frame, which is
+ * every call that predates frame support.
+ *
+ * `frameId` pins one frame (ids come from `framesList`). `allFrames` scans every
+ * frame and acts on the first that has the element — the answer to "the button
+ * is in the checkout iframe and my selector never matches". Each frame is
+ * authorized against ITS OWN url before anything runs there, so a scan can never
+ * reach into a frame the allowlist does not cover.
+ */
+export interface FrameOpts {
+    frameId?: number;
+    allFrames?: boolean;
+}
+export interface FrameInfo {
+    frameId: number;
+    top: boolean;
+    url: string;
+    title: string;
+}
+export interface PdfResult {
+    dataBase64: string;
+    mimeType: 'application/pdf';
+    url: string;
+    title: string;
+}
+export interface ObserverArgs extends FrameOpts {
+    tabId?: TabId;
+    console?: boolean;
+    network?: boolean;
+    dialogs?: boolean;
+    sinceSeq?: number;
+    limit?: number;
+    clear?: boolean;
+    setPolicy?: DialogPolicy;
+    promptText?: string;
+    includeResources?: boolean;
+}
 export interface TabInfo {
     tabId: TabId;
     url: string;
@@ -105,6 +145,8 @@ export interface SnapshotNode {
     value?: string;
     disabled?: boolean;
     checked?: boolean;
+    /** A password field: present so it can be targeted, `value` deliberately absent. */
+    secret?: boolean;
 }
 export interface SnapshotResult {
     url: string;
@@ -189,29 +231,29 @@ export interface Executor {
         button?: MouseButton;
         clickCount?: number;
         trusted?: boolean;
-    }): Promise<ActionOk>;
+    } & FrameOpts): Promise<ActionOk>;
     type(t: Target, text: string, opts?: {
         tabId?: TabId;
         clear?: boolean;
         pressEnter?: boolean;
         keyEvents?: boolean;
         trusted?: boolean;
-    }): Promise<ActionOk>;
+    } & FrameOpts): Promise<ActionOk>;
     /** Choose option(s) of a <select> by value or visible label. */
     selectOption(t: Target, values: string[], opts?: {
         tabId?: TabId;
-    }): Promise<ActionOk>;
+    } & FrameOpts): Promise<ActionOk>;
     /** Value-set + input/change events (used by fill_form). */
     fill(t: Target, value: string, opts?: {
         tabId?: TabId;
-    }): Promise<ActionOk>;
+    } & FrameOpts): Promise<ActionOk>;
     press(key: string, opts?: {
         tabId?: TabId;
         modifiers?: KeyModifier[];
     }): Promise<ActionOk>;
     hover(t: Target, opts?: {
         tabId?: TabId;
-    }): Promise<ActionOk>;
+    } & FrameOpts): Promise<ActionOk>;
     scroll(opts: {
         tabId?: TabId;
         x?: number;
@@ -219,17 +261,17 @@ export interface Executor {
         deltaX?: number;
         deltaY?: number;
         target?: Target;
-    }): Promise<ActionOk>;
+    } & FrameOpts): Promise<ActionOk>;
     getText(t?: Target, opts?: {
         tabId?: TabId;
-    }): Promise<{
+    } & FrameOpts): Promise<{
         text: string;
         ref?: string;
     }>;
     getHtml(t?: Target, opts?: {
         tabId?: TabId;
         outer?: boolean;
-    }): Promise<{
+    } & FrameOpts): Promise<{
         html: string;
     }>;
     /** Accessibility snapshot: interactive/landmark elements with stable refs the model can target. */
@@ -237,7 +279,7 @@ export interface Executor {
         tabId?: TabId;
         interactiveOnly?: boolean;
         max?: number;
-    }): Promise<SnapshotResult>;
+    } & FrameOpts): Promise<SnapshotResult>;
     /** Read cookies visible to the active tab's URL (or a given url). */
     getCookies(opts?: {
         tabId?: TabId;
@@ -257,18 +299,35 @@ export interface Executor {
         tabId?: TabId;
         fullPage?: boolean;
         target?: Target;
-    }): Promise<ScreenshotResult>;
+    } & FrameOpts): Promise<ScreenshotResult>;
     eval(expression: string, opts?: {
         tabId?: TabId;
         awaitPromise?: boolean;
-    }): Promise<EvalResult>;
+    } & FrameOpts): Promise<EvalResult>;
     waitFor(opts: {
         tabId?: TabId;
         selector?: string;
         textContains?: string;
         gone?: boolean;
         timeoutMs?: number;
-    }): Promise<WaitResult>;
+    } & FrameOpts): Promise<WaitResult>;
+    /** Every frame of a tab that the extension can inject into, with its URL. */
+    framesList?(opts?: {
+        tabId?: TabId;
+    }): Promise<FrameInfo[]>;
+    /** Read (and configure) the in-page console / network / dialog observers. */
+    observers?(args: ObserverArgs): Promise<ObserverReadResult>;
+    /** Render the page to PDF (Chrome's own print pipeline). */
+    printPdf?(opts?: {
+        tabId?: TabId;
+        landscape?: boolean;
+        printBackground?: boolean;
+        scale?: number;
+        paperWidth?: number;
+        paperHeight?: number;
+        pageRanges?: string;
+        preferCSSPageSize?: boolean;
+    }): Promise<PdfResult>;
     download(args: {
         url?: string;
         target?: Target;
@@ -290,7 +349,7 @@ export interface Executor {
  * (which only carries codes that originate inside the extension); these extra
  * codes describe failures on the server half (no backend, launch failed, etc.).
  */
-export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'BACKPRESSURE';
+export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'FRAME_NOT_FOUND' | 'OBSERVERS_DISABLED' | 'UNSUPPORTED' | 'BACKPRESSURE';
 export declare class ExecutorError extends Error {
     readonly code: ExecutorErrorCodeLocal;
     constructor(code: ExecutorErrorCodeLocal, message: string);

package/dist/src/mcp/audit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * src/mcp/audit.ts — per-call context so the action log can record WHICH page a
+ * call touched and what the policy decided about it.
+ *
+ * `history.jsonl` already records tool + args + ok. For a tool that drives a
+ * real, logged-in browser, the question people actually ask afterwards is "what
+ * did it touch, and what was it allowed to touch" — and the target URL, the
+ * policy verdict, and the size of what came back were all missing from the
+ * record. They are known inside the call and nowhere after it.
+ *
+ * `AsyncLocalStorage` rather than a module-level variable because `batch` runs
+ * ops CONCURRENTLY: one shared slot would attribute one op's URL to another's
+ * log line, which is worse than not logging it at all.
+ */
+export interface CallAudit {
+    /** The URL the policy gate was evaluated against, once one is resolved. */
+    url?: string;
+    /** Set when the gate denied the call. */
+    denied?: boolean;
+    /** Bytes of content this call returned to the caller (post-cap). */
+    bytes?: number;
+    /** How many secrets the redaction pass replaced. */
+    redactions?: number;
+    /** Frame the call actually acted on, when it was not the top frame. */
+    frameId?: number;
+}
+/** Run `fn` with a fresh audit record, and hand that record back. */
+export declare function withAudit<T>(fn: (audit: CallAudit) => Promise<T>): Promise<{
+    result: T;
+    audit: CallAudit;
+}>;
+/** The current call's audit record, or undefined outside a dispatch. */
+export declare function currentAudit(): CallAudit | undefined;
+/** Record the policy decision for this call. Safe to call outside a dispatch. */
+export declare function noteGate(url: string, allowed: boolean): void;
+/** Record how much content crossed back to the caller. */
+export declare function noteBytes(bytes: number): void;
+/** Record how many secrets were scrubbed on the way out. */
+export declare function noteRedactions(count: number): void;

package/dist/src/mcp/audit.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * src/mcp/audit.ts — per-call context so the action log can record WHICH page a
+ * call touched and what the policy decided about it.
+ *
+ * `history.jsonl` already records tool + args + ok. For a tool that drives a
+ * real, logged-in browser, the question people actually ask afterwards is "what
+ * did it touch, and what was it allowed to touch" — and the target URL, the
+ * policy verdict, and the size of what came back were all missing from the
+ * record. They are known inside the call and nowhere after it.
+ *
+ * `AsyncLocalStorage` rather than a module-level variable because `batch` runs
+ * ops CONCURRENTLY: one shared slot would attribute one op's URL to another's
+ * log line, which is worse than not logging it at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAudit = withAudit;
+exports.currentAudit = currentAudit;
+exports.noteGate = noteGate;
+exports.noteBytes = noteBytes;
+exports.noteRedactions = noteRedactions;
+const node_async_hooks_1 = require("node:async_hooks");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** Run `fn` with a fresh audit record, and hand that record back. */
+async function withAudit(fn) {
+    const audit = {};
+    const result = await storage.run(audit, () => fn(audit));
+    return { result, audit };
+}
+/** The current call's audit record, or undefined outside a dispatch. */
+function currentAudit() {
+    return storage.getStore();
+}
+/** Record the policy decision for this call. Safe to call outside a dispatch. */
+function noteGate(url, allowed) {
+    const a = storage.getStore();
+    if (!a)
+        return;
+    if (url)
+        a.url = url;
+    if (!allowed)
+        a.denied = true;
+}
+/** Record how much content crossed back to the caller. */
+function noteBytes(bytes) {
+    const a = storage.getStore();
+    if (!a)
+        return;
+    a.bytes = (a.bytes ?? 0) + bytes;
+}
+/** Record how many secrets were scrubbed on the way out. */
+function noteRedactions(count) {
+    if (count <= 0)
+        return;
+    const a = storage.getStore();
+    if (!a)
+        return;
+    a.redactions = (a.redactions ?? 0) + count;
+}
+//# sourceMappingURL=audit.js.map