browxai 0.7.0

package/dist/page/actionresult-blocks.d.ts

@@ -0,0 +1,99 @@
+import type { DispatchedAction } from "./actionresult.js";
+import type { NetworkEntry, NetworkSummary, MutationEntry, WsFrame } from "./network.js";
+import type { DialogRecord } from "../session/dialog.js";
+import type { PermissionRecord } from "../session/permission.js";
+import type { NotificationRecord } from "../session/notification.js";
+import type { FsPickerRecord } from "../session/fs-picker.js";
+import type { CapturedDownload } from "./downloads.js";
+/** The mutable action outcome a `raise`-policy slice can flip. */
+export interface ActionOutcome {
+    ok: boolean;
+    error: string | undefined;
+    failure: import("../util/failure.js").FailureClass | undefined;
+}
+/** If a policy fired in `raise` mode during the window and the action otherwise
+ *  succeeded, flip it to a clean ok:false with the policy's stable hint. The
+ *  page was handled server-side (not deadlocked), but the app saw the
+ *  cancel/deny branch and the caller almost certainly didn't want that.
+ *  Returns the (possibly) updated outcome; first raise wins (mirrors the prior
+ *  inline order: dialog → permission → notification → fs-picker). */
+export declare function applyPolicyRaise(outcome: ActionOutcome, raised: boolean, hint: string): ActionOutcome;
+export declare function buildDialogsBlock(slice: DialogRecord[]): Omit<DialogRecord, "ts">[] | undefined;
+export interface PermissionRequestBlock {
+    permission: PermissionRecord["permission"];
+    origin?: string;
+    handledAs: PermissionRecord["handledAs"];
+}
+export declare function buildPermissionRequestsBlock(slice: PermissionRecord[]): PermissionRequestBlock[] | undefined;
+export interface NotificationBlock {
+    title: string;
+    body?: string;
+    icon?: string;
+    tag?: string;
+    timestamp: number;
+    origin?: string;
+    handledAs: NotificationRecord["handledAs"];
+}
+export declare function buildNotificationsBlock(slice: NotificationRecord[]): NotificationBlock[] | undefined;
+export interface FsPickerRequestBlock {
+    api: FsPickerRecord["api"];
+    suggestedName?: string;
+    handledAs: FsPickerRecord["handledAs"];
+}
+export declare function buildFsPickerRequestsBlock(slice: FsPickerRecord[]): FsPickerRequestBlock[] | undefined;
+export interface DownloadBlock {
+    id: string;
+    suggestedFilename: string;
+    rawSuggestedFilename?: string;
+    mimeType?: string;
+    sizeBytes: number;
+    path: string;
+}
+export declare function buildDownloadsBlock(slice: CapturedDownload[]): DownloadBlock[] | undefined;
+export interface NetworkCloseResult {
+    summary: NetworkSummary;
+    requests: NetworkEntry[];
+    mutations: MutationEntry[];
+}
+export interface NetworkBlock {
+    summary: NetworkSummary;
+    requests?: NetworkEntry[];
+    egressOffAllowlist?: number;
+    mutations?: MutationEntry[];
+    wsFrames?: WsFrame[];
+}
+/** Build the `network` result block. Within the per-request cap the full
+ *  request rows ride along; over the cap they're omitted with a warning
+ *  pointing at `network_read`. Mutations + WS frames attach when present. */
+export declare function buildNetworkBlock(network: NetworkCloseResult, wsSlice: WsFrame[], egressOffAllowlist: number, requestCap: number, warnings: string[]): NetworkBlock;
+/** The five optional capture blocks, each present only when its slice was
+ *  non-empty. Collected once so the orchestrator spreads a single object into
+ *  both the token estimate and the final result (the prior code repeated ten
+ *  `...(x ? {key:x} : {})` ternaries). */
+export interface OptionalBlocks {
+    dialogs?: Omit<DialogRecord, "ts">[];
+    permissionRequests?: PermissionRequestBlock[];
+    notifications?: NotificationBlock[];
+    fsPickerRequests?: FsPickerRequestBlock[];
+    downloads?: DownloadBlock[];
+}
+export declare function assembleOptionalBlocks(parts: {
+    dialogs: Omit<DialogRecord, "ts">[] | undefined;
+    permissionRequests: PermissionRequestBlock[] | undefined;
+    notifications: NotificationBlock[] | undefined;
+    fsPickerRequests: FsPickerRequestBlock[] | undefined;
+    downloads: DownloadBlock[] | undefined;
+}): OptionalBlocks;
+export interface RecordableStep {
+    descriptor: DispatchedAction;
+    urlAfter: string;
+    recordingHint: {
+        selectorHint: string;
+        stability?: "high" | "medium" | "low";
+    } | undefined;
+}
+/** Append the action to an active recording when it is replayable as a
+ *  flow-file step. Coord-mode click/hover (no ref/selector/hint) are an escape
+ *  hatch flow files can't mechanically replay, so they're skipped with a
+ *  warning. Navigation/history actions need no target and are always recorded. */
+export declare function maybeRecord(recorder: import("./recording.js").Recorder | undefined, ok: boolean, step: RecordableStep, warnings: string[]): void;

