dsh-browser-application 0.37.0

package/lib/types/session-deferral.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Defer real session creation until the first prompt.
+ *
+ * The panel calls `session.create` as soon as it connects, but a session that
+ * is opened and never used should leave zero trace in the store/GUI. This
+ * wrapper answers `session.create` with a provisional id (minted locally,
+ * nothing persisted), serves `session.history` for provisional ids as empty,
+ * and materializes the real session — same id, original create payload — on
+ * the first `session.prompt` for that id. Abandoned provisional ids are
+ * pruned after {@link PROVISIONAL_TTL_MS}.
+ *
+ * Provisional sessions also answer `session.models` from the host-wide
+ * `session.modelCatalog` (via the Host API adapter, plus a pending switch)
+ * and remember `session.selectModel` until materialization, so the composer can
+ * show a model switcher before the first message.
+ *
+ * @module dsh-browser-application/src/session-deferral
+ */
+import type { ImageAttachmentLimits } from '@deepseek-ai/dsh-attachment';
+import type { BrowserHostApi } from './host-api.ts';
+/**
+ * Wrap the gateway sessions API so `session.create` returns a provisional id
+ * without creating anything; the real session materializes on the first
+ * `session.prompt` for that id.
+ *
+ * @param api - Gateway API implementation.
+ * @param enabled - Whether deferral is active; false returns the API untouched.
+ * @param imageLimits - actual host image capability, used for the synthetic
+ * empty history before the deferred Session exists.
+ * @returns the original API when disabled, otherwise the wrapped API.
+ */
+export declare function withSessionDeferral(api: BrowserHostApi, enabled: boolean, imageLimits?: ImageAttachmentLimits): BrowserHostApi;
+//# sourceMappingURL=session-deferral.d.ts.map

package/lib/types/session-history.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Session history decoding: the `session/follow` baseline, its records, and the
+ * compact chunk-row expansion older logs still use.
+ *
+ * @module dsh-browser-application/src/session-history
+ */
+import { type TypertGatewayLike } from './dsh-gateway.ts';
+export interface SessionSnapshot {
+    /** Inclusive Host log tip from session/follow; required for later session/page calls. */
+    readonly cursor: number;
+    readonly records: readonly unknown[];
+    readonly hasMore: boolean;
+    readonly projections?: unknown;
+    readonly assistantStream?: unknown;
+    readonly snapshotId?: string;
+}
+export declare function oneShotSessionSnapshot(gateway: TypertGatewayLike, sessionId: string, outerSignal: AbortSignal, maxMessages?: number): Promise<SessionSnapshot>;
+export declare function historyValue(snapshot: SessionSnapshot): Record<string, unknown>;
+export declare function historyPageValue(page: unknown): Record<string, unknown>;
+export declare function optionalNonNegativeInteger(payload: unknown, key: string): number | undefined;
+export declare function optionalPositiveInteger(payload: unknown, key: string): number | undefined;
+export declare function isSessionSnapshot(value: unknown): value is {
+    readonly type: 'snapshot';
+    readonly cursor: number;
+    readonly records: readonly unknown[];
+    readonly hasMore: boolean;
+    readonly projections?: unknown;
+    readonly assistantStream?: unknown;
+};
+//# sourceMappingURL=session-history.d.ts.map

package/lib/types/session-purge.d.ts

