@stratusagent/tool-browser 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratus Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @stratusagent/tool-browser
+
+`browser.goto`, `browser.read`, `browser.screenshot`, `browser.act`: a real
+browser, one per daemon, with a page per conversation and every request
+pinned through a proxy this plugin owns.
+
+Reach for [`@stratusagent/tool-web`](../tool-web) first. `web.fetch` is what
+an agent wants twenty times for every once it needs this, and it costs no
+Chromium.
+
+## Install
+
+```bash
+npm install @stratusagent/tool-browser
+```
+
+The dependency is **`playwright-core`** — a few megabytes, and it downloads
+no browser. Installing this plugin costs you nothing you did not ask for;
+the browser is one you already have, or one you fetch deliberately:
+
+```bash
+npx playwright install chromium      # ~150 MB, if you want a dedicated one
+```
+
+```jsonc
+// ~/.stratus/config.json — a trusted config only
+{
+  "plugins": {
+    "@stratusagent/tool-browser": {
+      "enabled": true,
+      "channel": "chrome"            // or "executablePath": "/path/to/chrome"
+    }
+  }
+}
+```
+
+Nothing here is loaded until a `browser.*` tool is actually called, so a
+daemon with the plugin enabled and no browser installed runs normally and
+fails that one call with a message naming the fix.
+
+## Risk model
+
+| Tool | Risk | What approval mode does |
+| --- | --- | --- |
+| `browser.goto` | `gated` | `interactive` asks, `remote` asks in Slack, `headless` refuses. |
+| `browser.read` | `gated` | Same. Navigating and reading reach a service outside Stratus. |
+| `browser.screenshot` | `gated` | Same. Writes a PNG into the agent's workspace and returns it as `file`, which a channel delivers as an attachment. |
+| `browser.act` | `dangerous` | Always a human, in every mode. A click submits, buys, and deletes — navigating somewhere else undoes a `goto`, and nothing undoes a click. |
+
+## Settings
+
+| Key | Default | What |
+| --- | --- | --- |
+| `channel` | none | Use an installed browser: `chrome`, `msedge`. |
+| `executablePath` | none | Use the browser at this path. |
+| `headless` | `true` | Set `false` to watch it work. |
+| `allowedHosts` | none | Hosts exempt from the address check. |
+| `allowPrivateAddresses` | `false` | Reach non-global addresses. The trusted-workstation posture. |
+| `idleMs` | `300000` | Close a conversation's context after this much quiet. |
+| `maxContexts` | `4` | Contexts at once; the least recently used goes first. |
+| `maxTextBytes` | `100000` | Cap on `browser.read`, then a `truncated` marker. |
+| `navigationTimeoutMs` | `30000` | Per navigation and per action. |
+| `workspaceRoot` | supplied by the daemon | Where screenshots go: `<root>/<agent-id>/screenshots`. |
+
+Address settings apply per agent under `agents`, and they are enforced —
+including when an agent's policy is *narrower* than the default. A proxy is
+chosen when Chromium launches, so a browser can only ever enforce one
+address policy: agents whose policy differs get their own browser, and
+agents that share a policy share one. Interception inside the browser cannot
+substitute, because it does not resolve names and so cannot narrow a
+hostname destination without re-opening the rebinding race the proxy closes.
+
+The practical cost is one Chromium per distinct policy. Most deployments
+have exactly one; a config that gives every agent its own posture pays for
+every one of them.
+
+## Why a proxy rather than request interception
+
+Playwright can intercept requests, and this plugin does — but interception
+happens *in the browser*, and Chromium resolves names for itself afterwards.
+Validating an address there and letting Chromium resolve it again is DNS
+rebinding with one more process in the way: the attacker's DNS answers
+`93.184.216.34` for the check and `169.254.169.254` for the connection.
+
+So every connection goes through a proxy this plugin starts on loopback,
+which resolves the name, checks the address, and dials **that address**.
+Redirects and subresources come back through it too, because every request
+does. The launch carries `--proxy-bypass-list=<-loopback>`, without which
+Chromium would bypass the proxy for exactly the addresses it exists to
+refuse.
+
+Interception still does the half a proxy cannot: `file:`, `data:`, and
+other local schemes never reach a proxy at all, and this process can read
+the files they name. Those are refused before navigation and again on every
+request the page makes.
+
+The address policy itself is [`@stratusagent/egress`](../egress) — the same
+module `tool-web` uses, tested against the same table of hostile URLs. A
+second copy would not drift into a style difference; the stale one would be
+an SSRF hole.
+
+## Screenshots come back as files, not bytes
+
+`browser.screenshot` writes to `<workspaceRoot>/<agent-id>/screenshots/` and
+returns `{ file, url, title }`. The `file` key is the channel contract's
+convention for a result that refers to a local file, so a Slack thread that
+asked for a screenshot gets the image posted into it rather than a path nobody
+can open. Base64 in a tool result would be a transcript no human can read and
+a provider bill nobody wanted.
+
+## Lifecycle
+
+One browser per address policy, started on the first call that needs it.
+One **context** per conversation, so two conversations never share a cookie
+jar or a login. A context that has been quiet longer than `idleMs` is
+closed; when a browser's last conversation goes, so does the browser and its
+proxy. `maxContexts` bounds how many contexts can exist at once, dropping
+the least recently used.
+
+The sweep runs on the plugin's own timer — unref'd, so it never holds a
+one-shot `stratus run` open, and disarmed once no browser is left. It also
+takes the current time as an argument, which is what makes the lifecycle
+testable without a test that sleeps.
+
+Shutdown is the kernel's `dispose` hook, which the gateway calls after
+in-flight turns drain and `stratus run`/`chat` call when they finish. Every
+context, every browser, and every proxy goes with it.

