dsh-browser-application 0.37.0

package/lib/invariant.js

@@ -0,0 +1,26 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@yuxianglin/dsh-bridge-browser`.
+* @module @yuxianglin/dsh-bridge-browser/invariant
+*/
+const PACKAGE_NAME = "@yuxianglin/dsh-bridge-browser";
+/** Cordis companion plugin name. */
+const name = "bridge-browser-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the bridge's connection registry and pending tool map
+* are instance-private (no published event stream to assert against), and the
+* wire contract is pinned by protocol.ts and covered by its unit tests. The
+* tools are plain ctx.tools registrations observed by dsh-tools' own
+* invariant.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/bridge-url.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve the browser-extension bridge WebSocket URL from the current page
+ * location or a discovery response. Shared by the settings row and tests.
+ * @module dsh-browser-application/src/bridge-url
+ */
+/** Minimal Location fields needed to rebuild a loopback-friendly ws URL. */
+export interface BridgeLocationLike {
+    protocol: string;
+    hostname: string;
+    port: string;
+    host: string;
+}
+/**
+ * Build `ws(s)://…/ext/bridge` from the page that hosts the dsh web UI.
+ * Loopback hostnames are normalized to `127.0.0.1` so the address pastes cleanly
+ * into the Chrome extension settings.
+ */
+export declare function bridgeWsUrlFromLocation(location: BridgeLocationLike, bridgePath?: string): string;
+/**
+ * Prefer the discovery endpoint; fall back to reconstructing from `location`.
+ * @param fetchImpl - injectable fetch (defaults to global fetch).
+ * @param location - page location used for fallback and relative discovery URL.
+ */
+export declare function resolveBridgeWsUrl(location: BridgeLocationLike & {
+    origin?: string;
+}, fetchImpl?: typeof fetch, bridgeConfigPath?: string): Promise<string>;
+//# sourceMappingURL=bridge-url.d.ts.map

package/lib/types/browser-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Model-facing browser page context injected after an explicit tab handoff.
+ *
+ * The extension captures the page immediately after the user chooses to
+ * follow it. A live Agent receives that snapshot at once; a deferred session
+ * keeps only its newest snapshot until `agent/created` publishes the
+ * Agent. Live inboxes also keep only the newest unclaimed browser snapshot.
+ * Injection deliberately does not wake an idle Agent — the snapshot is
+ * claimed together with the user's next message.
+ *
+ * @module
+ */
+import type { Agent, AgentRegistry } from '@deepseek-ai/dsh-agent';
+import { type ContextFormed, type UserMessage } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Followed-tab browser page snapshot owned by bridge-browser. */
+        'browser-context': {
+            kind: 'browser-context';
+        } & ContextFormed;
+    }
+}
+/** MessageSource.kind for snapshot supersession and transcript presentation. */
+export declare const BROWSER_CONTEXT_KIND: "browser-context";
+/** Build one immutable context message from a captured browser snapshot. */
+export declare function createBrowserSnapshotMessage(snapshot: string): UserMessage;
+/** Deliver followed-page snapshots to live or not-yet-materialized Agents. */
+export declare class BrowserContextInjector {
+    private readonly agents;
+    private readonly maxPending;
+    private readonly pending;
+    constructor(agents: Pick<AgentRegistry, 'get'>, maxPending?: number);
+    /** Inject now when possible; otherwise retain the newest snapshot per session. */
+    inject(sessionId: string, snapshot: string): 'injected' | 'queued';
+    /** Flush one provisional session at the supported Agent startup boundary. */
+    activate(agent: Agent): boolean;
+}
+//# sourceMappingURL=browser-context.d.ts.map

