@anvia/browser 1.0.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indra Zulfi
+
+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,106 @@
+# `@anvia/browser`
+
+Visible Chromium ownership and semantic browser tools for Anvia agents. Docker infrastructure remains
+owned by `@anvia/sandbox`; this package owns the browser workload running inside that sandbox.
+
+```ts
+import { DockerBrowserClient, createBrowserTools } from "@anvia/browser";
+import { Agent } from "@anvia/core/agent";
+import { DockerSandboxClient } from "@anvia/sandbox";
+
+const browserClient = new DockerBrowserClient({
+  sandboxClient: new DockerSandboxClient(),
+  image: "ghcr.io/anvia-hq/browser@sha256:...",
+});
+
+await browserClient.pullImage();
+await using browser = await browserClient.createBrowser({
+  workspace: { type: "ephemeral" },
+  network: { mode: "bridge" },
+  desktop: {
+    protocol: "novnc",
+    password: "passw0rd",
+    viewport: { width: 1440, height: 900 },
+  },
+});
+
+await browser.waitUntilReady({ timeoutMs: 30_000 });
+await using connection = await browser.connect();
+
+const tools = createBrowserTools({
+  connection,
+  tools: [
+    "browser_list_tabs",
+    "browser_open_tab",
+    "browser_select_tab",
+    "browser_close_tab",
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_click",
+    "browser_type",
+    "browser_press_key",
+    "browser_screenshot",
+  ],
+  navigation: { mode: "allow-all-http" },
+});
+
+const agent = new Agent({ id: "browser-agent", model, tools });
+```
+
+The client constructor performs no I/O. `pullImage()`, `createBrowser()`, readiness, and CDP
+connection are separate operations. `DockerBrowser` owns the underlying sandbox. A
+`PlaywrightBrowserConnection` owns only its CDP connection and never destroys the browser.
+
+`stop()` preserves the container. `resumeBrowser({ id })` starts a fresh browser service and requires
+a new readiness check and CDP connection. A named Docker volume preserves Chromium profile state even
+when the browser container is destroyed and later recreated with that volume.
+
+The browser tools use ARIA state and strict Playwright locators. They do not expose JavaScript
+evaluation, raw CDP, coordinate input, shell access, hidden retries, or automatic reconnection.
+Aborting an action that Playwright cannot cancel closes the CDP connection and leaves the browser
+running. The selected navigation policy is installed across the connection, so top-level navigation
+from links, forms, redirects, popups, and direct navigation is checked consistently. It does not block
+third-party subresources; Docker bridge networking remains outside that policy.
+
+The image runs Chromium as a non-root user with Chromium sandboxing, the pinned Playwright seccomp
+profile, every Linux capability dropped except the explicit `SYS_CHROOT` capability required by the
+namespace sandbox, no-new-privileges, and private shared memory. Startup fails rather than silently
+switching Chromium to `--no-sandbox`. Docker bridge networking is not an SSRF boundary; use
+infrastructure network policy where browsing untrusted destinations requires isolation.
+
+The VNC protocol uses exactly eight printable ASCII password characters. noVNC is published only on a
+host-loopback Docker port, raw VNC is not published, and the password is not placed in image metadata,
+URLs, environment variables, or logs.
+
+## Studio desktop and takeover
+
+`browser.desktop` is structurally compatible with Studio without creating a package dependency:
+
+```ts
+const studio = new Studio([agent], {
+  sandboxes: [
+    {
+      inspector: browser.inspector({ files: true, ports: true, processes: true }),
+      agentIds: [agent.id],
+      toolNames: tools.map((tool) => tool.name),
+      views: [
+        {
+          id: "desktop",
+          label: "Browser",
+          source: browser.desktop,
+          access: { mode: "local" },
+          authentication: { type: "password", password },
+        },
+      ],
+    },
+  ],
+});
+```
+
+Use `{ mode: "authorize", authorize }` when Studio is reachable remotely. The callback is invoked for
+the viewer connection, WebSocket upgrade, and every control operation. When the registered agent uses a
+matching browser tool, Studio opens its clean programmatic noVNC viewer in a resizable Playground panel;
+there is no stock noVNC toolbar, splash, or password prompt. Closing the panel restores Sessions and an
+**Open browser** action restores the current desktop. Studio human takeover waits for an active agent
+action, blocks new browser tool actions, and expires unless the Studio viewer renews its lease. Takeover
+coordinates trusted viewers; application authorization remains the security boundary.

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { DockerSandboxWorkspace, DockerSandboxResources, DockerSandboxRuntimeLimits, DockerSandboxState, DockerSandbox, DockerSandboxInspectionOptions, DockerSandboxInspector, DockerSandboxClient } from '@anvia/sandbox';
+import { AnyTool } from '@anvia/core/tool';
+
+type DockerBrowserClientOptions = Readonly<{
+    sandboxClient: DockerSandboxClient;
+    image: string;
+}>;
+type PullDockerBrowserImageOptions = Readonly<{
+    abortSignal?: AbortSignal;
+}>;
+type BrowserViewport = Readonly<{
+    width: number;
+    height: number;
+}>;
+type BrowserDesktopOptions = Readonly<{
+    protocol: "novnc";
+    password: string;
+    viewport: BrowserViewport;
+}>;
+type CreateDockerBrowserOptions = Readonly<{
+    id?: string;
+    workspace: DockerSandboxWorkspace;
+    network: Readonly<{
+        mode: "bridge";
+    }>;
+    desktop: BrowserDesktopOptions;
+    resources?: DockerSandboxResources;
+    runtime?: DockerSandboxRuntimeLimits;
+    abortSignal?: AbortSignal;
+}>;
+type ResumeDockerBrowserOptions = Readonly<{
+    id: string;
+    abortSignal?: AbortSignal;
+}>;
+type BrowserWaitUntilReadyOptions = Readonly<{
+    timeoutMs: number;
+    abortSignal?: AbortSignal;
+}>;
+type BrowserConnectOptions = Readonly<{
+    abortSignal?: AbortSignal;
+}>;
+type BrowserControlSnapshot = Readonly<{
+    mode: "agent" | "human";
+    ownerId?: string;
+    expiresAt?: string;
+}>;
+type AcquireBrowserHumanControlOptions = Readonly<{
+    ownerId: string;
+    leaseTimeoutMs: number;
+    abortSignal?: AbortSignal;
+}>;
+type RenewBrowserHumanControlOptions = Readonly<{
+    leaseTimeoutMs: number;
+}>;
+interface BrowserHumanControlLease extends AsyncDisposable {
+    readonly id: string;
+    readonly ownerId: string;
+    readonly expiresAt: string;
+    renew(options: RenewBrowserHumanControlOptions): BrowserControlSnapshot;
+    release(): void;
+}
+interface BrowserControl {
+    snapshot(): BrowserControlSnapshot;
+    acquireHumanControl(options: AcquireBrowserHumanControlOptions): Promise<BrowserHumanControlLease>;
+}
+type BrowserDesktopEndpoint = Readonly<{
+    protocol: "novnc";
+    containerPort: 6080;
+    control: BrowserControl;
+}>;
+interface DockerBrowser extends AsyncDisposable {
+    readonly id: string;
+    readonly state: DockerSandboxState;
+    readonly desktop: BrowserDesktopEndpoint;
+    readonly sandbox: DockerSandbox;
+    inspector(options: DockerSandboxInspectionOptions): DockerSandboxInspector;
+    waitUntilReady(options: BrowserWaitUntilReadyOptions): Promise<void>;
+    connect(options?: BrowserConnectOptions): Promise<PlaywrightBrowserConnection>;
+    stop(options?: Readonly<{
+        abortSignal?: AbortSignal;
+    }>): Promise<void>;
+    destroy(): Promise<void>;
+}
+type BrowserTab = Readonly<{
+    id: string;
+    title: string;
+    url: string;
+    selected: boolean;
+}>;
+interface PlaywrightBrowserConnection extends AsyncDisposable {
+    readonly closed: boolean;
+    listTabs(): Promise<readonly BrowserTab[]>;
+    disconnect(): Promise<void>;
+}
+type BrowserToolName = "browser_list_tabs" | "browser_open_tab" | "browser_select_tab" | "browser_close_tab" | "browser_navigate" | "browser_snapshot" | "browser_click" | "browser_type" | "browser_press_key" | "browser_screenshot";
+type BrowserNavigationPolicy = Readonly<{
+    mode: "allow-all-http";
+}> | Readonly<{
+    mode: "origins";
+    origins: readonly string[];
+}>;
+type BrowserToolLimits = Readonly<{
+    actionTimeoutMs?: number;
+    navigationTimeoutMs?: number;
+    snapshotMaxChars?: number;
+}>;
+type CreateBrowserToolsOptions = Readonly<{
+    connection: PlaywrightBrowserConnection;
+    tools: readonly [BrowserToolName, ...BrowserToolName[]];
+    navigation: BrowserNavigationPolicy;
+    limits?: BrowserToolLimits;
+}>;
+
+declare class DockerBrowserClient {
+    private readonly sandboxClient;
+    private readonly image;
+    constructor(options: DockerBrowserClientOptions);
+    pullImage(options?: PullDockerBrowserImageOptions): Promise<void>;
+    createBrowser(options: CreateDockerBrowserOptions): Promise<DockerBrowser>;
+    resumeBrowser(options: ResumeDockerBrowserOptions): Promise<DockerBrowser>;
+}
+
+type BrowserErrorCode = "connection_closed" | "human_controlled" | "invalid_state" | "navigation_blocked" | "not_ready" | "startup_failed";
+declare class BrowserError extends Error {
+    readonly code: BrowserErrorCode;
+    constructor(message: string, code: BrowserErrorCode, options?: ErrorOptions);
+}
+
+declare function createBrowserTools(options: CreateBrowserToolsOptions): readonly AnyTool[];
+
+export { type AcquireBrowserHumanControlOptions, type BrowserConnectOptions, type BrowserControl, type BrowserControlSnapshot, type BrowserDesktopEndpoint, type BrowserDesktopOptions, BrowserError, type BrowserErrorCode, type BrowserHumanControlLease, type BrowserNavigationPolicy, type BrowserTab, type BrowserToolLimits, type BrowserToolName, type BrowserViewport, type BrowserWaitUntilReadyOptions, type CreateBrowserToolsOptions, type CreateDockerBrowserOptions, type DockerBrowser, DockerBrowserClient, type DockerBrowserClientOptions, type PlaywrightBrowserConnection, type PullDockerBrowserImageOptions, type RenewBrowserHumanControlOptions, type ResumeDockerBrowserOptions, createBrowserTools };