@@ -0,0 +1,55 @@
+/**
+ * File-level removal of one session's durable storage under the dsh home.
+ *
+ * The gateway exposes no session.delete, so the bridge performs the removal
+ * itself: this module archives the session under exclusive write ownership,
+ * then removes its durable data while retaining the kernel lock's pathname.
+ * Session ids are validated against the persisted shape, only data within
+ * exact-name directories two levels below the sessions root is removed, and
+ * running sessions are refused before anything touches the disk.
+ *
+ * @module dsh-browser-application/src/session-purge
+ */
+/** Stable failure codes surfaced to the panel. Open set: callers must tolerate growth. */
+export type SessionPurgeErrorCode = 'not-found' | 'running' | 'invalid-id' | 'internal';
+/** Error thrown by {@link purgeSessionFiles}; the server turns it into a wire error. */
+export declare class SessionPurgeError extends Error {
+    readonly code: SessionPurgeErrorCode;
+    constructor(code: SessionPurgeErrorCode, message: string, options?: ErrorOptions);
+}
+/** Dependencies purging needs from the plugin. */
+export interface SessionPurgeDeps {
+    /** The dsh sessions root (`dshHomePath('sessions')`). */
+    sessionsRoot: string;
+    /** Session ids currently running; purging any of these is refused. */
+    runningSessionIds: ReadonlySet<string>;
+    /**
+     * Claim the runtime's exclusive write ownership (including its kernel lock).
+     * The returned handle must remain held until removal finishes. Opening a
+     * read handle, checking for a lock file, or checking only Agent status does
+     * not provide exclusion: idle Agents and other processes can own the log.
+     */
+    acquireOwnership(sessionId: string): Promise<{
+        close(): Promise<void>;
+    }>;
+    /** Archive while the durable session still exists and exclusive ownership is held. */
+    archiveSession(sessionId: string): Promise<void>;
+}
+/**
+ * Validate one session id against the persisted shape. Rejects everything
+ * that could escape the sessions root (separators, dot segments) before any
+ * filesystem call sees it.
+ * @param sessionId - untrusted id from the panel.
+ * @returns the id when well-formed.
+ * @throws SessionPurgeError with code `invalid-id` otherwise.
+ */
+export declare function assertPurgeableSessionId(sessionId: string): string;
+/**
+ * Permanently delete a session's data, keeping its directory and lock inode.
+ * The runtime refuses ambiguous duplicate session identities across workspaces.
+ * @param deps - root and running-set inputs.
+ * @param sessionId - validated session id.
+ * @returns nothing; throws {@link SessionPurgeError} on refusal or failure.
+ */
+export declare function purgeSessionFiles(deps: SessionPurgeDeps, sessionId: string): Promise<void>;
+//# sourceMappingURL=session-purge.d.ts.map

package/lib/types/session-workspace.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Best-effort workspace grouping for sessions created through the browser
+ * bridge.
+ *
+ * The wrapper touches exactly one request: an implicit `session.create`, which
+ * it gives the browser group's workspace id. Explicit workspace choices and
+ * every other gateway method pass through untouched — including the
+ * `workspace.create` and `workspace.rename` calls this module makes on its own
+ * behalf, which are issued through the same API and must not be intercepted.
+ *
+ * Grouping is best-effort by design. A failure returns the original call
+ * ungrouped rather than failing the prompt, because a conversation the user can
+ * still have is worth more than a tidy list.
+ *
+ * @module dsh-browser-application/src/session-workspace
+ */
+import type { BrowserHostApi } from './host-api.ts';
+type Warn = (message: string) => void;
+/**
+ * Add a dedicated Workspace to implicit session creation without making
+ * grouping a session-creation dependency. The first implicit create mkdirs
+ * and registers the configured path; that result, including failure, is
+ * cached for the wrapper lifetime.
+ *
+ * @param api - Injected gateway API implementation.
+ * @param workspacePath - Dedicated directory, or an empty string to opt out.
+ * @param workspaceTitle - Display name for the group, or an empty string to keep
+ *   the name the desktop derives from the directory. A title is needed because
+ *   that derived name is the directory's, so a fresh install shows
+ *   "browser-sessions" — an internal-sounding label the user has no reason to
+ *   open, and no way to rename from the interface.
+ * @param warn - Logger called once when grouping cannot be established.
+ * @returns the original API for opt-out, otherwise an API with wrapped session creation.
+ */
+export declare function withSessionWorkspace(api: BrowserHostApi, workspacePath: string, workspaceTitle: string, warn: Warn): BrowserHostApi;
+export {};
+//# sourceMappingURL=session-workspace.d.ts.map