package/dist/page/actionresult-blocks.js

@@ -0,0 +1,144 @@
+// ActionResult post-state block builders — the pure shaping helpers that
+// `runInActionWindow` (actionresult.ts) composes after the action window closes.
+// Each function maps one captured slice into its public result block; pulling
+// them out keeps the orchestrator under the size/complexity budget without
+// changing any output shape (the blocks are byte-identical to the inline
+// versions). No page contact — every input is already-captured data.
+/** If a policy fired in `raise` mode during the window and the action otherwise
+ *  succeeded, flip it to a clean ok:false with the policy's stable hint. The
+ *  page was handled server-side (not deadlocked), but the app saw the
+ *  cancel/deny branch and the caller almost certainly didn't want that.
+ *  Returns the (possibly) updated outcome; first raise wins (mirrors the prior
+ *  inline order: dialog → permission → notification → fs-picker). */
+export function applyPolicyRaise(outcome, raised, hint) {
+    if (!raised || !outcome.ok)
+        return outcome;
+    return { ok: false, error: outcome.error ?? hint, failure: { source: "app", hint } };
+}
+export function buildDialogsBlock(slice) {
+    if (slice.length === 0)
+        return undefined;
+    return slice.map((d) => {
+        const { ts: _ts, ...pub } = d;
+        return pub;
+    });
+}
+export function buildPermissionRequestsBlock(slice) {
+    if (slice.length === 0)
+        return undefined;
+    return slice.map((r) => {
+        const out = { permission: r.permission, handledAs: r.handledAs };
+        if (r.origin !== undefined)
+            out.origin = r.origin;
+        return out;
+    });
+}
+export function buildNotificationsBlock(slice) {
+    if (slice.length === 0)
+        return undefined;
+    return slice.map((n) => {
+        const out = {
+            title: n.title,
+            timestamp: n.timestamp,
+            handledAs: n.handledAs,
+        };
+        if (n.body !== undefined)
+            out.body = n.body;
+        if (n.icon !== undefined)
+            out.icon = n.icon;
+        if (n.tag !== undefined)
+            out.tag = n.tag;
+        if (n.origin !== undefined)
+            out.origin = n.origin;
+        return out;
+    });
+}
+export function buildFsPickerRequestsBlock(slice) {
+    if (slice.length === 0)
+        return undefined;
+    return slice.map((r) => {
+        const out = { api: r.api, handledAs: r.handledAs };
+        if (r.suggestedName !== undefined)
+            out.suggestedName = r.suggestedName;
+        return out;
+    });
+}
+export function buildDownloadsBlock(slice) {
+    if (slice.length === 0)
+        return undefined;
+    return slice.map((d) => {
+        const out = {
+            id: d.id,
+            suggestedFilename: d.suggestedFilename,
+            sizeBytes: d.sizeBytes,
+            path: d.path,
+        };
+        if (d.rawSuggestedFilename !== undefined)
+            out.rawSuggestedFilename = d.rawSuggestedFilename;
+        if (d.mimeType !== undefined)
+            out.mimeType = d.mimeType;
+        return out;
+    });
+}
+/** Build the `network` result block. Within the per-request cap the full
+ *  request rows ride along; over the cap they're omitted with a warning
+ *  pointing at `network_read`. Mutations + WS frames attach when present. */
+export function buildNetworkBlock(network, wsSlice, egressOffAllowlist, requestCap, warnings) {
+    const mutationsBlock = network.mutations.length > 0 ? { mutations: network.mutations } : {};
+    const wsBlock = wsSlice.length > 0 ? { wsFrames: wsSlice } : {};
+    if (network.summary.total === 0) {
+        return { summary: network.summary, ...mutationsBlock, ...wsBlock };
+    }
+    if (network.requests.length <= requestCap) {
+        return {
+            summary: network.summary,
+            requests: network.requests,
+            ...(egressOffAllowlist > 0 ? { egressOffAllowlist } : {}),
+            ...mutationsBlock,
+            ...wsBlock,
+        };
+    }
+    warnings.push(`network.requests omitted (count ${network.requests.length} > cap ${requestCap}); call network_read for details`);
+    return {
+        summary: network.summary,
+        ...(egressOffAllowlist > 0 ? { egressOffAllowlist } : {}),
+        ...mutationsBlock,
+        ...wsBlock,
+    };
+}
+export function assembleOptionalBlocks(parts) {
+    const out = {};
+    if (parts.dialogs)
+        out.dialogs = parts.dialogs;
+    if (parts.permissionRequests)
+        out.permissionRequests = parts.permissionRequests;
+    if (parts.notifications)
+        out.notifications = parts.notifications;
+    if (parts.fsPickerRequests)
+        out.fsPickerRequests = parts.fsPickerRequests;
+    if (parts.downloads)
+        out.downloads = parts.downloads;
+    return out;
+}
+const NON_TARGETED_ACTIONS = new Set(["navigate", "goBack", "goForward"]);
+/** Append the action to an active recording when it is replayable as a
+ *  flow-file step. Coord-mode click/hover (no ref/selector/hint) are an escape
+ *  hatch flow files can't mechanically replay, so they're skipped with a
+ *  warning. Navigation/history actions need no target and are always recorded. */
+export function maybeRecord(recorder, ok, step, warnings) {
+    if (!ok || !recorder?.active())
+        return;
+    const { descriptor, urlAfter, recordingHint } = step;
+    const isElementAction = !NON_TARGETED_ACTIONS.has(descriptor.type);
+    const hasReplayableTarget = !!(descriptor.ref || descriptor.selector || recordingHint);
+    if (!isElementAction || hasReplayableTarget) {
+        try {
+            recorder.record(descriptor, urlAfter, recordingHint);
+        }
+        catch {
+            /* swallow */
+        }
+        return;
+    }
+    warnings.push("recorder: skipped untargeted action (coords-mode click/hover) — flow files replay deterministically by ref/selector; record the equivalent ref-based action if you want this step in the draft");
+}

