@openagt/dashboard 0.0.0-stage → 0.9.0

package/dist/module-types/dashboard/module/index.d.ts

@@ -0,0 +1,335 @@
+import { type ComponentType } from 'react';
+import type { AgentStatus } from '../../src/index.js';
+import type { ModuleCommandResult, ModuleReadResult } from '../rpc/modules.js';
+export type { ModuleCommandResult, ModuleReadResult, AgentStatus };
+/** A registered project that has the module's package, as a page gets it. */
+export interface ModuleProject {
+    id: string;
+    name: string;
+    /** Whether one of the project's packages provides a git host; without one no pull request can be opened there. */
+    gitHost: boolean;
+}
+/**
+ * What a module page is rendered with. A page reads its sub-path and navigates within itself
+ * through {@link ModuleHost.openPage}; the dashboard's own pages reach it the same way, by the
+ * link convention below.
+ *
+ * A link into a project's files (`ModuleLink.href` such as `tickets/2026-01-01_x.md`) opens the
+ * mounted page named by its first segment, at `/<segment>/<projectId>/<rest…>`: the path a page
+ * gets for it is `[projectId, ...rest]`. So a page that shows one project's file under its own
+ * segment is where every such link in the dashboard lands, and the dashboard names no page.
+ */
+export interface ModulePageProps {
+    /** The registered projects whose dependencies include the module's package, in the registry's order. */
+    projects: ModuleProject[];
+    /** The URL's segments after the page's own, decoded: `/logs/a` gives `['a']`. */
+    path: string[];
+}
+/** A page a module adds: its own URL segment and its row in the sidebar. */
+export interface ModulePage {
+    /** The page's URL, `/<segment>`: a lowercase letter, then lowercase letters and digits (never a project's id, which always has a dash). */
+    segment: string;
+    /** The sidebar row's label. */
+    label: string;
+    /** The sidebar row's icon; a generic one when absent. */
+    icon?: ComponentType<{
+        className?: string;
+        'aria-hidden'?: boolean;
+    }>;
+    /** The page itself. */
+    Page: ComponentType<ModulePageProps>;
+}
+/**
+ * A link a dashboard page shows (#1774): the name of some work and where it points. What a
+ * {@link LinkAction} is given. The dashboard knows nothing of what the link names; the page that
+ * shows it does, and says so in these three fields.
+ */
+export interface ModuleLink {
+    /** The link's text: the name of the work. */
+    text: string;
+    /**
+     * Where the link points: a path inside the project's repository (`tickets/2026-01-01_x.md`) or an
+     * absolute URL. Absent for plain text that names work without pointing anywhere.
+     */
+    href?: string;
+    /** How urgent the page says the work is, 0 (only if capacity) to 10 (critical); absent when the page does not say. */
+    priority?: number;
+}
+/** What a link action did: done, or stopped, with the reason the action or its command gave. */
+export type LinkActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * An action a module offers on the links dashboard pages show (#1774): one verb, done by the
+ * module package's own command. The dashboard shows it as a button beside any link whose project
+ * has the module's package, with no page naming the module: the page shows links, the module acts
+ * on links, the dashboard puts the two together.
+ */
+export interface LinkAction {
+    /** The button's label, a short verb phrase: "Add to queue". */
+    label: string;
+    /** What the button says once the action is done: "Queued". The label with a check mark otherwise. */
+    doneLabel?: string;
+    /** The button's icon; none otherwise. */
+    icon?: ComponentType<{
+        className?: string;
+        'aria-hidden'?: boolean;
+    }>;
+    /**
+     * Act on the links, in the order given, all in one project. `host` runs the module package's
+     * own commands in that project. A batch stops at its first failure and says why.
+     */
+    run(host: ModuleHost, projectId: string, links: ModuleLink[]): Promise<LinkActionResult>;
+}
+/** What a module card is rendered with: the projects that have its package, never none: the card is not drawn then. With a project picked in the dashboard, that project alone. A card has no URL and no sub-path. */
+export interface ModuleCardProps {
+    /** The registered projects that have the module's package, in the registry's order; with a project picked in the dashboard, that project alone. Never empty. */
+    projects: ModuleProject[];
+}
+/**
+ * A card a module adds to the Overview (#1818): the package's own summary of its data across the
+ * projects that have it, drawn beside the dashboard's own cards. Drawn only when one of the
+ * projects the Overview shows has the package: with a project picked, only when that project has it.
+ */
+export interface ModuleCard {
+    /** Which card this is, for the shell's key and its error line; never shown as a title. */
+    id: string;
+    /** Its place among every installed package's cards, lower first; 50 when unsaid, ties by package name. */
+    order?: number;
+    /** The card itself. */
+    Card: ComponentType<ModuleCardProps>;
+}
+/** What a Settings section is rendered with: the projects that have its package. */
+export interface ModuleSettingsProps {
+    /** The registered projects whose dependencies include the module's package, in the registry's order. */
+    projects: ModuleProject[];
+}
+/**
+ * A section a module adds to the Settings page: the package's own settings, read and written
+ * through its own command, drawn after the dashboard's own sections. A package with no projects
+ * registered shows none.
+ */
+export interface ModuleSettings {
+    /** Which section this is, for the shell's key and its error line; the section draws its own title. */
+    id: string;
+    /** Its place among every installed package's sections, lower first; 50 when unsaid, ties by package name. */
+    order?: number;
+    /** The section itself, usually a {@link SettingsSection} of rows. */
+    Section: ComponentType<ModuleSettingsProps>;
+}
+/** How saving a usage limit went: done, or stopped, with the reason the module's command gave. */
+export type UsageLimitSaved = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The stop line a module puts on the Overview's usage bar: where its unattended work stops, as an
+ * offset from the quota boundary in percentage points, negative before it and positive past it.
+ * The bar draws the line and its handle, and asks the module to read the offset and to save the
+ * one a drag picked, through the module package's own command. The first module that declares one
+ * (in package order) has the line.
+ */
+export interface ModuleUsageLimit {
+    /** The offset in force across the projects, or undefined when none says one: the bar then draws no line. */
+    read(host: ModuleHost, projects: ModuleProject[]): Promise<number | undefined>;
+    /** Save the offset the handle was dragged to, within ±{@link MAX_SPEND_OFFSET}. */
+    save(host: ModuleHost, projects: ModuleProject[], points: number): Promise<UsageLimitSaved>;
+}
+/**
+ * The Context as a side-rail tab sees it (#504): the files the next run is pointed at. A tab may
+ * show which files are in it and add or remove one.
+ */
+export interface ModuleContext {
+    /** The Context's files, as repo-relative paths. */
+    files: ReadonlySet<string>;
+    /** Add the path to the Context, or take it out when it is in. */
+    toggle(path: string): void;
+}
+/** What a side-rail tab is rendered with: the project on screen, the run selected in it (if any), the Context. */
+export interface ModulePanelProps {
+    projectId: string;
+    /** The run whose page this is; absent on the project's own page. */
+    agentId?: string;
+    /**
+     * How many events the run's feed has shown: it grows each time the agent does something, so a
+     * tab showing what the agent changes reads again then, rather than on its next poll. Absent on
+     * the project's own page.
+     */
+    activity?: number;
+    /**
+     * On a tab that lists what a run changed (`changes`): the changed file a click in the chat
+     * asked to see, by its path in the run's checkout. `at` tells one ask from the next for the
+     * same file. Absent until a file is asked for.
+     */
+    reveal?: {
+        path: string;
+        at: number;
+    };
+    context: ModuleContext;
+}
+/**
+ * A tab a module adds to the side rail (#492), shown on every project's page and every run's page
+ * of the projects that have the module, before the dashboard's own tabs. A tab with nothing to
+ * show says so inside it: the rail cannot know a module is empty without rendering it.
+ */
+export interface ModulePanel {
+    /** Which tab this is among the module's own, for the rail's key and its remembered pick. */
+    id: string;
+    /** The tab's label. */
+    label: string;
+    /** The tab's tooltip: one sentence on what it shows. */
+    help: string;
+    /** A count shown on the tab beside its label; none when absent or 0. */
+    count?(props: ModulePanelProps): number;
+    /**
+     * This tab lists what a run changed. The chat's row of a changed file then opens the side panel
+     * on it, and hands it the file as `reveal`. Without such a tab, those rows open nothing.
+     */
+    changes?: true;
+    /** The tab's contents. */
+    Panel: ComponentType<ModulePanelProps>;
+}
+/** What a run slot is rendered with: the run, and whether its agent is working. */
+export interface ModuleRunProps {
+    projectId: string;
+    agentId: string;
+    /** The run's agent is still working: a run that ended, or stopped on a question, is not. */
+    working: boolean;
+}
+/**
+ * What a module adds to a run's page: `summary`, a few words in the bar above the message box,
+ * shown until the run has ended and its branch has been read (the dashboard's own words about the
+ * branch take over then).
+ */
+export interface ModuleRunSlots {
+    summary?: ComponentType<ModuleRunProps>;
+}
+/** What a module's browser part default-exports. */
+export interface ModuleDefinition {
+    /** The pages the module adds, each with a sidebar row. */
+    pages?: ModulePage[];
+    /** The cards the module adds to the Overview. */
+    cards?: ModuleCard[];
+    /** The actions the module offers on the links dashboard pages show, wherever the link's project has the module's package. */
+    linkActions?: LinkAction[];
+    /** The tabs the module adds to the side rail. */
+    panels?: ModulePanel[];
+    /** What the module adds to a run's page. */
+    run?: ModuleRunSlots;
+    /** The sections the module adds to the Settings page. */
+    settings?: ModuleSettings[];
+    /** The stop line the module puts on the usage bar. */
+    usageLimit?: ModuleUsageLimit;
+    /** A stylesheet to load with the module, relative to the module's browser part's own URL. */
+    stylesheet?: string;
+}
+/** Type the default export: `export default defineModule({ ... })`. */
+export declare function defineModule(definition: ModuleDefinition): ModuleDefinition;
+/** A run of a project as the dashboard knows it (#1774): enough for a page to name one and link to it. */
+export interface ModuleAgent {
+    /** The run's id, the one {@link ModuleHost.openAgent} takes. */
+    id: string;
+    /** The run's branch, the name the agent gave its work, when its record carries one. */
+    name?: string;
+    /** What the run was asked, as typed or as queued; absent when its record carries none. */
+    ask?: string;
+    status: AgentStatus;
+    /** ISO 8601. */
+    startedAt: string;
+}
+/** What starting a run answered: the run's id, or in words why there is none. */
+export type StartRunResult = {
+    ok: true;
+    agentId: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * What the dashboard gives the module it is rendering. Every service is generic — a project, a
+ * run, a page, a command — and none names a skill: what a module composes out of them is its own.
+ */
+export interface ModuleHost {
+    /** The package the module came from: the one whose commands {@link runCommand} runs. */
+    package: string;
+    /**
+     * Run one of the module package's own commands in one project and get its JSON output: the
+     * same command an agent runs (`npx <command> …`). `command` names one when the package has several.
+     */
+    runCommand(projectId: string, args: string[], command?: string): Promise<ModuleCommandResult>;
+    /**
+     * The same, for a command that changes the project's data (a claim released, an entry added):
+     * the dashboard then syncs the project's data with origin and forgets what it had read, so the
+     * change shows at once instead of at the next sync. A link action's host runs every command so.
+     */
+    act(projectId: string, args: string[], command?: string): Promise<ModuleCommandResult>;
+    /**
+     * Call one of the module's own server reads (its package's `./server`) in one project, with
+     * `input`, a JSON object; `input.agentId` names the run the read is about, when it is about one.
+     * Answered in the daemon's own process, so it suits a read made every few seconds.
+     */
+    read(projectId: string, name: string, input?: Record<string, unknown>): Promise<ModuleReadResult>;
+    /** Open one agent's page in the dashboard: its live feed while it runs, its record after. */
+    openAgent(projectId: string, agentId: string): void;
+    /** Open a page a module adds (this one's or another's), at a sub-path: `openPage('tickets', [projectId, file])`. With a project picked in the dashboard, a page that project's packages do not add shows "No such page". */
+    openPage(segment: string, path?: string[]): void;
+    /**
+     * Start a run in one project with this prompt, with the person's own picks (which tool, which
+     * model, where it runs), and land on it, unless `land` is false: then the dashboard stays where
+     * it is, for a module that starts several runs in a row. Answers the run's id, or why there is none.
+     */
+    startRun(projectId: string, prompt: string, opts?: {
+        land?: boolean;
+    }): Promise<StartRunResult>;
+    /** Open the project's launcher with this prompt drafted in, to set it up before sending: "Configure first, then run". */
+    configureRun(projectId: string, prompt: string): void;
+    /** The project's runs the dashboard knows: the ones running, and the recorded ones when the project records them. */
+    agents(projectId: string): Promise<ModuleAgent[]>;
+}
+/** What the dashboard knows about the module it is serving: every service but the commands and the reads, which it binds to the package. */
+export type ModuleHostBase = Omit<ModuleHost, 'runCommand' | 'act' | 'read'>;
+/**
+ * The host for one module: the dashboard's services, and its commands bound to the module's own
+ * package. `acts` marks every command as an action on the project rather than a page's read: the
+ * dashboard builds a link action's host with it, so what the action wrote is read back at once.
+ */
+export declare function moduleHost(base: ModuleHostBase, opts?: {
+    acts?: boolean;
+}): ModuleHost;
+/**
+ * Set by the dashboard around every module page it renders: the module's package and the
+ * dashboard's services. A test of a module page provides a whole host here, commands included,
+ * and {@link useModuleHost} hands it over as it is.
+ */
+export declare const ModuleHostContext: import("react").Context<ModuleHost | ModuleHostBase | null>;
+/** The dashboard's services for the module being rendered. Only valid inside a module page. */
+export declare function useModuleHost(): ModuleHost;
+export { Button, buttonVariants, type ButtonProps } from '../components/ui/button.js';
+export { Badge } from '../components/ui/badge.js';
+export { Card, CardHeader, CardTitle, CardContent } from '../components/ui/card.js';
+export { Skeleton } from '../components/ui/skeleton.js';
+export { Checkbox } from '../components/ui/checkbox.js';
+export { Input } from '../components/ui/input.js';
+export { Popover, PopoverContent, PopoverTrigger } from '../components/ui/popover.js';
+export { RangeSlider } from '../components/ui/slider.js';
+export { Separator } from '../components/ui/separator.js';
+export { PreviewCard } from '@base-ui-components/react/preview-card';
+export { DiffStat } from '../components/DiffStat.js';
+export { ScrollArea } from '../components/ui/scroll-area.js';
+export { Tooltip, TooltipTrigger, TooltipContent } from '../components/ui/tooltip.js';
+export { DropdownMenu, DropdownMenuContent, DropdownMenuCheckboxItem, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from '../components/ui/dropdown-menu.js';
+export { Markdown } from '../components/Markdown.js';
+export { StartAgentButton } from '../components/StartAgentButton.js';
+export { LinkActions, type ProjectLinks, type LinkTargets } from '../components/LinkActions.js';
+export { cn } from '../lib/utils.js';
+export { SettingsSection, SettingsRow, SettingsSelectRow, type SettingsOption } from '../components/SettingsRows.js';
+export { useCodingAgents, type CodingAgent } from '../lib/models.js';
+export { MAX_SPEND_OFFSET } from '../../src/preference-defaults.js';
+export { formatRelative, formatDateTime, formatDuration, formatAge } from '../lib/format-date.js';
+export { usePolled, useLoaded, forgetRemembered } from '../lib/use-async.js';
+export { useAction } from '../lib/use-action.js';

package/dist/module-types/dashboard/rpc/models.d.ts

@@ -0,0 +1,2 @@
+export type * from '../../src/dashboard/models.js';
+export declare const onModels: () => Promise<import("./models.js").ModelsView>;

package/dist/module-types/dashboard/rpc/modules.d.ts

@@ -0,0 +1,5 @@
+import type * as impl from '../../src/dashboard-rpc/modules.js';
+export type * from '../../src/dashboard-rpc/modules.js';
+export declare const onModules: () => Promise<impl.DashboardModule[]>;
+export declare const runModuleCommand: (projectId: string, pkg: string, args: string[], command?: string | undefined, acts?: boolean | undefined) => Promise<import("@openagt/agent-data").PackageCommandResult>;
+export declare const readModule: (projectId: string, pkg: string, name: string, input: unknown) => Promise<impl.ModuleReadResult>;

package/dist/module-types/src/agent-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An agent's id, derived from the moment it starts. Pure — no node imports — because the sweep
+ * that mints ids ahead of a claim (#1748) is reachable from the dashboard's browser bundle.
+ */
+/** Filesystem-safe, lexicographically-sortable agent id from an ISO start time. */
+export declare function agentIdFromStartedAt(startedAt: string): string;
+/**
+ * The inverse of {@link agentIdFromStartedAt}, for a caller that has the id but not the meta
+ * (#1251): picking which PR is the agent's needs the start time to tell the agent's own PR from a
+ * predecessor's on the same branch name. Undefined for an id that is not one of ours.
+ */
+export declare function startedAtFromAgentId(id: string): string | undefined;

package/dist/module-types/src/agent-locks.d.ts

@@ -0,0 +1,2 @@
+/** Run `fn` once every earlier holder of `checkout`'s lock has settled. */
+export declare function withAgentLock<T>(checkout: string, fn: () => Promise<T>): Promise<T>;

package/dist/module-types/src/agent-view.d.ts

@@ -0,0 +1,38 @@
+import type { OpenAgentEvent } from './events.js';
+/** One error of a run: one the agent reported through an `error` block (#1500), or one its tool wrote in the diary. */
+export interface AgentError {
+    /** What is wrong, in one line. */
+    headline: string;
+    /** What it ran and what that said, when the agent wrote any. */
+    detail?: string;
+}
+/**
+ * Every error of the run (#1500), oldest first — the count the dashboard shows on the session, and
+ * the latest headline it shows beside it. Two sources: the `error` lines the run's tool writes in
+ * the diary when the coding agent or its transport fails (the message's first line is the
+ * headline, the rest the detail), and the `error` blocks of runs recorded before the daemon
+ * stopped running agents.
+ *
+ * A fold over the log rather than state of its own: an error is an event that happened, so the
+ * list only ever grows, and reopening a finished agent shows exactly what it showed while it ran.
+ */
+export declare function agentErrors(events: readonly OpenAgentEvent[]): AgentError[];
+/** The wrapped agent session (#431): its id and a deep link, when one is known. */
+export interface SessionInfo {
+    sessionId?: string;
+    sessionLink?: string;
+    /**
+     * The directory the agent ran in (#1195), from the opening `session` event.
+     *
+     * Taken from the event rather than the filesystem on purpose: an agent that finishes cleanly has
+     * its worktree removed (`tearDownWorktree`), so the event is the only surviving record of where
+     * the session lived — and that path is exactly what `claude --resume` needs to find it again.
+     */
+    workspace?: string;
+}
+/**
+ * The session behind the agent (#431): the workspace from the opening `session`
+ * event, then the id and any deep link from the latest `session-update`. Null before the
+ * session opens. The link is what the old dashboard surfaced as "open session".
+ */
+export declare function sessionInfo(events: readonly OpenAgentEvent[]): SessionInfo | null;

package/dist/module-types/src/bridge-browser.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The bridge browser (#1332): a Chrome for Testing the daemon launches and owns, with the Claude
+ * web bridge extension installed, signed in to claude.ai once by the user and kept minimized.
+ *
+ * The bridge's far end is a browser signed in to claude.ai. Until now that was the user's own
+ * Chrome with the extension loaded, so a web run could only start — and a parked question could
+ * only be noticed — while that Chrome happened to be open. The spike on #1332 settled what a
+ * browser nobody attends has to be: headed, because claude.ai's Cloudflare gate never clears a
+ * headless one; Chrome for Testing, because branded Chrome stopped loading unpacked extensions
+ * from the command line; and installed over CDP with developer mode on, because an extension
+ * loaded any other way is disabled the first time it reloads itself (#1712).
+ *
+ * Nothing here talks to claude.ai. The daemon launches the browser, hands the extension the
+ * bridge token, and from then on the extension's Driver tab does exactly what it does in the
+ * user's own Chrome — the daemon only keeps the window out of the way and brings it up when the
+ * user has to sign in.
+ */
+/** The directory holding the bridge browser's profile and binary, next to the registry file. */
+export declare const BRIDGE_BROWSER_DIR = "openagent-browser";
+/**
+ * Where the bridge browser lives: `$XDG_CONFIG_HOME/openagent-browser` when set, else the
+ * dotted `$HOME/.openagent-browser`. Beside the registry, so the same variable that isolates
+ * a test's registry isolates its browser, and a machine's real one is never touched from a test.
+ * The profile inside it is persistent on purpose: the user signs in once and the sign-in outlives
+ * every daemon restart.
+ */
+export declare function bridgeBrowserDir(env: NodeJS.ProcessEnv): string;
+/**
+ * The launch flags. Headed (no `--headless`): claude.ai's bot gate rejects a headless browser
+ * outright, and a headed one whose window is minimized passes. The unsafe-extension-debugging
+ * flag is what lets `Extensions.loadUnpacked` install the extension over CDP. The keychain flags
+ * keep the cookie-encryption key out of the OS keychain (macOS asks for the login password on
+ * every launch otherwise, and Linux for the wallet) — the same choice Puppeteer makes; the profile
+ * directory's own permissions are what guard the sign-in.
+ */
+export declare function bridgeBrowserLaunchArgs(port: number, profileDir: string): string[];
+/** Where the extension's files are, and whether that is a checkout, where they are edited in place. */
+export interface BridgeExtensionSource {
+    dir: string;
+    checkout: boolean;
+}
+/**
+ * The extension's files (#1720): the checkout's `packages/chrome-extension` next to this package,
+ * so an edit there reaches the browser through the extension's self-reload; else the copy the
+ * build puts in `dist/chrome-extension`, which is what an installed package has. A folder counts
+ * only when its manifest names the bridge extension. Undefined when neither is there.
+ * `moduleUrl` is this file's URL; tests point it elsewhere.
+ */
+export declare function bridgeExtensionSource(moduleUrl?: string): BridgeExtensionSource | undefined;
+/**
+ * The process holding a profile's singleton lock, or undefined when nothing does. Chrome leaves
+ * the lock behind as a symlink whose target is `<host>-<pid>`; a daemon that died without closing
+ * its browser leaves that browser running, and a second Chrome on the same profile would hand its
+ * command line to the first and exit at once.
+ */
+export declare function profileLockOwner(profileDir: string, readLink?: (path: string) => Promise<string>): Promise<number | undefined>;
+/** One page, worker or browser-internal target Chrome lists. */
+export interface CdpTarget {
+    id: string;
+    type: string;
+    url: string;
+    webSocketDebuggerUrl?: string;
+}
+/** A session on one target: the calls go to that page or worker rather than to the browser. */
+export interface CdpTargetSession {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    close(): void;
+}
+/** How the daemon talks to its browser. Injectable: the real one speaks WebSocket to Chrome. */
+export interface BridgeBrowserCdp {
+    /** A browser-level call: installing the extension, opening and closing targets, window bounds. */
+    call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Every target Chrome lists — pages, the extension's worker, browser-internal pages. */
+    targets(): Promise<CdpTarget[]>;
+    /** Attach to one target. */
+    attach(target: CdpTarget): Promise<CdpTargetSession>;
+    /** Drop the browser-level connection. The browser keeps running. */
+    close(): void;
+}
+/** The real connection: the browser socket from `/json/version`, targets from `/json/list`. */
+export declare function connectBridgeBrowser(browserUrl: string): Promise<BridgeBrowserCdp>;
+/** Install the extension from its directory. Chrome answers with the extension's id. */
+export declare function installExtension(cdp: BridgeBrowserCdp, extensionDir: string): Promise<string>;
+/**
+ * The developer-mode switch on Chrome's extensions page, flipped on if it is off. Chrome (137
+ * and later) disables an unpacked extension on reload while the mode is off, and the extension
+ * reloads itself whenever its files change (#1712), so without this the bridge would die on the
+ * first edit or pull. The profile remembers the setting, but writing the preference into the
+ * profile directly does nothing — the switch is the one way that works.
+ */
+export declare const DEVELOPER_MODE_ON = "(() => {\n  const manager = document.querySelector('extensions-manager')?.shadowRoot\n  const toggle = manager?.querySelector('extensions-toolbar')?.shadowRoot?.querySelector('#devMode')\n  if (!toggle) return 'missing'\n  if (!toggle.checked) toggle.click()\n  return 'on'\n})()";
+/** Open Chrome's extensions page in the background, switch developer mode on, close the page. */
+export declare function enableDeveloperMode(cdp: BridgeBrowserCdp, sleep: (ms: number) => Promise<void>): Promise<void>;
+/**
+ * What the extension is told, run inside its own worker: the daemon's address and the bridge
+ * token go into the storage its options page would have written, and the Driver tab is opened
+ * as the one pinned claude.ai/code tab — the shape the extension adopts as its Driver — in place
+ * of the blank page the browser started on. Opened here rather than left to the extension
+ * because the extension opens no Driver tab while the daemon lists no cloud session, and the user
+ * signs in on that tab before any session exists.
+ */
+export declare function seedExpression(daemonUrl: string, token: string): string;
+/** Hand the freshly installed extension its daemon and token, in its service worker. */
+export declare function seedExtension(cdp: BridgeBrowserCdp, extensionId: string, daemonUrl: string, token: string, sleep: (ms: number) => Promise<void>): Promise<void>;
+/** The bridge browser once it runs. */
+export interface BridgeBrowser {
+    extensionId: string;
+    /** The path the claude.ai tab is on (`/login` while signed out), or undefined without such a tab. */
+    page(): Promise<string | undefined>;
+    /** Restore the window and bring the browser to the front, for the user to sign in. */
+    show(): Promise<void>;
+    /** Minimize the window again. */
+    hide(): Promise<void>;
+    /** Called once if Chrome exits on its own — the user quit it, or it crashed. */
+    onExit(listener: (detail: string) => void): void;
+    /** Close the browser. Safe to call twice. */
+    close(): Promise<void>;
+}
+/** The Chrome process, as much of it as this module needs. */
+export interface BridgeBrowserProcess {
+    pid?: number | undefined;
+    kill(signal?: NodeJS.Signals): unknown;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+}
+/** Everything the launch touches outside its own logic. Injectable so the sequence is testable without a Chrome. */
+export interface BridgeBrowserDeps {
+    /** The Chrome for Testing binary, downloaded into `cacheDir` if none is there yet. */
+    binary(cacheDir: string, report: (detail: string) => void): Promise<string>;
+    /** The process holding the profile's lock, if any. */
+    lockOwner(profileDir: string): Promise<number | undefined>;
+    alive(pid: number): boolean;
+    kill(pid: number, signal: NodeJS.Signals): void;
+    port(): Promise<number>;
+    spawn(binary: string, args: string[]): BridgeBrowserProcess;
+    ready(browserUrl: string): Promise<boolean>;
+    connect(browserUrl: string): Promise<BridgeBrowserCdp>;
+    /** Bring the browser application to the front (macOS: activate the app bundle). */
+    activate(binary: string): void;
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * The Chrome for Testing binary in `cacheDir`, or the current stable one downloaded there (about
+ * 150 MB, once). Chrome for Testing rather than whatever Chrome the machine has: branded Chrome
+ * ignores an unpacked extension handed to it from outside, and the agent's own browser lookup
+ * would find exactly that.
+ */
+export declare function bridgeBrowserBinary(cacheDir: string, report: (detail: string) => void): Promise<string>;
+/** macOS: the `.app` bundle the binary lives in, which `open` activates. Undefined elsewhere. */
+export declare function appBundle(binary: string): string | undefined;
+/** The real dependencies. */
+export declare function bridgeBrowserDeps(): BridgeBrowserDeps;
+/**
+ * Make sure nothing else holds the profile: a browser a dead daemon left behind is stopped,
+ * gently first. It is OpenAgent's own profile, so whatever holds it is OpenAgent's own
+ * leftover; nothing the user runs shares it.
+ */
+export declare function freeProfile(profileDir: string, deps: BridgeBrowserDeps): Promise<boolean>;
+/** What a launch needs to know. */
+export interface BridgeBrowserOptions {
+    /** Where the daemon listens — what the extension is told to call. */
+    daemonUrl: string;
+    /** The bridge token the extension presents on every call. */
+    token: string;
+    /** The bridge browser's directory: the profile and the binary live under it. */
+    dir: string;
+    /** The extension's files. Default: `bridgeExtensionSource()`. */
+    extension?: BridgeExtensionSource | undefined;
+    /** Progress, one line at a time, for the dashboard to show while the launch runs. */
+    report?: ((detail: string) => void) | undefined;
+}
+/**
+ * Launch the bridge browser and get it ready: binary, profile, extension, developer mode, token,
+ * Driver tab, minimized. Throws with the step that failed; the browser is closed again on a
+ * failure after the spawn, so a half-set-up browser is never left running.
+ */
+export declare function startBridgeBrowser(opts: BridgeBrowserOptions, deps?: BridgeBrowserDeps): Promise<BridgeBrowser>;
+/** Where the bridge browser stands, for the dashboard. */
+export type BridgeBrowserStatus = {
+    state: 'off';
+} | {
+    state: 'starting';
+    detail: string;
+}
+/** `signIn`: the claude.ai tab is on the sign-in page, so a person has to sign in before anything is served. */
+ | {
+    state: 'running';
+    since: string;
+    visible: boolean;
+    signIn: boolean;
+} | {
+    state: 'stopped';
+    detail: string;
+};
+/** What the dashboard can ask of the bridge browser. */
+export type BridgeBrowserAction = 'show' | 'hide' | 'restart';
+/** The daemon's handle on its bridge browser: one at a time, started and stopped from the preference and the dashboard. */
+export interface BridgeBrowserOwner {
+    /** Where the browser stands; a running one is asked which page its claude.ai tab is on. */
+    status(): Promise<BridgeBrowserStatus>;
+    /** Launch it, unless it is running or on its way. Resolves once the launch is over, either way. */
+    start(): Promise<void>;
+    /** Close it, or cancel a launch under way. */
+    stop(): Promise<void>;
+    act(action: BridgeBrowserAction): Promise<void>;
+}
+/** How the owner launches a browser: the daemon's real launch, or a test's fake. */
+export type BridgeBrowserLauncher = (report: (detail: string) => void) => Promise<BridgeBrowser>;
+/**
+ * The one bridge browser a daemon runs. A launch is slow — the first one downloads Chrome — so
+ * the status carries the step it is on, and a stop that lands mid-launch closes the browser the
+ * launch then hands over rather than leaving it running unowned. A browser that exits on its own
+ * (the user quit it) is reported as stopped with the reason, and not relaunched: quitting it was
+ * an act, and the dashboard offers a restart.
+ */
+export declare function bridgeBrowserOwner(launch: BridgeBrowserLauncher, log?: (line: string) => void): BridgeBrowserOwner;

package/dist/module-types/src/browser-stream.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The DevTools connection to a Chrome the daemon owns: the bridge browser's (#1332). Chrome
+ * refuses DevTools socket connections carrying an `Origin` header unless launched with
+ * `--remote-allow-origins`, and opening that up would let any page the user happens to visit
+ * drive the browser. So the debug port stays unreachable from the web, and this process is the
+ * only one that talks to it.
+ */
+/** What a caller needs from a CDP connection, so a test can stand in for Chrome. */
+export interface CdpSession {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    close(): void;
+}
+/** How a caller reaches a browser or a page. Injectable: the real one speaks WebSocket to Chrome. */
+export type CdpConnect = (webSocketDebuggerUrl: string) => Promise<CdpSession>;
+/**
+ * Talk CDP to Chrome over its debugger socket. Node's global WebSocket is enough, which is
+ * what keeps this dependency-free.
+ */
+export declare const connectCdp: CdpConnect;

package/dist/module-types/src/browser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What launching a Chrome with its DevTools port open needs, whoever launches it: a port nobody
+ * holds, and a way to know the port answers. The bridge browser (#1332) is the one caller.
+ */
+/** A free localhost port, asked of the OS rather than guessed. */
+export declare function freePort(): Promise<number>;
+/**
+ * Poll `/json/version` until Chrome answers. Chrome opens the port a beat after the process
+ * starts, so connecting to a URL that is not listening yet is the obvious race.
+ */
+export declare function waitForDebugEndpoint(browserUrl: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<boolean>;