package/lib/types/token.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bridge bearer-token lifecycle: generation, constant-time verification, and
+ * file persistence under the dsh home directory.
+ *
+ * The token authenticates the browser extension against the bridge WebSocket.
+ * It is NOT the /api trust fence (that stays untouched); it is the bridge
+ * path's own auth because the bridge route lives outside the fence by design.
+ *
+ * @module
+ */
+/** File name of the persisted token inside the dsh home. */
+export declare const TOKEN_FILE_NAME = "ext-bridge-token";
+/**
+ * Generate a fresh token as lowercase hex.
+ * @param bytes - entropy bytes; defaults to DEFAULT_TOKEN_BYTES (256-bit).
+ * @returns the hex token string.
+ */
+export declare function generateToken(bytes?: number): string;
+/**
+ * Constant-time token comparison. Length mismatch fails fast (still constant
+ * time on the compared prefix) — a wrong-length token can never verify.
+ * @param expected - the configured token.
+ * @param actual - the token presented by the client.
+ * @returns true only when both are equal-length hex and byte-equal.
+ */
+export declare function verifyToken(expected: string, actual: string): boolean;
+/**
+ * Path of the persisted token file under the dsh home.
+ * @returns absolute path like `~/.dsh/ext-bridge-token`.
+ */
+export declare function tokenFilePath(): string;
+/**
+ * Read the persisted token; returns undefined when absent or unreadable.
+ * @param file - token file path.
+ * @returns the stored hex token, trimmed.
+ */
+export declare function readTokenFile(file?: string): Promise<string | undefined>;
+/**
+ * Persist a token atomically (temp file + rename) with 0600 permissions.
+ * @param token - hex token to persist.
+ * @param file - token file path.
+ */
+export declare function writeTokenFile(token: string, file?: string): Promise<void>;
+/**
+ * Resolve the bridge token: an explicitly configured token wins; otherwise the
+ * persisted file is reused when present, and a fresh token is generated and
+ * persisted otherwise.
+ * @param configured - token from plugin config, or undefined.
+ * @param file - token file path (injectable for tests).
+ * @returns `{ token, file, generated }` where `generated` records whether a new token was minted.
+ */
+export declare function resolveToken(configured: string | undefined, file?: string): Promise<{
+    token: string;
+    file: string;
+    generated: boolean;
+}>;
+//# sourceMappingURL=token.d.ts.map

package/lib/types/tools.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Model-facing browser tools. Every tool executes by dispatching a `tool.call`
+ * over the bridge to the connected extension, which performs the action in the
+ * user's explicitly controlled tab and returns a pure-text result.
+ *
+ * The surface is structured text by design: `browser_snapshot` renders the page
+ * with a numbered interactive inventory, and every other tool addresses elements
+ * by that inventory's stable index. Results are single `{ text }` objects.
+ *
+ * The tools differ only in name, description, parameter schema, and which
+ * arguments are forwarded, so they live in one table instead of fifteen
+ * near-identical blocks — which also makes "frame routing only on frame-local
+ * tools" a single visible column instead of a fact repeated fifteen times.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { BridgeServer } from './server.ts';
+/** Options resolved from plugin config before tool registration. */
+export interface BrowserToolsOptions {
+    /** Per-tool-call budget in ms (also the bridge's default). */
+    toolTimeoutMs: number;
+    /** Upper bound on one snapshot's rendered characters. */
+    snapshotMaxChars: number;
+    /** Upper bound on interactive inventory items per snapshot. */
+    maxInteractiveItems: number;
+}
+/** The keys the extension accepts as wire action names (tool name == action name). */
+export declare const BROWSER_TOOL_NAMES: readonly ["browser_snapshot", "browser_click", "browser_type", "browser_press", "browser_scroll", "browser_navigate", "browser_open_tab", "browser_list_tabs", "browser_follow_tab", "browser_close_tab", "browser_back", "browser_forward", "browser_reload", "browser_get_text", "browser_wait", "browser_describe_image"];
+/**
+ * Register the browser tools on `ctx.tools`. Disposers are returned for the
+ * caller's effect to own; each tool's cooperative timeout budget is declared so
+ * the timeout policy can enforce it, and every execute forwards `exec.signal`
+ * into the bridge call (abort settles it).
+ *
+ * @param ctx - Cordis context with the tools service.
+ * @param bridge - the authenticated bridge server.
+ * @param options - resolved tool budgets.
+ * @returns disposers keyed by tool name.
+ */
+export declare function registerBrowserTools(ctx: Context, bridge: BridgeServer, options: BrowserToolsOptions): Map<string, () => void>;
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/vision-selfcheck.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The startup check that the cost switch actually took effect.
+ *
+ * A provider that ignores `thinking: {type: 'disabled'}` answers normally, so
+ * nothing looks wrong while every image costs several times the image itself —
+ * thinking tokens are the large part of the bill on a pure perception task. The
+ * request body cannot prove it was honoured; `usage` can.
+ *
+ * This runs once, in the background, and only ever warns. A deployment whose
+ * provider reports nothing stays quiet rather than crying wolf: zero means "none
+ * billed as far as this response says", not proof.
+ *
+ * @module
+ */
+import type { VisionClient } from './vision.ts';
+/** Run the probe and report a switch that was silently ignored. */
+export declare function checkThinkingIsOff(vision: VisionClient, warn: (message: string) => void): void;
+//# sourceMappingURL=vision-selfcheck.d.ts.map