package/dist/page/actionresult-shape.d.ts

@@ -0,0 +1,48 @@
+import { type A11yNode } from "./a11y.js";
+/** A page-level landmark region (dialog / alert / banner / …) tracked across the
+ *  action window to diff appeared/removed structure. */
+export type Region = {
+    role: string;
+    name?: string;
+    ref: string;
+};
+export type SnapshotMode = "scoped_snapshot" | "tree_diff" | "full" | "none";
+export interface NavigationInfo {
+    changed: boolean;
+    from: string;
+    to: string;
+    kind: "hash" | "full_load" | "spa" | null;
+}
+export interface SnapshotDeltaInfo {
+    mode: SnapshotMode;
+    scope: string;
+    tree?: string;
+    truncated: boolean;
+}
+export interface RegionDiff {
+    appeared: Region[];
+    removed: Region[];
+    newTabs: Array<{
+        url: string;
+        title: string;
+    }>;
+}
+export declare function topLevelRegions(tree: A11yNode): Map<string, Region>;
+export declare function diffRegions(pre: Map<string, Region>, post: Map<string, Region>): RegionDiff;
+export declare function describeNavigation(from: string, to: string, frameNavigated: boolean): NavigationInfo;
+export declare function buildSnapshotDelta(mode: SnapshotMode, tree: A11yNode | null, maxTokens: number, warnings: string[], 
+/** refs to scope the delta to (action's ref + appeared regions).
+ *  When empty + mode=scoped_snapshot, falls back to the full tree as before. */
+scopeRefs?: string[]): SnapshotDeltaInfo | undefined;
+export declare function sleep(ms: number): Promise<void>;
+export interface ConsoleSlice {
+    errors: string[];
+    warnings: number;
+    truncated_chars?: number;
+}
+/** Inline summary of console errors — collapse multi-line stack-traces to their
+ *  first line + a token-budget per error, and emit `truncated_chars` if any were
+ *  trimmed. The full text is still in the session's `ConsoleBuffer`; an agent who
+ *  needs it calls `console_read`. Pattern mirrors the existing
+ *  `network.requests omitted (count N > cap)` design. */
+export declare function summariseConsoleErrors(errors: string[], warnings: string[]): ConsoleSlice;