package/dist/driver.d.ts

@@ -0,0 +1,82 @@
+import type { OptionalModuleHost } from '@stratusagent/plugins';
+/**
+ * The browser, as this pack uses it.
+ *
+ * A seam rather than a direct Playwright import, for two reasons. The pack
+ * must load in a daemon where no browser is installed — every other tool
+ * still works, and `browser.*` fails with something an operator can act on
+ * — and the lifecycle logic (contexts per session, idle teardown, the
+ * concurrency cap) is testable against a stub, where a real Chromium in CI
+ * would test the same code and a 300 MB download.
+ *
+ * Playwright's own objects satisfy these shapes structurally.
+ */
+export interface PageLike {
+    goto(url: string, options?: {
+        timeout?: number;
+        waitUntil?: string;
+    }): Promise<{
+        status(): number;
+    } | null>;
+    url(): string;
+    title(): Promise<string>;
+    content(): Promise<string>;
+    evaluate(script: string): Promise<unknown>;
+    screenshot(options: {
+        path?: string;
+        fullPage?: boolean;
+    }): Promise<Buffer>;
+    click(selector: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    fill(selector: string, value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    route(pattern: string, handler: (route: RouteLike) => void | Promise<void>): Promise<void>;
+    close(): Promise<void>;
+}
+export interface RouteLike {
+    request(): {
+        url(): string;
+        resourceType?: () => string;
+    };
+    abort(reason?: string): Promise<void>;
+    continue(): Promise<void>;
+}
+export interface BrowserContextLike {
+    newPage(): Promise<PageLike>;
+    close(): Promise<void>;
+}
+export interface BrowserLike {
+    newContext(options?: {
+        viewport?: {
+            width: number;
+            height: number;
+        };
+    }): Promise<BrowserContextLike>;
+    close(): Promise<void>;
+}
+export interface LaunchOptions {
+    headless: boolean;
+    proxy: {
+        server: string;
+        bypass: string;
+    };
+    executablePath?: string;
+    channel?: string;
+}
+export interface BrowserDriver {
+    launch(options: LaunchOptions): Promise<BrowserLike>;
+}
+/**
+ * Playwright, loaded only when a browser tool is actually called.
+ *
+ * `playwright-core` is a few megabytes and downloads no browser, which is
+ * the whole reason it is the dependency: installing this plugin costs an
+ * operator nothing they did not ask for, and the browser is whatever they
+ * already have — an installed Chrome or Edge by `channel`, an
+ * `executablePath` they name, or a Chromium they installed with
+ * `npx playwright install chromium`.
+ */
+export declare const createPlaywrightDriver: (host: OptionalModuleHost) => BrowserDriver;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,MAAM,IAAI,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC5G,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,UAAU,CAAC,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5E,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,IAAI;QAAE,GAAG,IAAI,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;IAC1D,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACtD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM,kBAAkB,KAAG,aA8BhE,CAAC"}

package/dist/driver.js

@@ -0,0 +1,37 @@
+import { loadOptionalModule } from '@stratusagent/plugins';
+/**
+ * Playwright, loaded only when a browser tool is actually called.
+ *
+ * `playwright-core` is a few megabytes and downloads no browser, which is
+ * the whole reason it is the dependency: installing this plugin costs an
+ * operator nothing they did not ask for, and the browser is whatever they
+ * already have — an installed Chrome or Edge by `channel`, an
+ * `executablePath` they name, or a Chromium they installed with
+ * `npx playwright install chromium`.
+ */
+export const createPlaywrightDriver = (host) => ({
+    async launch(options) {
+        const playwright = await loadOptionalModule('playwright-core', host);
+        if (!playwright) {
+            throw new Error('browser.* needs playwright-core, which is not installed. '
+                + 'Install it alongside @stratusagent/tool-browser (npm install playwright-core).');
+        }
+        try {
+            return await playwright.chromium.launch({
+                headless: options.headless,
+                proxy: options.proxy,
+                ...(options.executablePath ? { executablePath: options.executablePath } : {}),
+                ...(options.channel ? { channel: options.channel } : {}),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // The overwhelmingly common failure, and one an operator can fix in a
+            // line — worth saying rather than passing Playwright's paragraph on.
+            throw new Error(`Could not start a browser: ${message}\n`
+                + 'Install one with `npx playwright install chromium`, or point the plugin at a browser you have '
+                + '(`"channel": "chrome"` or `"executablePath": "/path/to/chrome"`).');
+        }
+    },
+});
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAsD3D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,IAAwB,EAAiB,EAAE,CAAC,CAAC;IAClF,KAAK,CAAC,MAAM,CAAC,OAAO;QAClB,MAAM,UAAU,GAAG,MAAM,kBAAkB,CAExC,iBAAiB,EAAE,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACb,2DAA2D;kBACzD,gFAAgF,CACnF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;gBACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7E,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,sEAAsE;YACtE,qEAAqE;YACrE,MAAM,IAAI,KAAK,CACb,8BAA8B,OAAO,IAAI;kBACvC,gGAAgG;kBAChG,mEAAmE,CACtE,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { JsonObject, Plugin } from '@stratusagent/core';
+import { type OptionalModuleHost } from '@stratusagent/plugins';
+import { type BrowserDriver } from './driver.ts';
+export { createPlaywrightDriver, type BrowserContextLike, type BrowserDriver, type BrowserLike, type LaunchOptions, type PageLike, type RouteLike, } from './driver.ts';
+export { BrowserSessionPool, type SessionPoolOptions } from './sessions.ts';
+export interface BrowserPluginConfig extends JsonObject {
+    allowPrivateAddresses?: boolean;
+    allowedHosts?: string[];
+    headless?: boolean;
+    executablePath?: string;
+    channel?: string;
+    idleMs?: number;
+    maxContexts?: number;
+    maxTextBytes?: number;
+    navigationTimeoutMs?: number;
+    /** Supplied by the host: `~/.stratus/workspaces`, one directory per agent. */
+    workspaceRoot?: string;
+}
+export interface BrowserPluginOptions {
+    /** Overrides the Playwright driver. Tests use it; nothing else should. */
+    driver?: BrowserDriver;
+    /** How this host resolves and imports optional packages. */
+    moduleHost?: OptionalModuleHost;
+}
+/**
+ * The `browser` toolset.
+ *
+ * One browser per plugin, a context per conversation, and an idle sweep
+ * that closes both — see `BrowserSessionPool`. Every request the browser
+ * makes goes through a proxy this plugin owns, which resolves and validates
+ * each address itself, because Chromium resolves names for itself no matter
+ * what an interception handler decided.
+ */
+export declare const createBrowserPlugin: (config?: JsonObject, options?: BrowserPluginOptions) => Plugin & {
+    dispose(): Promise<void>;
+    sweepIdle(now: number): Promise<string[]>;
+};
+/** The loader's ABI. See `docs/architecture/plugins.md`. */
+export declare const createPlugin: (config?: JsonObject) => Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,EAAiB,MAAM,oBAAoB,CAAC;AAEvF,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE1F,OAAO,EAA0B,KAAK,aAAa,EAAiC,MAAM,aAAa,CAAC;AAGxG,OAAO,EACL,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAK5E,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0PD,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC9B,SAAQ,UAAe,EACvB,UAAS,oBAAyB,KACjC,MAAM,GAAG;IAAE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAgEhF,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,YAAY,GAAI,SAAQ,UAAe,KAAG,MAAqC,CAAC"}

package/dist/index.js

@@ -0,0 +1,293 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { assertRequestAllowed } from '@stratusagent/egress';
+import { resolvePluginAgentConfig } from '@stratusagent/plugins';
+import { createPlaywrightDriver } from "./driver.js";
+import { BrowserSessionPool } from "./sessions.js";
+export { createPlaywrightDriver, } from "./driver.js";
+export { BrowserSessionPool } from "./sessions.js";
+const DEFAULT_NAVIGATION_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_TEXT_BYTES = 100_000;
+const asNumber = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+/** The address policy a block describes, per-agent or top-level. */
+const policyFrom = (resolved) => ({
+    ...(resolved.allowPrivateAddresses === true ? { allowPrivateAddresses: true } : {}),
+    ...(Array.isArray(resolved.allowedHosts)
+        ? { allowedHosts: resolved.allowedHosts.filter((entry) => typeof entry === 'string') }
+        : {}),
+});
+const settingsFor = (config, session) => {
+    const resolved = resolvePluginAgentConfig(config, session.agent.id);
+    const policy = policyFrom(resolved);
+    return {
+        policy,
+        maxTextBytes: asNumber(resolved.maxTextBytes, DEFAULT_MAX_TEXT_BYTES),
+        navigationTimeoutMs: asNumber(resolved.navigationTimeoutMs, DEFAULT_NAVIGATION_TIMEOUT_MS),
+        workspaceRoot: typeof resolved.workspaceRoot === 'string' ? resolved.workspaceRoot : undefined,
+    };
+};
+/**
+ * Text as a reader would see it, extracted in the page.
+ *
+ * The DOM is right there, so there is nothing to guess at: the furniture is
+ * removed from a clone and what is left is `innerText`, which already
+ * respects what is visible. This is the one place a browser genuinely beats
+ * `web.fetch`, whose extractor has to infer all of it from markup.
+ */
+const READABLE_TEXT_SCRIPT = `(() => {
+  const doc = document.cloneNode(true);
+  for (const element of doc.querySelectorAll('script, style, noscript, svg, nav, header, footer, aside, form')) {
+    element.remove();
+  }
+  const main = doc.querySelector('article, main') ?? doc.body;
+  return main ? main.innerText : '';
+})()`;
+/**
+ * The request-level half of the address policy, inside the browser.
+ *
+ * The proxy the browser is launched through owns every connection it makes,
+ * which is what defeats rebinding — but a `file:` or `data:` URL never
+ * reaches a proxy, and Chromium runs as the daemon user. So schemes are
+ * refused here, on every request the page makes: the navigation itself,
+ * each redirect, and every subresource.
+ */
+const guardRequests = async (page, policy, record) => {
+    await page.route('**/*', async (route) => {
+        const url = route.request().url();
+        try {
+            assertRequestAllowed(url, policy);
+            await route.continue();
+        }
+        catch (error) {
+            record(`${url} — ${error instanceof Error ? error.message : String(error)}`);
+            await route.abort('blockedbyclient');
+        }
+    });
+};
+/**
+ * What was refused while this session's page was loading, from both halves
+ * of the policy: the scheme guard inside the browser, and the proxy that
+ * owns the connections. Reported to the agent because a page that renders
+ * empty because its requests were blocked is otherwise a mystery it retries.
+ */
+const refusalsFor = (runtime, session) => [
+    ...(runtime.blocked.get(session.id) ?? []),
+    ...runtime.pool.refusalsFor(session.id),
+].slice(-10);
+const truncate = (value, maxBytes) => Buffer.byteLength(value, 'utf8') <= maxBytes
+    ? { text: value, truncated: false }
+    : { text: `${value.slice(0, maxBytes)}\n… truncated at ${maxBytes} bytes`, truncated: true };
+const navigate = async (page, rawUrl, policy, timeoutMs) => {
+    // Before navigation, not after: a `file:///…/credentials.json` must never
+    // be handed to the browser at all, because by the time an interception
+    // handler sees it the read has a chance to have happened.
+    const url = assertRequestAllowed(rawUrl, policy);
+    const response = await page.goto(url.href, { timeout: timeoutMs, waitUntil: 'load' });
+    return response?.status();
+};
+const screenshotPathFor = async (workspaceRoot, session, now) => {
+    if (!workspaceRoot) {
+        throw new Error('browser.screenshot has nowhere to write. Set workspaceRoot for @stratusagent/tool-browser, '
+            + 'or run through a daemon that supplies it.');
+    }
+    // One directory per agent, under the workspace root the host resolved:
+    // an agent's output is that agent's, and a shared scratch directory is
+    // two agents reading each other's screenshots.
+    const directory = path.join(workspaceRoot, session.agent.id, 'screenshots');
+    await mkdir(directory, { recursive: true });
+    return path.join(directory, `${new Date(now).toISOString().replace(/[:.]/g, '-')}.png`);
+};
+const createTools = (config, runtime) => {
+    const goto = {
+        name: 'browser.goto',
+        description: 'Open a URL in this conversation’s browser page.',
+        risk: 'gated',
+        parameters: {
+            type: 'object',
+            properties: { url: { type: 'string' } },
+            required: ['url'],
+        },
+        async execute(input, session) {
+            const settings = settingsFor(config, session);
+            const page = await runtime.pageFor(session);
+            const status = await navigate(page, String(input.url ?? ''), settings.policy, settings.navigationTimeoutMs);
+            return {
+                url: page.url(),
+                ...(status === undefined ? {} : { status }),
+                title: await page.title(),
+                ...(refusalsFor(runtime, session).length > 0
+                    ? { blockedRequests: refusalsFor(runtime, session) }
+                    : {}),
+            };
+        },
+    };
+    const read = {
+        name: 'browser.read',
+        description: 'Read the current page as text, optionally navigating first.',
+        risk: 'gated',
+        parameters: {
+            type: 'object',
+            properties: { url: { type: 'string' }, maxBytes: { type: 'number' } },
+        },
+        async execute(input, session) {
+            const settings = settingsFor(config, session);
+            const page = await runtime.pageFor(session);
+            if (typeof input.url === 'string' && input.url.length > 0) {
+                await navigate(page, input.url, settings.policy, settings.navigationTimeoutMs);
+            }
+            const extracted = await page.evaluate(READABLE_TEXT_SCRIPT);
+            const { text, truncated } = truncate(typeof extracted === 'string' ? extracted : '', asNumber(input.maxBytes, settings.maxTextBytes));
+            return {
+                url: page.url(),
+                title: await page.title(),
+                text,
+                truncated,
+                ...(refusalsFor(runtime, session).length > 0
+                    ? { blockedRequests: refusalsFor(runtime, session) }
+                    : {}),
+            };
+        },
+    };
+    const screenshot = {
+        name: 'browser.screenshot',
+        description: 'Save a screenshot of the current page and return its path.',
+        risk: 'gated',
+        parameters: {
+            type: 'object',
+            properties: { url: { type: 'string' }, fullPage: { type: 'boolean' } },
+        },
+        async execute(input, session) {
+            const settings = settingsFor(config, session);
+            const page = await runtime.pageFor(session);
+            if (typeof input.url === 'string' && input.url.length > 0) {
+                await navigate(page, input.url, settings.policy, settings.navigationTimeoutMs);
+            }
+            const target = await screenshotPathFor(settings.workspaceRoot, session, Date.now());
+            await page.screenshot({ path: target, fullPage: input.fullPage === true });
+            // `file`, because that is the key a channel already acts on: an ok
+            // result carrying `file` (or `files`) is delivered as an attachment,
+            // which is how "screenshot example.com and show me" ends with a
+            // picture in Slack rather than a path nobody can open. One key rather
+            // than a `path` alias beside it — two words for one thing is how a
+            // convention stops being one.
+            return { file: target, url: page.url(), title: await page.title() };
+        },
+    };
+    const act = {
+        name: 'browser.act',
+        description: 'Click or type on the current page.',
+        // Dangerous, and the only one here that is: navigating and reading can
+        // be undone by navigating somewhere else, while a click submits, buys,
+        // and deletes. No selector makes that reversible.
+        risk: 'dangerous',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['click', 'type'] },
+                selector: { type: 'string' },
+                value: { type: 'string' },
+            },
+            required: ['action', 'selector'],
+        },
+        async execute(input, session) {
+            const settings = settingsFor(config, session);
+            const page = await runtime.pageFor(session);
+            const selector = String(input.selector ?? '');
+            if (!selector) {
+                throw new Error('selector is required.');
+            }
+            if (input.action === 'type') {
+                await page.fill(selector, String(input.value ?? ''), { timeout: settings.navigationTimeoutMs });
+            }
+            else if (input.action === 'click') {
+                await page.click(selector, { timeout: settings.navigationTimeoutMs });
+            }
+            else {
+                throw new Error(`Unsupported action: ${String(input.action)}. Use click or type.`);
+            }
+            return { action: input.action, selector, url: page.url(), title: await page.title() };
+        },
+    };
+    return [goto, read, screenshot, act];
+};
+/**
+ * The `browser` toolset.
+ *
+ * One browser per plugin, a context per conversation, and an idle sweep
+ * that closes both — see `BrowserSessionPool`. Every request the browser
+ * makes goes through a proxy this plugin owns, which resolves and validates
+ * each address itself, because Chromium resolves names for itself no matter
+ * what an interception handler decided.
+ */
+export const createBrowserPlugin = (config = {}, options = {}) => {
+    const blocked = new Map();
+    const resolved = config;
+    const pool = new BrowserSessionPool({
+        driver: options.driver ?? createPlaywrightDriver(options.moduleHost ?? {
+            resolve: (specifier) => import.meta.resolve(specifier),
+            import: (specifier) => import(__rewriteRelativeImportExtension(specifier)),
+        }),
+        ...(resolved.headless === false ? { headless: false } : {}),
+        ...(typeof resolved.executablePath === 'string' ? { executablePath: resolved.executablePath } : {}),
+        ...(typeof resolved.channel === 'string' ? { channel: resolved.channel } : {}),
+        ...(typeof resolved.idleMs === 'number' ? { idleMs: resolved.idleMs } : {}),
+        ...(typeof resolved.maxContexts === 'number' ? { maxContexts: resolved.maxContexts } : {}),
+        onEvicted: ({ sessionId }) => {
+            // The page that recorded them is gone, so its refusals go with it.
+            blocked.delete(sessionId);
+        },
+    });
+    const runtime = {
+        pool,
+        blocked,
+        async pageFor(session) {
+            const settings = settingsFor(config, session);
+            // The agent's own policy decides which browser serves it: a proxy is
+            // chosen when Chromium launches, so an agent whose config narrows the
+            // address policy needs a browser launched under that policy rather
+            // than a context inside somebody else's.
+            const page = await pool.pageFor(session.id, Date.now(), settings.policy);
+            // Routed once per page. A page created for this session gets the
+            // scheme guard before anything is asked of it.
+            if (!page.__stratusGuarded) {
+                await guardRequests(page, settings.policy, (entry) => {
+                    blocked.set(session.id, [...(blocked.get(session.id) ?? []), entry].slice(-20));
+                });
+                page.__stratusGuarded = true;
+            }
+            return page;
+        },
+    };
+    return {
+        name: '@stratusagent/tool-browser',
+        setup(context) {
+            for (const tool of createTools(config, runtime)) {
+                context.tools.register(tool);
+            }
+        },
+        /**
+         * The kernel's teardown hook, which is what a host actually calls.
+         * Named anything else, a browser and a listening proxy survive both
+         * `stratus run` and a daemon shutdown — the second of which is the
+         * whole reason `Plugin.dispose` exists.
+         */
+        dispose: () => pool.close(),
+        /**
+         * The sweep, for a caller that wants it at a chosen instant. The pool
+         * also runs it on its own timer; this is what makes the behaviour
+         * testable without a test that sleeps.
+         */
+        sweepIdle: (now) => pool.sweepIdle(now),
+    };
+};
+/** The loader's ABI. See `docs/architecture/plugins.md`. */
+export const createPlugin = (config = {}) => createBrowserPlugin(config);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/sessions.d.ts

@@ -0,0 +1,95 @@
+import { type EgressPolicy } from '@stratusagent/egress';
+import type { BrowserDriver, PageLike } from './driver.ts';
+export interface SessionPoolOptions {
+    driver: BrowserDriver;
+    headless?: boolean;
+    executablePath?: string;
+    channel?: string;
+    /** Close a context that has done nothing for this long. */
+    idleMs?: number;
+    /** How many contexts may exist at once. The oldest goes when a new one would exceed it. */
+    maxContexts?: number;
+    /** Called when a page is dropped, so a caller can log it. */
+    onEvicted?: (event: {
+        sessionId: string;
+        reason: 'idle' | 'capacity' | 'shutdown' | 'policy';
+    }) => void;
+    /** Reported rather than thrown: a sweep runs on a timer with nobody waiting on it. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Browsers, contexts, and the proxies that own their connections.
+ *
+ * Three rules, and each of them is a boundary rather than an optimization:
+ *
+ * - **A browser per policy.** A proxy is chosen when Chromium launches, so
+ *   a single shared browser can only ever enforce one address policy — and
+ *   an agent whose config *narrows* it (`allowedHosts: []` over a permissive
+ *   default) would silently get the permissive one. Contexts cannot fix
+ *   that: request interception runs inside the browser and does not resolve
+ *   names, so it cannot narrow a hostname destination without re-opening
+ *   the DNS-rebinding race the proxy exists to close.
+ * - **A context per conversation**, so two conversations never share a
+ *   cookie jar or a login.
+ * - **Nothing left running.** A context that has gone quiet is closed, and
+ *   a browser whose last conversation went with it is closed too.
+ *
+ * The sweep takes the time as an argument *and* runs on a timer. A pool that
+ * only read the clock itself could only be tested by sleeping; one that only
+ * offered the method would leave `idleMs` as a setting nothing honoured.
+ */
+export declare class BrowserSessionPool {
+    private readonly options;
+    private readonly contexts;
+    private readonly browsers;
+    private readonly launching;
+    private sweepTimer;
+    /**
+     * Admission runs one at a time.
+     *
+     * The cap is checked and then a context is created, and creating one
+     * yields — so without this, every call in a burst sees room, and a pool
+     * capped at four opens as many browsers' worth of contexts as there were
+     * simultaneous first calls. A queue is enough: admission is short, and
+     * the alternative (reserving a slot and unwinding it on failure) is the
+     * same serialization with more ways to leak a reservation.
+     */
+    private admission;
+    private closed;
+    constructor(options: SessionPoolOptions);
+    private browserFor;
+    /**
+     * The page this session works in, created on first use — under the
+     * policy resolved for *this* agent, not for whoever asked first.
+     */
+    pageFor(sessionId: string, now: number, policy?: EgressPolicy): Promise<PageLike>;
+    private admit;
+    /**
+     * What the proxy refused for this session's browser.
+     *
+     * Scoped to the browser rather than to the process: an agent under a
+     * different policy has a different browser and never sees these. Two
+     * agents that share a policy share a browser and can see each other's
+     * refused *addresses* — which is the same set their identical policy
+     * already told them about.
+     */
+    refusalsFor(sessionId: string): string[];
+    private drop;
+    /** Close whatever has been idle longer than the timeout. Returns what went. */
+    sweepIdle(now: number): Promise<string[]>;
+    /**
+     * The timer behind `idleMs`. Unref'd, so a pending sweep never holds a
+     * one-shot `stratus run` open, and disarmed as soon as the last browser
+     * goes so an idle daemon carries no timer at all.
+     */
+    private armSweep;
+    private disarmSweep;
+    private closeBrowser;
+    /** Everything, for shutdown. */
+    close(): Promise<void>;
+    /** How many conversations currently hold a page. */
+    get size(): number;
+    /** How many browsers are running — one per distinct address policy. */
+    get browserCount(): number;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAsB,aAAa,EAAe,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5F,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAA;KAAE,KAAK,IAAI,CAAC;IACxG,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAE5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IAEtE,OAAO,CAAC,UAAU,CAA6B;IAE/C;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS,CAAuC;IAExD,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,kBAAkB;YAIzB,UAAU;IAqCxB;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC;YAoB7E,KAAK;IAyDnB;;;;;;;;OAQG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;YAQ1B,IAAI;IAiBlB,+EAA+E;IACzE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAS/C;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,WAAW;YAOL,YAAY;IAa1B,gCAAgC;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B,oDAAoD;IACpD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,uEAAuE;IACvE,IAAI,YAAY,IAAI,MAAM,CAEzB;CACF"}

package/dist/sessions.js

@@ -0,0 +1,253 @@
+import { chromiumProxyOptions, createEgressProxy, policyKeyFor, } from '@stratusagent/egress';
+const DEFAULT_IDLE_MS = 5 * 60_000;
+const DEFAULT_MAX_CONTEXTS = 4;
+const MAX_SWEEP_INTERVAL_MS = 60_000;
+/**
+ * Browsers, contexts, and the proxies that own their connections.
+ *
+ * Three rules, and each of them is a boundary rather than an optimization:
+ *
+ * - **A browser per policy.** A proxy is chosen when Chromium launches, so
+ *   a single shared browser can only ever enforce one address policy — and
+ *   an agent whose config *narrows* it (`allowedHosts: []` over a permissive
+ *   default) would silently get the permissive one. Contexts cannot fix
+ *   that: request interception runs inside the browser and does not resolve
+ *   names, so it cannot narrow a hostname destination without re-opening
+ *   the DNS-rebinding race the proxy exists to close.
+ * - **A context per conversation**, so two conversations never share a
+ *   cookie jar or a login.
+ * - **Nothing left running.** A context that has gone quiet is closed, and
+ *   a browser whose last conversation went with it is closed too.
+ *
+ * The sweep takes the time as an argument *and* runs on a timer. A pool that
+ * only read the clock itself could only be tested by sleeping; one that only
+ * offered the method would leave `idleMs` as a setting nothing honoured.
+ */
+export class BrowserSessionPool {
+    options;
+    contexts = new Map();
+    browsers = new Map();
+    launching = new Map();
+    sweepTimer;
+    /**
+     * Admission runs one at a time.
+     *
+     * The cap is checked and then a context is created, and creating one
+     * yields — so without this, every call in a burst sees room, and a pool
+     * capped at four opens as many browsers' worth of contexts as there were
+     * simultaneous first calls. A queue is enough: admission is short, and
+     * the alternative (reserving a slot and unwinding it on failure) is the
+     * same serialization with more ways to leak a reservation.
+     */
+    admission = Promise.resolve();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async browserFor(policy) {
+        const key = policyKeyFor(policy);
+        const existing = this.browsers.get(key);
+        if (existing) {
+            return existing;
+        }
+        // Single-flight per policy: two calls arriving together must not launch
+        // two browsers, and the second would leak because only one is kept.
+        const pending = this.launching.get(key);
+        if (pending) {
+            return pending;
+        }
+        const launch = (async () => {
+            const proxy = await createEgressProxy(policy);
+            try {
+                const browser = await this.options.driver.launch({
+                    headless: this.options.headless ?? true,
+                    proxy: chromiumProxyOptions(proxy),
+                    ...(this.options.executablePath ? { executablePath: this.options.executablePath } : {}),
+                    ...(this.options.channel ? { channel: this.options.channel } : {}),
+                });
+                const entry = { key, browser, proxy, sessions: new Set() };
+                this.browsers.set(key, entry);
+                this.armSweep();
+                return entry;
+            }
+            catch (error) {
+                await proxy.close();
+                throw error;
+            }
+            finally {
+                this.launching.delete(key);
+            }
+        })();
+        this.launching.set(key, launch);
+        return launch;
+    }
+    /**
+     * The page this session works in, created on first use — under the
+     * policy resolved for *this* agent, not for whoever asked first.
+     */
+    async pageFor(sessionId, now, policy = {}) {
+        const key = policyKeyFor(policy);
+        const existing = this.contexts.get(sessionId);
+        if (existing && existing.browserKey === key) {
+            // The common path, and the only one that does not queue: a
+            // conversation coming back to its own page competes with nobody.
+            existing.lastUsedAt = now;
+            return existing.page;
+        }
+        const admitted = this.admission.then(() => this.admit(sessionId, now, policy, key), () => this.admit(sessionId, now, policy, key));
+        // The queue advances whether or not this admission succeeded; a failed
+        // launch must not block every later call behind it.
+        this.admission = admitted.catch(() => undefined);
+        return admitted;
+    }
+    async admit(sessionId, now, policy, key) {
+        // Re-read inside the queue: another admission may have created this
+        // session's context, or changed what is in the pool, while this one
+        // waited its turn.
+        const existing = this.contexts.get(sessionId);
+        if (existing) {
+            if (existing.browserKey === key) {
+                existing.lastUsedAt = now;
+                return existing.page;
+            }
+            // The agent's policy changed under a live conversation (an edited
+            // config, a soul now resolving different settings). The open context
+            // belongs to a browser enforcing the old one, so it goes.
+            await this.drop(existing, 'policy');
+        }
+        const entry = await this.browserFor(policy);
+        const maxContexts = this.options.maxContexts ?? DEFAULT_MAX_CONTEXTS;
+        while (this.contexts.size >= maxContexts) {
+            const oldest = [...this.contexts.values()].sort((left, right) => left.lastUsedAt - right.lastUsedAt)[0];
+            if (!oldest) {
+                break;
+            }
+            await this.drop(oldest, 'capacity');
+        }
+        const context = await entry.browser.newContext();
+        let page;
+        try {
+            page = await context.newPage();
+        }
+        catch (error) {
+            // A context that never got a page is not in `contexts`, so the idle
+            // sweep will never look at it — and neither will shutdown, which
+            // walks the same map. Closed here or not at all, and the browser
+            // goes too when it turns out nothing is using it (which is also how
+            // a Chromium that died during page creation stops being handed to
+            // the next caller).
+            try {
+                await context.close();
+            }
+            catch {
+                // Already gone with the browser that owned it.
+            }
+            if (entry.sessions.size === 0) {
+                await this.closeBrowser(entry);
+            }
+            throw error;
+        }
+        this.contexts.set(sessionId, { sessionId, context, page, lastUsedAt: now, browserKey: key });
+        entry.sessions.add(sessionId);
+        return page;
+    }
+    /**
+     * What the proxy refused for this session's browser.
+     *
+     * Scoped to the browser rather than to the process: an agent under a
+     * different policy has a different browser and never sees these. Two
+     * agents that share a policy share a browser and can see each other's
+     * refused *addresses* — which is the same set their identical policy
+     * already told them about.
+     */
+    refusalsFor(sessionId) {
+        const context = this.contexts.get(sessionId);
+        if (!context) {
+            return [];
+        }
+        return this.browsers.get(context.browserKey)?.proxy.refusals ?? [];
+    }
+    async drop(entry, reason) {
+        this.contexts.delete(entry.sessionId);
+        try {
+            await entry.context.close();
+        }
+        catch {
+            // A context that is already gone is the outcome we wanted.
+        }
+        const browser = this.browsers.get(entry.browserKey);
+        browser?.sessions.delete(entry.sessionId);
+        if (browser && browser.sessions.size === 0) {
+            // The browser goes with its last conversation: a Chromium sitting
+            // idle overnight is the leak this pack is most likely to cause.
+            await this.closeBrowser(browser);
+        }
+        this.options.onEvicted?.({ sessionId: entry.sessionId, reason });
+    }
+    /** Close whatever has been idle longer than the timeout. Returns what went. */
+    async sweepIdle(now) {
+        const idleMs = this.options.idleMs ?? DEFAULT_IDLE_MS;
+        const expired = [...this.contexts.values()].filter((entry) => now - entry.lastUsedAt >= idleMs);
+        for (const entry of expired) {
+            await this.drop(entry, 'idle');
+        }
+        return expired.map((entry) => entry.sessionId);
+    }
+    /**
+     * The timer behind `idleMs`. Unref'd, so a pending sweep never holds a
+     * one-shot `stratus run` open, and disarmed as soon as the last browser
+     * goes so an idle daemon carries no timer at all.
+     */
+    armSweep() {
+        if (this.sweepTimer || this.closed) {
+            return;
+        }
+        const idleMs = this.options.idleMs ?? DEFAULT_IDLE_MS;
+        const interval = Math.max(1_000, Math.min(idleMs, MAX_SWEEP_INTERVAL_MS));
+        this.sweepTimer = setInterval(() => {
+            void this.sweepIdle(Date.now()).catch((error) => this.options.onError?.(error));
+        }, interval);
+        this.sweepTimer.unref?.();
+    }
+    disarmSweep() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = undefined;
+        }
+    }
+    async closeBrowser(entry) {
+        this.browsers.delete(entry.key);
+        try {
+            await entry.browser.close();
+        }
+        catch {
+            // Same as a context: already gone is fine.
+        }
+        await entry.proxy.close();
+        if (this.browsers.size === 0) {
+            this.disarmSweep();
+        }
+    }
+    /** Everything, for shutdown. */
+    async close() {
+        this.closed = true;
+        this.disarmSweep();
+        for (const entry of [...this.contexts.values()]) {
+            await this.drop(entry, 'shutdown');
+        }
+        // Anything still open had no contexts to take it down — a browser that
+        // launched for a call that then failed, for instance.
+        for (const entry of [...this.browsers.values()]) {
+            await this.closeBrowser(entry);
+        }
+    }
+    /** How many conversations currently hold a page. */
+    get size() {
+        return this.contexts.size;
+    }
+    /** How many browsers are running — one per distinct address policy. */
+    get browserCount() {
+        return this.browsers.size;
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@stratusagent/tool-browser",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.13 <23 || >=23.4"
+  },
+  "dependencies": {
+    "playwright-core": "^1.49.0",
+    "@stratusagent/core": "0.6.0",
+    "@stratusagent/egress": "0.6.0",
+    "@stratusagent/plugins": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3",
+    "@stratusagent/tool-web": "0.6.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stratuslabs/agent.git",
+    "directory": "packages/tool-browser"
+  },
+  "description": "Browser tools for Stratus agents: navigate, read, screenshot, and act, with every request pinned through a policy-owned proxy",
+  "keywords": [
+    "stratus",
+    "agent",
+    "ai",
+    "llm",
+    "stratus-plugin",
+    "tools",
+    "browser",
+    "playwright"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "stratus": {
+    "pluginVersion": 1,
+    "contributes": {
+      "tools": [
+        {
+          "name": "browser.goto",
+          "risk": "gated"
+        },
+        {
+          "name": "browser.read",
+          "risk": "gated"
+        },
+        {
+          "name": "browser.screenshot",
+          "risk": "gated"
+        },
+        {
+          "name": "browser.act",
+          "risk": "dangerous"
+        }
+      ]
+    },
+    "config": {
+      "type": "object",
+      "properties": {
+        "allowPrivateAddresses": {
+          "type": "boolean"
+        },
+        "allowedHosts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "headless": {
+          "type": "boolean"
+        },
+        "executablePath": {
+          "type": "string"
+        },
+        "channel": {
+          "type": "string"
+        },
+        "idleMs": {
+          "type": "integer"
+        },
+        "maxContexts": {
+          "type": "integer"
+        },
+        "maxTextBytes": {
+          "type": "integer"
+        },
+        "navigationTimeoutMs": {
+          "type": "integer"
+        },
+        "workspaceRoot": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
+    "test": "node --test --experimental-strip-types"
+  }
+}