package/lib/types/vision.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The multimodal call the desktop makes on the extension's behalf.
+ *
+ * Only the desktop can hold the model credential without putting it in a browser
+ * profile, and only the desktop can reach the network through the machine's own
+ * proxy, VPN, or client certificate. This module is the transport: the prompt,
+ * the request body, and the response parser are shared with the extension's own
+ * outbound path, so "which side calls the model" changes nothing about what is
+ * asked or what counts as an answer.
+ *
+ * @module
+ */
+import { type VisionCallConfig, type VisionCallContext, type VisionCallImage, type VisionCallResult } from '@dsh-browser/protocol';
+export type { VisionCallContext, VisionCallResult };
+/** A 1×1 transparent PNG: the smallest thing a vision endpoint will accept. */
+export declare const PROBE_IMAGE_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+/** What a probe learned about the deployment's cost controls. */
+export interface VisionProbe {
+    ok: boolean;
+    /** Reasoning tokens the response reported; 0 when none or unreported. */
+    reasoningTokens: number;
+    message: string;
+}
+export interface VisionConfig extends VisionCallConfig {
+    /** Chat-completions base URL. */
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+}
+export interface VisionRequest extends VisionCallImage {
+    context: VisionCallContext;
+}
+export type VisionResult = VisionCallResult;
+export declare class VisionClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: VisionConfig, fetchImpl?: typeof fetch);
+    /**
+     * Describe one image.
+     *
+     * @param request - normalized bytes plus the page context around them.
+     * @returns one line of description, or a classified failure.
+     */
+    describe(request: VisionRequest): Promise<VisionResult>;
+    /**
+     * Send one minimal request and read the billing back.
+     *
+     * A thinking switch can be ignored silently — the request succeeds and the
+     * answer looks fine, while every image costs several times what it should. The
+     * only way to know is to look at `usage`, so this sends the smallest possible
+     * image once and reports what came back.
+     *
+     * @returns what the provider reported, or why the probe could not run.
+     */
+    probe(): Promise<VisionProbe>;
+}
+//# sourceMappingURL=vision.d.ts.map

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "dsh-browser-application",
+  "version": "0.37.0",
+  "description": "dsh 浏览器设置：把扩展连到 dsh 桌面端，提供 browser_* 工具，并在需要时替你识别页面上的图片。这是它的全部配置项。",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-gateway": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-gateway": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
+    "@dsh-browser/protocol": "workspace:*",
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
+    "playwright-core": "^1.50.0",
+    "tsdown": "0.22.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b --pretty false && tsdown",
+    "typecheck": "tsc -b --pretty false",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/youbaiyun/dsh-browser-application.git",
+    "directory": "packages/bridge"
+  },
+  "homepage": "https://github.com/youbaiyun/dsh-browser-application#readme",
+  "bugs": {
+    "url": "https://github.com/youbaiyun/dsh-browser-application/issues"
+  }
+}