package/dist/page/actionresult-shape.js

@@ -0,0 +1,155 @@
+// ActionResult shape helpers — the pure tree/navigation/console shaping the
+// action window composes. Split out of actionresult.ts to keep that file under
+// the size budget; every function is behavior-identical to its prior inline form
+// (no page contact, deterministic over already-captured inputs).
+import { walk } from "./a11y.js";
+import { findByRef, serialise } from "./snapshot.js";
+import { truncateToBudget } from "../util/tokens.js";
+const INTERESTING_REGION_ROLES = new Set([
+    "dialog",
+    "alertdialog",
+    "alert",
+    "status",
+    "banner",
+    "complementary",
+    "tablist",
+    "menu",
+    "menubar",
+    "tooltip",
+    "toolbar",
+]);
+export function topLevelRegions(tree) {
+    // "Top-level regions" = nodes whose role indicates a page-level appearance
+    // (dialog, alert, alertdialog, status, banner, etc.) anywhere in the tree.
+    const out = new Map();
+    for (const { node } of walk(tree)) {
+        if (INTERESTING_REGION_ROLES.has(node.role)) {
+            out.set(node.ref, { role: node.role, name: node.name, ref: node.ref });
+        }
+    }
+    return out;
+}
+export function diffRegions(pre, post) {
+    const appeared = [];
+    const removed = [];
+    for (const [ref, r] of post)
+        if (!pre.has(ref))
+            appeared.push(r);
+    for (const [ref, r] of pre)
+        if (!post.has(ref))
+            removed.push(r);
+    return { appeared, removed, newTabs: [] };
+}
+export function describeNavigation(from, to, frameNavigated) {
+    if (from === to)
+        return { changed: false, from, to, kind: null };
+    try {
+        const a = new URL(from);
+        const b = new URL(to);
+        if (a.origin === b.origin &&
+            a.pathname === b.pathname &&
+            a.search === b.search &&
+            a.hash !== b.hash) {
+            return { changed: true, from, to, kind: "hash" };
+        }
+    }
+    catch {
+        /* invalid URL — fall through */
+    }
+    return { changed: true, from, to, kind: frameNavigated ? "full_load" : "spa" };
+}
+/** Serialise the scoped subtrees for the snapshotDelta, truncated to the token
+ *  budget. When no scope ref resolved in the post-tree, returns a tiny
+ *  scope-marker delta instead of the full tree. */
+function serialiseScopedSubtrees(tree, scopeRefs, maxTokens, warnings) {
+    const subtrees = scopeRefs
+        .map((ref) => findByRef(tree, ref))
+        .filter((n) => n !== null);
+    if (subtrees.length === 0) {
+        // All scope refs gone — element vanished + no appeared regions. Fall through
+        // to a tiny scope marker instead of the full tree.
+        return {
+            mode: "scoped_snapshot",
+            scope: "(scope refs not present in post-tree)",
+            truncated: false,
+        };
+    }
+    const text = subtrees
+        .map((n, i) => (subtrees.length > 1 ? `--- subtree ${i + 1}/${subtrees.length} ---\n` : "") + serialise(n))
+        .join("\n");
+    const { text: trimmed, truncated } = truncateToBudget(text, maxTokens);
+    if (truncated)
+        warnings.push(`snapshotDelta truncated to fit maxResultTokens=${maxTokens}; call snapshot() for the complete tree`);
+    return {
+        mode: "scoped_snapshot",
+        scope: `scoped to ${subtrees.length} subtree(s) [${scopeRefs.join(", ")}]`,
+        tree: trimmed,
+        truncated,
+    };
+}
+export function buildSnapshotDelta(mode, tree, maxTokens, warnings, 
+/** refs to scope the delta to (action's ref + appeared regions).
+ *  When empty + mode=scoped_snapshot, falls back to the full tree as before. */
+scopeRefs = []) {
+    if (mode === "none")
+        return undefined;
+    if (!tree)
+        return { mode, scope: "(no tree)", truncated: false };
+    let renderMode = mode;
+    if (mode === "tree_diff") {
+        //  partial: emit appeared/removed-as-subtrees instead of a unified diff.
+        // Closer in spirit to Vercel agent-browser's diff than the previous fallback,
+        // without needing the line-stable cross-snapshot diff plumbing.
+        warnings.push('mode=tree_diff: emitting appeared-region subtrees only (full unified diff not yet implemented; pass mode:"full" for the post-action tree)');
+        renderMode = "scoped_snapshot";
+    }
+    if (renderMode === "scoped_snapshot" && scopeRefs.length > 0) {
+        // real scope-down. Serialise just the action's element subtree + any
+        // newly-appeared top-level regions. Drops 7-10k-token snapshots to ~500-1500
+        // on the heavy-SPA / many-elements shape.
+        return serialiseScopedSubtrees(tree, scopeRefs, maxTokens, warnings);
+    }
+    // Fall-through: full tree. Honours explicit mode:"full" and the rare case where
+    // scoped_snapshot was asked-for but we have no scope refs (no action ref, no
+    // appeared regions — uncommon).
+    const scope = renderMode === "scoped_snapshot" ? "full (no scope refs)" : "full";
+    const { text, truncated } = truncateToBudget(serialise(tree), maxTokens);
+    if (truncated)
+        warnings.push(`snapshotDelta truncated to fit maxResultTokens=${maxTokens}; call snapshot() for the complete tree`);
+    return { mode: renderMode, scope, tree: text, truncated };
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+const ERROR_MAX_CHARS_PER = 400;
+const ERROR_MAX_TOTAL_ENTRIES = 20;
+/** Inline summary of console errors — collapse multi-line stack-traces to their
+ *  first line + a token-budget per error, and emit `truncated_chars` if any were
+ *  trimmed. The full text is still in the session's `ConsoleBuffer`; an agent who
+ *  needs it calls `console_read`. Pattern mirrors the existing
+ *  `network.requests omitted (count N > cap)` design. */
+export function summariseConsoleErrors(errors, warnings) {
+    if (errors.length === 0)
+        return { errors: [], warnings: 0 };
+    let trimmed = 0;
+    const out = [];
+    const slice = errors.slice(0, ERROR_MAX_TOTAL_ENTRIES);
+    for (const e of slice) {
+        if (e.length <= ERROR_MAX_CHARS_PER && !e.includes("\n")) {
+            out.push(e);
+            continue;
+        }
+        const firstLine = e.split("\n")[0].slice(0, ERROR_MAX_CHARS_PER);
+        out.push(firstLine + " …");
+        trimmed += Math.max(0, e.length - firstLine.length);
+    }
+    if (errors.length > ERROR_MAX_TOTAL_ENTRIES) {
+        warnings.push(`console.errors truncated (showing ${ERROR_MAX_TOTAL_ENTRIES} of ${errors.length}); call console_read for the full ring buffer`);
+    }
+    const result = { errors: out, warnings: 0 };
+    if (trimmed > 0) {
+        result.truncated_chars = trimmed;
+        warnings.push(`console.errors stack-traces summarised (${trimmed} chars trimmed); call console_read for the full text`);
+    }
+    return result;
+}