Plugins and agents cannot run bounded scripts in BB Browser tabs

[brsbl]

Summary

BB needs one general, bounded Browser-page runtime that both plugins and native agent tools can use against an exact Browser target. The Browser action remains the plugin-owned user entry point, but selection is a consumer of the runtime rather than a specialized core inspection API.

Canonical architecture

Exact Browser target

Every operation and mode state binds to the complete identity:

• clientId
• windowId
• tabId
• navigationEpoch

Logical tabId alone is never accepted. Navigation changes the epoch and invalidates stale work.

Browser-page runtime

• execute cleanup-safe page scripts in an isolated world by default
• accept and return bounded JSON only
• enforce input, result, screenshot, execution-time, and concurrency limits
• cancel on caller abort, navigation, tab detach, window close, client disconnect, or timeout
• expose no Node, Electron, or BB app-shell objects to page code
• retain experimental_browserAction as the plugin toolbar entry point, including its exact target

This is distinct from app.contentScripts, which runs trusted plugin code in the BB application shell.

Agent request/response broker

• discover Browser targets available to the selected BB client
• select and address the exact client/window/tab/navigation epoch
• correlate concurrent calls with independent request IDs
• route server-side agent tools to the exact desktop Browser tab
• make active agent control visible and preserve normal BB tool permission/audit behavior

Inspection and control operations

The tool set uses the same runtime for DOM/interactive snapshots, click, type, keyboard, scroll, navigation, screenshot, and a bounded ephemeral custom-script path. Selection/annotation logic is plugin-owned in the Browser Context reusable page-script library.

Security and lifecycle boundaries

• Plugin backend and agent tool code are full-trust BB extensions; page scripts are constrained to the selected Browser page and bounded transport.
• Custom scripts do not bypass normal agent-tool permissions or timeline auditability.
• Main-frame navigation invalidates the target epoch and every in-flight operation bound to it.
• Renderer-local AbortSignal objects never cross IPC; cancellation uses serializable request IDs.
• Native Browser-view visibility policy remains separate from temporary plugin overlays or agent activity.

Implementation stack

• Foundation: PR #1869 at 7b27bdec8ac5dc3966c1a49a6be654635fd77a02 — Browser-page runtime, exact-target broker, agent control, Browser action, and SDK 0.4.9
• Follow-up: PR #1870 at 9a6617ec517d2fa4b021b06f08326b36593765bd — generic inspectable mention UI
• Native GitHub stack: #1871
• First consumer: bb-plugins PR #72 at c6060ba54624a5da86679eba137d382903bee194

PRs #1642, #1643, and old bb-plugins PRs #31/#30 are superseded and must not be merged as this implementation.

Compatibility and provenance

• The additive public Browser surface is @get-bb/plugin-sdk 0.4.9; 0.4.8 was already published.
• Persisted 0.4.8 plugin manifests continue to load under 0.4.9.
• Browser Context alone raises its SDK floor; unrelated plugins retain their capability-based versions.
• Frozen top source: 9a6617ec517d2fa4b021b06f08326b36593765bd
• @get-bb/plugin-sdk@0.4.9 SHA-256: 0c2023c099ea00a54066be9c9a0f701b6716336779cc0ff8ed05a6a9bedc5930
• Matching bb plugin build@0.39.0 SHA-256: 7df5ca65550708db87443e65f87780ab08694811ac74f3fdad53dfd91ab7ece3

Completion criteria

• core runtime, broker, and operations are tested across cancellation, navigation, disconnect, concurrency, and payload limits
• real BB desktop QA proves plugin Browser actions and agent inspect/control at representative widths
• Browser Context selection is implemented outside core on the general runtime
• exact SDK and plugin-builder provenance is recorded for the consumer

Do not close this issue until the revised objective is merged.

Originating implementation thread: thr_p9qmfkggwm

AGENT GENERATED: by GPT-5.6-Sol

[brsbl]

2026-08-18 architecture decision: replace the discarded Browser-specific inspection contract with one general, isolated Browser-page runtime plus an exact client/window/tab broker. Plugin Browser actions and native agent inspect/control use the same bounded substrate; selection capture moves to the Browser Context plugin. Replacement core stack: #1869 → #1870 (native stack #1871). PRs #1642/#1643 are superseded and remain unmerged.

[brsbl]

2026-08-18 implementation status: the replacement core stack is frozen and green.

• #1869 head bf227d3c46e1ef6b0c3ed92279e45ba3f672db22: isolated Browser-page runtime, exact client/window/tab broker, Browser action, native agent inspect/control operations, serializable cancellation IPC, and SDK 0.4.9 compatibility layer.
• #1870 head 4162466dfdb6de58fc05a750ec23e36a7b8da56c: provider-agnostic inspectable mentions on top of the runtime foundation.
• Native stack: #1871.
• All required GitHub checks pass. Exact desktop QA passed the plugin Browser action plus agent snapshot, isolated custom script, type, click, scroll, and screenshot paths at representative widths.
• Final @get-bb/plugin-sdk@0.4.9 archive SHA-256: b44992cbf539aa54ac785b6aab2df57ad3eb2aa2fbe17f6755aaf5ebfe4cc11e, produced from top head 4162466dfdb6de58fc05a750ec23e36a7b8da56c. Matching builder archive SHA-256: 55d54d85924fd3d3fcdf6cee74fa847068a2577a77886a06733df9b1aa261a0f from the same source head; packages/plugin-build is unchanged from merge base.

The Browser Context consumer can now rebase onto these exact heads and provenance. This issue remains open until the revised objective is merged.

[brsbl]

2026-08-19 status update: the core stack is frozen and green after the Browser-toolbar overflow follow-up. Foundation PR #1869 is at 50f60f0b9393de09143a1ac521e398b823c0511e; stacked PR #1870 is at 83adae80d6d8c414b83528e7f9b7993085f67a02. The public Browser runtime/broker and SDK 0.4.9 contract did not change. All GitHub checks pass on both heads. The foundation now also guarantees plugin actions precede an always-visible external-link control and moves excess actions into an ordered keyboard-accessible overflow menu. No merge performed.

[brsbl]

2026-08-19 exact-target completion: the additive Browser action/state contract now carries the established clientId + windowId + tabId + navigationEpoch identity end to end. Refreshed frozen heads are #1869 7b27bdec8ac5dc3966c1a49a6be654635fd77a02 → #1870 9a6617ec517d2fa4b021b06f08326b36593765bd. The replacement Browser Context consumer is brsbl/bb-plugins#72 at e182e56c2f479515d83e768fd2d74ef7b3a47bbf; focused core/plugin checks and exact Electron user/agent entry, exit, navigation invalidation, and selection QA pass. No merge performed.

[brsbl]

2026-08-19 provenance correction: the final replacement consumer head is c6060ba54624a5da86679eba137d382903bee194. The only follow-up after e182e56c2 preserves the plugin-local 0.4.9 builder provenance when validating generated install refs; it does not alter the public core contract or UI.