package/src/bridge-url.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+
+import { BRIDGE_CONFIG_PATH, BRIDGE_PATH } from '@dsh-browser/protocol'
+
+/** 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 function bridgeWsUrlFromLocation(
+  location: BridgeLocationLike,
+  bridgePath: string = BRIDGE_PATH,
+): string {
+  const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
+  const hostname = location.hostname === 'localhost' ? '127.0.0.1' : location.hostname
+  const host = location.port === '' ? hostname : `${hostname}:${location.port}`
+  return `${wsProtocol}//${host}${bridgePath}`
+}
+
+/**
+ * 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 async function resolveBridgeWsUrl(
+  location: BridgeLocationLike & { origin?: string },
+  fetchImpl: typeof fetch = fetch,
+  bridgeConfigPath: string = BRIDGE_CONFIG_PATH,
+): Promise<string> {
+  const fallback = bridgeWsUrlFromLocation(location)
+  try {
+    const base = location.origin ?? `${location.protocol}//${location.host}`
+    const response = await fetchImpl(`${base}${bridgeConfigPath}`, {
+      signal: AbortSignal.timeout(1_500),
+    })
+    if (!response.ok) return fallback
+    const body = await response.json() as { wsUrl?: unknown }
+    if (typeof body.wsUrl === 'string' && (body.wsUrl.startsWith('ws://') || body.wsUrl.startsWith('wss://'))) {
+      return body.wsUrl
+    }
+  } catch {
+    // Discovery is best-effort: the settings row still shows the reconstructed URL.
+  }
+  return fallback
+}

package/src/browser-context.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { createUserMessage, 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 const BROWSER_CONTEXT_KIND = 'browser-context' as const
+
+/** Bound orphaned provisional sessions while retaining normal recent tabs. */
+const DEFAULT_MAX_PENDING = 32
+
+/** Build one immutable context message from a captured browser snapshot. */
+export function createBrowserSnapshotMessage(snapshot: string): UserMessage {
+  const text = [
+    'The user chose to follow the newly active browser tab. The browser page context was refreshed immediately after that choice.',
+    'The following is an already completed browser_snapshot of the current page. Use its stable indices directly for the next request; do not take an immediate duplicate snapshot unless required context is missing.',
+    snapshot,
+  ].join('\n\n')
+  return createUserMessage({
+    content: [{ type: 'text', text }],
+    source: {
+      kind: BROWSER_CONTEXT_KIND,
+      form: 'snapshot',
+      sections: [{ name: 'browser-page', text }],
+    },
+  })
+}
+
+/** Supersede pending tab context through the durable Inbox command surface. */
+function injectLatestSnapshot(agent: Agent, snapshot: string): void {
+  for (const message of agent.inbox.nextStep) {
+    if (message.source.kind === BROWSER_CONTEXT_KIND
+      && message.source.form === 'snapshot') {
+      agent.inbox.remove(message.id)
+    }
+  }
+  agent.inject(createBrowserSnapshotMessage(snapshot))
+}
+
+/** Deliver followed-page snapshots to live or not-yet-materialized Agents. */
+export class BrowserContextInjector {
+  private readonly pending = new Map<string, string>()
+
+  constructor(
+    private readonly agents: Pick<AgentRegistry, 'get'>,
+    private readonly maxPending = DEFAULT_MAX_PENDING,
+  ) {
+    if (!Number.isInteger(maxPending) || maxPending < 1) {
+      throw new Error('browser context maxPending must be a positive integer')
+    }
+  }
+
+  /** Inject now when possible; otherwise retain the newest snapshot per session. */
+  inject(sessionId: string, snapshot: string): 'injected' | 'queued' {
+    const agent = this.agents.get(sessionId as Parameters<AgentRegistry['get']>[0])
+    if (agent !== undefined) {
+      this.pending.delete(sessionId)
+      injectLatestSnapshot(agent, snapshot)
+      return 'injected'
+    }
+
+    // Refresh insertion order when the same provisional session follows again.
+    this.pending.delete(sessionId)
+    while (this.pending.size >= this.maxPending) {
+      const oldest = this.pending.keys().next().value as string | undefined
+      if (oldest === undefined) break
+      this.pending.delete(oldest)
+    }
+    this.pending.set(sessionId, snapshot)
+    return 'queued'
+  }
+
+  /** Flush one provisional session at the supported Agent startup boundary. */
+  activate(agent: Agent): boolean {
+    const sessionId = String(agent.id)
+    const snapshot = this.pending.get(sessionId)
+    if (snapshot === undefined) return false
+    injectLatestSnapshot(agent, snapshot)
+    this.pending.delete(sessionId)
+    return true
+  }
+}

package/src/dsh-gateway.ts

@@ -0,0 +1,66 @@
+/**
+ * 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>
+}
+
+/**
+ * Empty Client→Host uplink for in-process Host wireStream.open calls.
+ * dsh 0.2 requires the uplink slot; Gateway-owned endpoints ($events) discard
+ * it immediately, and Remote streams still need a valid AsyncIterable.
+ */
+const EMPTY_WIRE_UPLINK: AsyncIterable<unknown> = {
+  async *[Symbol.asyncIterator]() { /* no uplink items */ },
+}
+
+/**
+ * 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 function openWireStream(gateway: TypertGatewayLike, endpoint: string, payload: unknown, signal: AbortSignal): Promise<AsyncIterable<unknown>> {
+  const open = gateway.wireStream.open
+  if (open.length === 3) {
+    return open(endpoint, payload, signal)
+  }
+  return open(endpoint, payload, EMPTY_WIRE_UPLINK, undefined, signal)
+}
+
+/** Structural subset of dsh 0.2's Host Connection service. */
+export interface HostConnectionLike {
+  createSharedFetchHandler(channel: '/api'): {
+    fetch(request: Request): Promise<Response>
+  }
+}