package/lib/types/dsh-gateway.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Structural subset of the dsh Host services the bridge adapts to: the
+ * TypertGateway wire seam, the Connection fetch handler, and the version-aware
+ * wire-stream opener.
+ *
+ * @module dsh-browser-application/src/dsh-gateway
+ */
+import type { HostRpcFailure } from './host-api.ts';
+/** Structural subset of dsh 0.2's Host TypertGateway service. */
+export interface TypertGatewayLike {
+    readonly wireStream: {
+        /**
+         * dsh 0.2: `(endpoint, payload, uplink, peer, signal)`.
+         * Legacy stubs/tests: `(endpoint, payload, signal)`.
+         */
+        open(endpoint: string, payload: unknown, uplinkOrSignal: AsyncIterable<unknown> | AbortSignal, peer?: unknown, signal?: AbortSignal): Promise<AsyncIterable<unknown>>;
+        failure(error: unknown): HostRpcFailure;
+    };
+    invoke(request: {
+        readonly namespace: string;
+        readonly method: string;
+        readonly args: Readonly<Record<string, unknown>>;
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/**
+ * Open a Host wire stream against either dsh 0.2 or the legacy three-arg form.
+ *
+ * - arity 3: composition/unit stubs still use `(endpoint, payload, signal)`.
+ * - arity 5: real dsh 0.2 TypertGatewayWireStream.
+ * - arity 0: Cordis/service wrappers — must use the five-arg call. Treating
+ *   these as three-arg maps AbortSignal onto uplink and leaves signal
+ *   undefined (hello.ok → stream-failed → WS 1011).
+ */
+export declare function openWireStream(gateway: TypertGatewayLike, endpoint: string, payload: unknown, signal: AbortSignal): Promise<AsyncIterable<unknown>>;
+/** Structural subset of dsh 0.2's Host Connection service. */
+export interface HostConnectionLike {
+    createSharedFetchHandler(channel: '/api'): {
+        fetch(request: Request): Promise<Response>;
+    };
+}
+//# sourceMappingURL=dsh-gateway.d.ts.map

package/lib/types/event-generation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One authenticated extension connection's event streams, its active Session
+ * follower, and the forwarded Host waterfalls it answers.
+ *
+ * @module dsh-browser-application/src/event-generation
+ */
+import type { RespondResult } from '@dsh-browser/protocol';
+import { type TypertGatewayLike } from './dsh-gateway.ts';
+import { type SessionSnapshot } from './session-history.ts';
+import type { HostEventFrame } from './host-api.ts';
+import { ExtensionSessionRegistry } from './extension-sessions.ts';
+export type SendRemoteEventResult = (clientId: string, eventId: string, outcome: RemoteEventOutcome, signal: AbortSignal) => Promise<void>;
+export type RemoteEventOutcome = {
+    readonly kind: 'next';
+} | {
+    readonly kind: 'result';
+    readonly value?: unknown;
+} | {
+    readonly kind: 'rejected';
+    readonly error: {
+        readonly name: string;
+        readonly message: string;
+        readonly code?: string;
+        readonly details?: unknown;
+    };
+};
+/** One authenticated extension connection's event streams and active Session follower. */
+export declare class EventGeneration {
+    private readonly gateway;
+    private readonly sendResult;
+    private readonly extensionSessions;
+    private readonly onHistoryCursor;
+    private readonly lifetime;
+    private readonly signal;
+    private readonly queue;
+    private readonly tasks;
+    private readonly pendingQuestions;
+    private clientId;
+    private followAbort;
+    private followedSessionId;
+    private followRevision;
+    private disposed;
+    constructor(gateway: TypertGatewayLike, sendResult: SendRemoteEventResult, extensionSessions: ExtensionSessionRegistry, onHistoryCursor: (sessionId: string, cursor: number) => void, outerSignal: AbortSignal);
+    start(): void;
+    events(): AsyncIterable<HostEventFrame>;
+    openSessionHistory(sessionId: string, callSignal: AbortSignal, maxMessages?: number): Promise<SessionSnapshot>;
+    ensureSessionFollow(sessionId: string, callSignal: AbortSignal): Promise<void>;
+    respond(rpcId: string, result: RespondResult, signal: AbortSignal): Promise<unknown>;
+    dispose(): Promise<void>;
+    private openSessionFollow;
+    private pumpSessionEvents;
+    private pumpRemoteEvents;
+    private handleRemoteEvent;
+    private track;
+}
+//# sourceMappingURL=event-generation.d.ts.map

package/lib/types/extension-sessions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Track session ids that the browser extension has driven through the bridge.
+ * Desktop-native sessions must keep the host userQuestions waterfall so the
+ * Desktop UI can render ask_user_question cards.
+ * @module dsh-browser-application/src/extension-sessions
+ */
+/** Mutable registry of extension-owned session ids. */
+export declare class ExtensionSessionRegistry {
+    private readonly ids;
+    /** Remember a session the extension successfully created or prompted. */
+    note(sessionId: string | undefined): void;
+    /** Whether the extension has touched this session over the bridge. */
+    has(sessionId: string | undefined): boolean;
+    /** Test helper: drop all tracked ids. */
+    clear(): void;
+}
+/**
+ * Decide whether the bridge should own ask_user_question for this request.
+ * Desktop sessions must fall through to the native answerer waterfall.
+ */
+export declare function shouldBridgeOwnQuestion(input: {
+    hasExtensionConnection: boolean;
+    sessionId: string | undefined;
+    extensionSessions: Pick<ExtensionSessionRegistry, 'has'>;
+}): boolean;
+//# sourceMappingURL=extension-sessions.d.ts.map

package/lib/types/host-api.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bridge-owned Host API consumed by the WebSocket carrier.
+ *
+ * This boundary keeps release-specific Host topology out of the browser wire
+ * server. dsh 0.1.5 implements it with Typert Remotes and Connection.
+ *
+ * @module
+ */
+import type { RespondResult } from '@dsh-browser/protocol';
+/** Stable failure envelope understood by the extension panel. */
+export interface HostRpcFailure {
+    readonly code: string;
+    readonly message: string;
+    readonly details: object;
+}
+/** Business result returned by the active dsh Host adapter. */
+export type HostRpcResult<T = unknown> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: HostRpcFailure;
+};
+/** One extension-originated unary call after WebSocket decoding. */
+export interface HostRpcCall {
+    readonly rpcId: string;
+    readonly method: string;
+    readonly payload: unknown;
+    readonly signal: AbortSignal;
+}
+/** Event retained as the private bridge-to-extension protocol. */
+export interface HostEventFrame {
+    readonly rpcId: string;
+    readonly method: string;
+    readonly payload: unknown;
+}
+/** API surface the WebSocket carrier needs from a dsh Host. */
+export interface BrowserHostApi {
+    call(call: HostRpcCall): Promise<HostRpcResult>;
+    events(signal: AbortSignal): AsyncIterable<HostEventFrame>;
+    respond(rpcId: string, result: RespondResult, signal: AbortSignal): Promise<unknown>;
+}
+/** Convert an arbitrary Host rejection to the open wire failure vocabulary. */
+export declare function hostFailure(error: unknown): HostRpcFailure;
+/** Narrow unknown JSON-like data without accepting arrays. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=host-api.d.ts.map

package/lib/types/image-relay.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Serving the extension's image-recognition requests on the desktop side.
+ *
+ * The extension is asked for bytes first because only it carries the user's login
+ * state; when it could not fetch at all — its content-security policy, a host
+ * permission, or an enterprise rule — it sends the URL and the desktop tries with
+ * its own network stack instead. The two paths are complementary rather than
+ * redundant, which is why the frame carries a source rather than always one kind.
+ *
+ * The desktop has no image codec, so bytes it fetches itself are passed through
+ * unchanged once they are known to be an image and to be a sane size. Anything
+ * the extension already normalized arrives pre-scaled.
+ *
+ * @module
+ */
+import type { ImageRecognitionRequest, ImageSource } from '@dsh-browser/protocol';
+import type { VisionClient } from './vision.ts';
+export type ImageRelayResult = {
+    ok: true;
+    desc: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare class ImageRelay {
+    private readonly vision;
+    private readonly fetchImpl;
+    constructor(vision: VisionClient | undefined, fetchImpl?: typeof fetch);
+    /** Whether a vision model is configured, which is what `hello.ok` advertises. */
+    get available(): boolean;
+    /**
+     * Recognize one image for the extension.
+     *
+     * @param request - the page context the extension gathered.
+     * @param source - normalized bytes, or a URL for the desktop to fetch.
+     * @returns a one-line description, or a classified failure.
+     */
+    recognize(request: ImageRecognitionRequest, source: ImageSource): Promise<ImageRelayResult>;
+    /** The desktop's own attempt, for when the extension's fetch did not work. */
+    private fetchByUrl;
+}
+//# sourceMappingURL=image-relay.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `dsh-browser-application`: token-authenticated WebSocket bridge for
+ * the browser extension plus the text-only `browser_*` tool set.
+ *
+ * The bridge mounts its own upgrade route (`/ext/bridge`) on the host
+ * webserver, OUTSIDE the /api trust fence — so it brings its own bearer-token
+ * authentication (first frame `hello` within HELLO_TIMEOUT_MS). Extension
+ * calls, Session streams, and Host waterfalls use dsh's Typert Gateway
+ * and Connection services.
+ * Tools execute by dispatching
+ * `tool.call` frames to the connected extension, which performs the action in
+ * the tab explicitly controlled by the user.
+ *
+ * Opt-in by design: nothing is registered unless this plugin appears in the
+ * composition. No dsh core code is touched.
+ *
+ * @module dsh-browser-application
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { VisionClient } from './vision.ts';
+/**
+ * The plugin's display title, shown wherever the desktop lists it.
+ *
+ * It reads as a settings page because that is what the entry is: the desktop's
+ * Plugins page renders this plugin's Config as an editable form, and this is the
+ * heading on it.
+ */
+export declare const name = "dsh \u6D4F\u89C8\u5668\u8BBE\u7F6E";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Plugin config: deployment-varying tunables only; the wire contract stays fixed. */
+export interface Config {
+    /** Fixed bearer token. When absent, a token is generated on first boot and persisted under the dsh home (0600). */
+    token?: string;
+    /** Per-tool-call timeout in ms. Defaults to 90000. */
+    toolTimeoutMs?: number;
+    /** Upper bound on one snapshot's rendered characters. Defaults to 32000; minimum 500. */
+    snapshotMaxChars?: number;
+    /** Upper bound on interactive inventory items per snapshot. Defaults to 60. */
+    maxInteractiveItems?: number;
+    /** Dedicated workspace path for extension-created sessions. Empty disables grouping. */
+    sessionWorkspacePath?: string;
+    /**
+     * Display name for that workspace. Defaults to {@link DEFAULT_SESSION_WORKSPACE_TITLE}.
+     *
+     * Without it the group is named after its directory, so it reads as
+     * "browser-sessions" — which looks like an internal detail rather than the
+     * user's own browser conversations, and nothing in the interface renames it. An
+     * empty string accepts whatever name the desktop derives.
+     */
+    sessionWorkspaceTitle?: string;
+    /** Defer real session creation until the first prompt. Defaults to true. */
+    deferSessionCreate?: boolean;
+    /**
+     * Allow the model to open pages in the user's browser on its own initiative.
+     *
+     * This is the authoritative switch, and it gates three things together so it
+     * cannot be a half-measure: the prompt guidance that tells the model to open
+     * pages, the extension's `@open` command, and the extension's automatic panel
+     * opening. Turning it off means the model may still read and operate a page
+     * the user already has open; it just stops driving the browser to new places
+     * unprompted. Defaults to true.
+     */
+    openPagesForUser?: boolean;
+    /**
+     * API key for desktop-side image recognition. Empty disables it, and the
+     * extension then keeps its own network path instead of relaying.
+     *
+     * Relaying exists so this key never enters a browser profile, and so image
+     * fetches that the extension's content-security policy or an enterprise rule
+     * blocks can still succeed through the desktop's own network stack.
+     */
+    visionApiKey?: string;
+    /** Chat-completions base URL. Defaults to the DeepSeek endpoint. */
+    visionBaseUrl?: string;
+    /**
+     * Model id that reads the images.
+     *
+     * Configurable because {@link visionBaseUrl} is: pointing this plugin at another
+     * provider while the model id stays fixed would send a name that provider has
+     * never heard of. Defaults to {@link VISION_MODEL}, which is the only DeepSeek id
+     * that reports an image input modality — and note that it is the *id*, not the
+     * display name `DeepSeek-V4.1-Flash`, which the API rejects with 400.
+     */
+    visionModel?: string;
+    /**
+     * `off` disables thinking blocks. On a pure perception task they cost more than
+     * the image does, and the model cannot verify that the setting took effect, so
+     * the desktop reads `usage` back to confirm no reasoning tokens were billed.
+     */
+    visionThinking?: string;
+    /** Per-image timeout in ms. Defaults to 20000. */
+    visionTimeoutMs?: number;
+}
+export declare const Config: z<Config>;
+/** The shape after schemastery applies its defaults to every field. */
+type ResolvedConfig = Required<Omit<Config, 'token'>> & Pick<Config, 'token'>;
+/** Configured budgets must be positive integers. Exported for validation tests. */
+export declare function assertPositiveInteger(name: string, value: number): void;
+/**
+ * Apply defaults and direct-call validation at the plugin boundary.
+ * @param config - Loader-resolved or directly supplied plugin configuration.
+ * @returns a complete configuration ready for runtime use.
+ */
+export declare function resolveConfig(config: Config): ResolvedConfig;
+/**
+ * Build the desktop's vision client, or nothing when no key is configured.
+ *
+ * Absence is meaningful rather than an error: `hello.ok` then reports
+ * `imageRecognition: false`, and the extension keeps its own network path instead
+ * of sending frames nobody would answer.
+ *
+ * @param config - the resolved plugin configuration.
+ * @returns a client, or `undefined` when vision is not configured.
+ */
+export declare function buildVisionClient(config: ResolvedConfig): VisionClient | undefined;
+/** The host's credential service, narrowed to the one call this file makes. */
+export interface CredentialSource {
+    resolve(ref: string): Promise<{
+        value: string;
+        source: string;
+    } | undefined>;
+}
+/** The host, narrowed to the one call this file makes on it. */
+export interface VisionHost {
+    get(name: string): unknown;
+}
+/**
+ * Which vision client to use: an explicitly configured key first, the credential the
+ * desktop already holds for this provider second.
+ *
+ * The fallback is deliberately the *credential* service and not the *account* one.
+ * `deepseekAccount.resolveToken()` was tried first and is wrong: it answers with the
+ * desktop's platform token, which the public chat-completions API rejects with 401,
+ * turning a clear "not configured" into an authentication failure about a key nobody
+ * ever wrote. `credentials.resolve('DEEPSEEK_API_KEY')` is the key the desktop itself
+ * calls this provider with.
+ *
+ * Holding the key does not send anything: the bridge relays only when the extension
+ * asks, and the extension asks only for a tier the user turned on. The opt-in that
+ * matters is the tier, not the presence of a key.
+ *
+ * @param host - the Cordis context, narrowed to `get`.
+ * @param config - plugin config (schema defaults applied).
+ * @returns the client, or undefined when neither source supplies a key.
+ */
+export declare function resolveVisionClient(host: VisionHost, config: ResolvedConfig): Promise<VisionClient | undefined>;
+/**
+ * Mount the bridge: resolve the token, register the upgrade route, the tool
+ * set, and an optional system-prompt section, all effect-scoped for HMR.
+ *
+ * @param ctx - Cordis context.
+ * @param config - plugin config (schema defaults applied).
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-browser-application`.
+ * @module dsh-browser-application/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "bridge-browser-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/remote-host-api.d.ts

@@ -0,0 +1,12 @@
+/**
+ * dsh 0.2 Host adapter: unary calls through TypertGateway, plus the Session
+ * and forwarded-event plumbing assembled from the gateway, history, and
+ * event-generation modules.
+ *
+ * @module dsh-browser-application/src/remote-host-api
+ */
+import type { BrowserHostApi } from './host-api.ts';
+import { type TypertGatewayLike, type HostConnectionLike } from './dsh-gateway.ts';
+/** Build the dsh 0.2 Host implementation. */
+export declare function createRemoteHostApi(gateway: TypertGatewayLike, connection: HostConnectionLike): BrowserHostApi;
+//# sourceMappingURL=remote-host-api.d.ts.map

package/lib/types/server.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Bridge WebSocket carrier: token-authenticated connection registry, gateway
+ * RPC dispatch, per-connection event pump, and tool-call dispatch to the
+ * connected browser extension.
+ *
+ * The route this server mounts (`/ext/bridge`) lives OUTSIDE the /api trust
+ * fence (which only guards the client-connection routes), so the bridge brings
+ * its own authentication: a bearer token presented in the `hello` frame within
+ * HELLO_TIMEOUT_MS. Host calls terminate at the bridge-owned Host adapter.
+ * Methods the /api carrier pins to loopback (`PRIVILEGED_METHODS`)
+ * stay loopback-only here regardless of the token, defense in depth for
+ * `--host 0.0.0.0` deployments.
+ *
+ * One active connection at a time: a new authenticated socket replaces the
+ * previous one (the old socket is closed and its in-flight tool calls settle
+ * as `bridge-closed`).
+ *
+ * @module
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { BrowserHostApi } from './host-api.ts';
+import { type BridgeCaps, type BridgePolicy, type ToolErrorCode } from '@dsh-browser/protocol';
+import type { ImageRelay } from './image-relay.ts';
+/** Loopback IPv4/IPv6 literals (IPv4-mapped included). Exported for tests and reuse. */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/** Error thrown by requestTool; the tool registry turns it into an isError result. */
+export declare class BridgeToolError extends Error {
+    readonly code: ToolErrorCode;
+    constructor(code: ToolErrorCode, message: string);
+}
+/** Dependencies the bridge needs from the host. */
+export interface BridgeServerDeps {
+    /** Bearer token the extension must present in `hello`. */
+    token: string;
+    /** Active dsh Host adapter used for unary calls, events, and waterfalls. */
+    api: BrowserHostApi;
+    /** Default per-tool-call timeout in ms. */
+    toolTimeoutMs: number;
+    /** Capabilities to echo in `hello.ok` (negotiated snapshot budgets). */
+    caps: BridgeCaps;
+    /** What the desktop app allows, sent alongside the caps in `hello.ok`. */
+    policy: BridgePolicy;
+    /**
+     * Image recognition on the extension's behalf. Absent when no vision model is
+     * configured, which the extension learns from `hello.ok`'s policy.
+     */
+    imageRelay?: ImageRelay;
+    /**
+     * Why no relay is available, in words the user can act on.
+     *
+     * Sent in `hello.ok` so the extension can put it in front of whoever asked for an
+     * image, instead of reporting only that recognition is unavailable — which leaves
+     * the reader with a dead end and no next step.
+     */
+    visionUnavailableReason?: string;
+    /** Seed a followed-page snapshot into a live or deferred Agent session. */
+    injectBrowserSnapshot: (sessionId: string, snapshot: string) => void | Promise<void>;
+    /**
+     * Permanently delete one session's durable storage. Callers archive the
+     * session through the gateway first; this only removes files.
+     */
+    purgeSession: (sessionId: string) => Promise<void>;
+    /**
+     * Test seam: force the remote address seen by the privilege gate. The
+     * sandbox cannot bind arbitrary loopback literals, so the non-loopback
+     * branch is exercised through this override; production never sets it.
+     */
+    remoteAddressOverride?: string;
+    /** Seconds a fresh socket may present `hello`; defaults to HELLO_TIMEOUT_MS. */
+    helloTimeoutMs?: number;
+    /** Server ping cadence; defaults to PING_INTERVAL_MS. */
+    pingIntervalMs?: number;
+}
+/**
+ * Decode one ws message payload to text. Exported so all three delivery
+ * shapes (fragmented buffer list, Buffer, ArrayBuffer) are unit-testable
+ * directly — node ws only ever delivers Buffers in practice.
+ * @param data - ws message payload.
+ * @returns the decoded UTF-8 text.
+ */
+export declare function messageToText(data: Buffer | ArrayBuffer | Buffer[]): string;
+/**
+ * Token-authenticated bridge server. Construct once per plugin instance;
+ * dispose with {@link close}.
+ */
+export declare class BridgeServer {
+    private readonly deps;
+    private readonly wss;
+    private current;
+    private readonly pendingTools;
+    private readonly orderedSessionRpcs;
+    private closed;
+    constructor(deps: BridgeServerDeps);
+    /**
+     * Handle one HTTP upgrade for the bridge path.
+     * @param req - upgrade request (carries the client's remote address).
+     * @param socket - raw socket transferred by the HTTP server.
+     * @param head - bytes already read after the upgrade headers.
+     */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    /**
+     * Request one browser action from the connected extension.
+     * @param name - tool name (also the wire action name).
+     * @param args - validated tool arguments.
+     * @param signal - caller cancellation (abort settles the call as cancelled).
+     * @param timeoutMs - per-call budget; defaults to the plugin config value.
+     * @param sessionId - optional owning Agent session for approval continuity.
+     * @returns the extension's action result.
+     * @throws BridgeToolError when no extension is connected, the call times
+     *   out, is cancelled, or the extension reports a failure.
+     */
+    requestTool(name: string, args: Record<string, unknown>, signal: AbortSignal, timeoutMs?: number, sessionId?: string): Promise<unknown>;
+    /**
+     * Terminate the server: close the acceptor, drop all sockets, reject all
+     * in-flight tool calls.
+     * @returns a promise resolving after the acceptor and all pumps stop.
+     */
+    close(): Promise<void>;
+    /** @returns whether an authenticated extension is currently connected. */
+    hasConnection(): boolean;
+    private attach;
+    /** Promote an authenticated socket to the single active slot. */
+    private promote;
+    private handleReadyFrame;
+    /** Recognition requests in flight; the extension bounds its side as well. */
+    private imageCallsInFlight;
+    private readonly maxImageCalls;
+    /**
+     * Serve one image-recognition request from the extension.
+     *
+     * A failure is answered with a frame rather than a throw, because the extension
+     * records it in the manifest: the model must be told "there is an image here
+     * and it could not be read", not shown nothing at all.
+     */
+    private handleImageCall;
+    /**
+     * Preserve prompt/cancel arrival order per session. In particular, the
+     * first prompt may still be materializing a provisional session; its cancel
+     * must not reach the gateway until that admission has completed.
+     */
+    private routeRpc;
+    private handleRpc;
+    /** Relay a pending Host waterfall response through the active adapter. */
+    private handleRespond;
+    private settleTool;
+    /** Close the current connection (if any) and settle its in-flight calls. */
+    private replaceConnection;
+}
+/**
+ * Tool error payload → stable code. The wire parser enforces string fields,
+ * so the fallback branches are parser-gated; exported so the fallback
+ * contract is unit-testable directly.
+ * @param payload - extension-reported error payload.
+ * @returns the stable error code.
+ */
+export declare function payloadCode(payload: unknown): ToolErrorCode;
+/**
+ * Tool error payload → message. The wire parser enforces string fields, so
+ * the fallback branches are parser-gated; exported so the fallback contract
+ * is unit-testable directly.
+ * @param payload - extension-reported error payload.
+ * @returns the human-readable message.
+ */
+export declare function payloadMessage(payload: unknown): string;
+//# sourceMappingURL=server.d.ts.map