dsh-browser-plus 0.0.0-stage → 0.5.1

package/src/browser-electron/task-summary.ts

@@ -0,0 +1,10 @@
+/** Return a page-safe task location without path, query, or fragment data. */
+export function taskSummaryUrl(raw: string): string {
+  if (raw === '') return ''
+  try {
+    const origin = new URL(raw).origin
+    return origin === 'null' ? '' : origin
+  } catch {
+    return ''
+  }
+}

package/src/browser-electron/task-thumbnail.ts

@@ -0,0 +1,17 @@
+export const TASK_THUMBNAIL_WIDTH = 288
+export const TASK_THUMBNAIL_JPEG_QUALITY = 58
+export const MAX_TASK_THUMBNAIL_BYTES = 180 * 1024
+
+export interface ThumbnailImage {
+  resize(options: { width: number }): {
+    toJPEG(quality: number): Buffer
+  }
+}
+
+export function taskThumbnailDataUrl(image: ThumbnailImage): string | undefined {
+  const jpeg = image.resize({ width: TASK_THUMBNAIL_WIDTH }).toJPEG(TASK_THUMBNAIL_JPEG_QUALITY)
+
+  if (jpeg.length === 0 || jpeg.length > MAX_TASK_THUMBNAIL_BYTES) return undefined
+
+  return `data:image/jpeg;base64,${jpeg.toString('base64')}`
+}

package/src/browser-electron/write-guard.ts

@@ -0,0 +1,134 @@
+/**
+ * Write-path admission for browser-produced files (screenshots, downloads).
+ *
+ * The provider — not the host — owns this guard so one implementation covers
+ * the self-hosted Electron host and desktop-shell handles alike, and so it can
+ * be exercised without Electron. Roots are resolved through the deepest
+ * existing ancestor, which keeps a symlinked or `..`-laden target from
+ * escaping a root it only appears to sit inside.
+ * @module dsh-browser-plus/browser-electron/write-guard
+ */
+
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { BrowserError } from '../browser/types.ts'
+
+/**
+ * Roots a browser write may target when the config does not name any: the
+ * DSH workspace (the process working directory) and the OS temp directory.
+ * This mirrors the DSH file sandbox's "write inside the workspace" boundary.
+ */
+export function defaultWriteRoots(): string[] {
+  return [process.cwd(), tmpdir()]
+}
+
+/** Windows paths compare case-insensitively; POSIX paths do not. */
+function comparable(value: string): string {
+  return process.platform === 'win32' ? value.toLowerCase() : value
+}
+
+/**
+ * Resolve symlinks on the deepest ancestor that exists, then re-append the
+ * segments that do not. A save target usually does not exist yet, so the
+ * target itself cannot be realpath'd — but its parent usually can.
+ */
+function realpathOfNearestAncestor(target: string): string {
+  let current = target
+  const tail: string[] = []
+  for (;;) {
+    try {
+      const real = realpathSync.native(current)
+      return tail.length === 0 ? real : join(real, ...[...tail].reverse())
+    } catch {
+      const parent = dirname(current)
+      // Reached the filesystem root without finding anything real: fall back
+      // to the lexical path rather than denying a legitimate write.
+      if (parent === current) return target
+      tail.push(basename(current))
+      current = parent
+    }
+  }
+}
+
+/** True when `candidate` is `root` itself or lives beneath it. */
+function within(candidate: string, root: string): boolean {
+  if (candidate === root) return true
+  return candidate.startsWith(root.endsWith(sep) ? root : root + sep)
+}
+
+/** Real, comparable forms of both sides; roots are normalized exactly once per call. */
+function resolvedPair(candidate: string, roots: readonly string[]): { target: string; roots: string[] } {
+  return {
+    target: comparable(realpathOfNearestAncestor(resolve(candidate))),
+    roots: roots.map(root => comparable(realpathOfNearestAncestor(resolve(root)))),
+  }
+}
+
+/**
+ * Whether a path would be admitted by {@link resolveWritePath}, without
+ * throwing. Exposed for focused tests and for callers that want to probe.
+ * @param candidate - the path to test.
+ * @param roots - the allowed roots.
+ */
+export function isWithinRoots(candidate: string, roots: readonly string[]): boolean {
+  const { target, roots: resolved } = resolvedPair(candidate, roots)
+  return resolved.some(root => within(target, root))
+}
+
+/**
+ * Resolve a write target and admit it only when it lands inside one of the
+ * allowed roots. Returns the absolute path to write.
+ * @param savePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every write.
+ * @throws BrowserError `BROWSER_WRITE_PATH_DENIED` when the path is unusable or outside every root.
+ */
+export function resolveWritePath(savePath: string, roots: readonly string[]): string {
+  if (typeof savePath !== 'string' || savePath.trim() === '') {
+    throw new BrowserError('browser: refusing to write without a save path', 'BROWSER_WRITE_PATH_DENIED')
+  }
+  const absolute = resolve(savePath)
+  if (!isWithinRoots(absolute, roots)) {
+    // This message reaches the model context and, through a task's error field,
+    // the page itself — so it never names an absolute path.
+    const hint = roots.length === 0 ? ' (none configured)' : ''
+    throw new BrowserError(
+      `browser: refusing to write "${savePath}" outside the allowed roots${hint}; `
+      + 'add the directory to the browser-electron "writeRoots" config to allow it',
+      'BROWSER_WRITE_PATH_DENIED',
+    )
+  }
+  return absolute
+}
+
+/**
+ * Resolve a file the browser is about to hand to a page and admit it only when
+ * it lands inside one of the allowed roots. Unlike a write target the file must
+ * already exist, so the path itself is realpath'd: a symlink to a permitted
+ * file is admitted, a symlink that leaves the roots is not.
+ * @param filePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every read.
+ * @throws BrowserError `BROWSER_READ_PATH_DENIED` when the path is unusable, missing, or outside every root.
+ */
+export function resolveReadPath(filePath: string, roots: readonly string[]): string {
+  if (typeof filePath !== 'string' || filePath.trim() === '') {
+    throw new BrowserError('browser: refusing to read without a file path', 'BROWSER_READ_PATH_DENIED')
+  }
+  const absolute = resolve(filePath)
+  let real: string
+  try {
+    real = realpathSync.native(absolute)
+  } catch {
+    throw new BrowserError(`browser: refusing to read "${filePath}": the file does not exist`, 'BROWSER_READ_PATH_DENIED')
+  }
+  const allowed = roots.map(root => comparable(realpathOfNearestAncestor(resolve(root))))
+  if (!allowed.some(root => within(comparable(real), root))) {
+    const hint = roots.length === 0 ? ' (none configured)' : ''
+    throw new BrowserError(
+      `browser: refusing to read "${filePath}" outside the allowed roots${hint}; `
+      + 'add the directory to the browser-electron "readRoots" config to allow it',
+      'BROWSER_READ_PATH_DENIED',
+    )
+  }
+  return absolute
+}

package/src/command-browser/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Human-facing `/browser` command: puts the shared browser window on screen
+ * without going through the model.
+ *
+ * The window is normally created as a side effect of the first browser tool
+ * call, so a human who wants to browse (or take over) before any agent call had
+ * no way to raise it. `/browser` is that way in: it spawns the host and shows
+ * the window when nothing is open, and raises the existing window otherwise.
+ *
+ * The command registry is declared structurally instead of imported from
+ * `@deepseek-ai/dsh-commands`: the registry is a peer service the profile
+ * provides, and depending on that package only for its types would make this
+ * row fail to load wherever the service exists but the dependency does not.
+ * @module dsh-browser-plus/command-browser
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+
+/** The invocation the dispatcher hands a handler. */
+interface CommandInvocation {
+  /** Everything after the command name, verbatim. */
+  readonly rawInput: string
+}
+
+/** What the dispatching UI renders for one settled execution. */
+type CommandOutcome =
+  | { readonly kind: 'success'; readonly text?: string }
+  | { readonly kind: 'error'; readonly text: string }
+
+/** One definition accepted by the registry. */
+interface CommandDefinition {
+  readonly name: string
+  readonly description: string
+  readonly handler: (invocation: CommandInvocation) => Promise<CommandOutcome> | CommandOutcome
+}
+
+/** The registry this plugin registers into, satisfied by `@deepseek-ai/dsh-commands`. */
+interface CommandRegistry {
+  register(definition: CommandDefinition): void
+}
+
+export const name = 'browser-command'
+export const inject = ['browser', 'commands']
+
+/** Register the command. */
+export function apply(ctx: Context, _config: unknown = {}): void {
+  const commands = (ctx as unknown as { readonly commands: CommandRegistry }).commands
+  commands.register({
+    name: 'browser',
+    description: '打开并前置共享浏览器窗口',
+    handler: async () => {
+      try {
+        await ctx.browser.ensureWindowVisible()
+        return { kind: 'success', text: '浏览器窗口已打开。' }
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error)
+        return { kind: 'error', text: `打开浏览器窗口失败：${detail}` }
+      }
+    },
+  })
+}

package/src/http-browser/index.ts

@@ -0,0 +1,139 @@
+/**
+ * The HTTP bridge the browser panel talks to.
+ *
+ * The panel lives in the Web GUI, the window lives in the DSH process, and a
+ * client bundle has no way to call a server-side plugin method directly: the
+ * generated Remote/Typert surface exists for product packages, not for a
+ * third-party plugin built with plain tsc. The DSH web server, however, is a
+ * service this plugin can register routes on, and the GUI is served from that
+ * same origin — so one POST is the whole bridge.
+ *
+ * Routes (all JSON, no-store):
+ *   POST /api/dsh-browser-plus/open   -> { ok: true } once the window is up
+ *   GET  /api/dsh-browser-plus/status -> { ok: true, tasks: number }
+ *
+ * The `webServer` service is declared structurally rather than imported from
+ * `@deepseek-ai/dsh-host-webserver`: this row must load wherever the service
+ * exists, without taking a build-time dependency on the package that owns it.
+ * @module dsh-browser-plus/http-browser
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Absolute path of the "open the window" endpoint. */
+export const OPEN_PATH = '/api/dsh-browser-plus/open'
+/** Absolute path of the status endpoint. */
+export const STATUS_PATH = '/api/dsh-browser-plus/status'
+
+/** The request fields these handlers read. */
+interface WebRequest {
+  readonly method?: string
+  readonly headers?: Record<string, string | string[] | undefined>
+}
+
+/** The response surface these handlers use (a subset of `ServerResponse`). */
+interface WebResponse {
+  statusCode: number
+  setHeader(name: string, value: string): void
+  end(chunk?: string): void
+}
+
+/** One route registration. */
+interface WebRoute {
+  readonly kind: 'exact' | 'prefix'
+  readonly path: string
+  readonly handler: (req: WebRequest, res: WebResponse) => void | Promise<void>
+}
+
+/** The route registry this plugin registers into. */
+interface WebServerService {
+  register(route: WebRoute): () => void
+}
+
+export const name = 'browser-http'
+export const inject = ['browser', 'webServer']
+
+/** Write one JSON response. */
+function sendJson(res: WebResponse, status: number, payload: unknown): void {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(payload))
+}
+
+/** Read one request header as a single string. */
+function headerValue(req: WebRequest, name: string): string {
+  const raw = req.headers?.[name]
+  return Array.isArray(raw) ? (raw[0] ?? '') : (raw ?? '')
+}
+
+/**
+ * Refuse a request that a page on another site made.
+ *
+ * These two endpoints are unauthenticated and only open a window / report a task
+ * count — but any web page can POST to localhost without a preflight, so without
+ * this check a random site could pop our browser window open. The panel's own
+ * fetch is same-origin, so its Origin always matches the Host we were reached on.
+ */
+function fromAnotherSite(req: WebRequest): boolean {
+  const origin = headerValue(req, 'origin')
+  if (origin === '') return false
+  try {
+    const parsed = new URL(origin)
+    const host = headerValue(req, 'host')
+    return host === '' || parsed.host !== host
+  } catch {
+    return true
+  }
+}
+
+/** One line for the panel to show; never a stack. */
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** Register the browser-panel bridge. */
+export function apply(ctx: Context, _config: unknown = {}): void {
+  const server = (ctx as unknown as { readonly webServer?: WebServerService }).webServer
+  if (server === undefined) return
+  ctx.effect(() => server.register({
+    kind: 'exact',
+    path: OPEN_PATH,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        return
+      }
+      if (fromAnotherSite(req)) {
+        sendJson(res, 403, { ok: false, error: 'cross-site request refused' })
+        return
+      }
+      try {
+        await ctx.browser.ensureWindowVisible()
+        sendJson(res, 200, { ok: true })
+      } catch (error) {
+        sendJson(res, 500, { ok: false, error: describe(error) })
+      }
+    },
+  }), 'dsh-browser-plus:open route')
+  ctx.effect(() => server.register({
+    kind: 'exact',
+    path: STATUS_PATH,
+    handler: async (req, res) => {
+      if (req.method !== 'GET') {
+        sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        return
+      }
+      if (fromAnotherSite(req)) {
+        sendJson(res, 403, { ok: false, error: 'cross-site request refused' })
+        return
+      }
+      try {
+        const tasks = await ctx.browser.listTasks()
+        sendJson(res, 200, { ok: true, tasks: tasks.length })
+      } catch (error) {
+        sendJson(res, 500, { ok: false, error: describe(error) })
+      }
+    },
+  }), 'dsh-browser-plus:status route')
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * dsh-browser-plus plugin entry: aggregates the shared-browser capability
+ * pieces. The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-browser-plus/browser`          -> the ctx.browser seam (Service)
+ *   - `dsh-browser-plus/browser-electron` -> the Electron CDP provider
+ *   - `dsh-browser-plus/tool-browser`     -> the model-facing browser_* tools
+ * This root entry only re-exports for programmatic use; the loader rows are
+ * the composition surface.
+ *
+ * It IS also mounted as a row of its own — an empty one — because the client
+ * module system only scans Loader rows whose specifier is an exact package root
+ * (`exactPackageSpecifier` in `@deepseek-ai/dsh-client-modules` returns
+ * undefined for a subpath). Without a root row the package's `dsh.client`
+ * declaration is never read and the browser panel never reaches the GUI, no
+ * matter how many subpath rows the bundle patch adds.
+ * @module dsh-browser-plus
+ */
+
+/** Plugin name for the root row. */
+export const name = 'browser-plus'
+
+/** The root row has no behaviour of its own; it exists to carry the package identity. */
+export function apply(): void {}
+
+export { BrowserError } from './browser/types.ts'
+export type {
+  BrowserChallenge,
+  BrowserContentFormat,
+  BrowserControlOwner,
+
+  BrowserContentRequest,
+  BrowserContentResult,
+  BrowserDragRequest,
+  BrowserDragResult,
+  BrowserExecuteRequest,
+  BrowserPointerResult,
+  BrowserPointerTarget,
+  BrowserExecuteResult,
+  BrowserFillField,
+  BrowserFillRequest,
+  BrowserFillResult,
+  BrowserHandoffState,
+  BrowserNavigateRequest,
+  BrowserOpenRequest,
+  BrowserProvider,
+  BrowserRefRequest,
+  BrowserScreenshotRequest,
+  BrowserScrollIntoViewRequest,
+  BrowserScrollRequest,
+  BrowserScrollResult,
+  BrowserScreenshotResult,
+  BrowserSessionId,
+  BrowserSnapshotElement,
+  BrowserSnapshotResult,
+  BrowserTab,
+  BrowserTaskInfo,
+  BrowserTaskStatus,
+  BrowserTaskUpdate,
+  BrowserTypeRequest,
+  ExportedCookie,
+} from './browser/types.ts'
+export { BrowserRuntime } from './browser/runtime.ts'
+export { ElectronBrowserProvider } from './browser-electron/provider.ts'
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './browser-electron/provider.ts'
+export { RemoteElectronViewHost, defaultHostMainPath } from './browser-electron/remote-host.ts'

package/src/task-todos/index.ts

@@ -0,0 +1,114 @@
+/**
+ * Bridge between the Agent's todo list and the shared browser window.
+ *
+ * DSH keeps each Agent's plan as a session projection (`todos`, written by
+ * `todo_write` and folded from `todo/write` events). The floating orb in the
+ * browser window renders that plan, but the browser host is a child process that
+ * can only see what the parent hands it — so this row subscribes to the
+ * projection change feed and mirrors the plan into the browser provider.
+ *
+ * Every dependency here is optional on purpose. A deployment without the
+ * projection registry, or without the todo tool mounted at all, must still get a
+ * working browser: the orb then simply has no plan to show and falls back to the
+ * task's own status and last browser action.
+ * @module dsh-browser-plus/task-todos
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+
+/** One entry as this bridge forwards it (the provider validates again). */
+interface TodoItem {
+  readonly content: string
+  readonly status: 'pending' | 'in_progress' | 'completed'
+}
+
+/** The browser seam surface this bridge uses. */
+interface TodoSink {
+  pushTaskTodos?(taskKey: string, todos: readonly TodoItem[]): Promise<void>
+}
+
+/** Minimal shape of `ctx.sessionProjections` (kept structural). */
+interface ProjectionRegistry {
+  onChanged(listener: (session: { readonly id?: unknown }, key: string, value: unknown, seq: number) => void): () => void
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'browser-task-todos'
+
+/** The browser seam; the projection registry is injected optionally below. */
+export const inject = ['browser']
+
+/** Keep at most this many entries — the orb shows a short list, not a backlog. */
+const MAX_ITEMS = 40
+
+/** Keep one entry short enough to read in a popover. */
+const MAX_CONTENT = 160
+
+/**
+ * Normalize whatever the projection holds into the orb's three states. Anything
+ * unrecognized becomes `pending` rather than being dropped: a plan line the UI
+ * cannot classify is still a line the human asked to see.
+ * @param value - the projection's raw `todos` value.
+ * @returns the entries to forward.
+ */
+function normalize(value: unknown): TodoItem[] {
+  if (!Array.isArray(value)) return []
+  const items: TodoItem[] = []
+  for (const raw of value) {
+    const entry = raw as { content?: unknown; status?: unknown }
+    if (typeof entry?.content !== 'string') continue
+    const content = entry.content.trim()
+    if (content === '') continue
+    const status = entry.status === 'completed' || entry.status === 'in_progress' ? entry.status : 'pending'
+    items.push({ content: content.slice(0, MAX_CONTENT), status })
+    if (items.length >= MAX_ITEMS) break
+  }
+  return items
+}
+
+/**
+ * Register the bridge.
+ * @param ctx - plugin context carrying the browser seam.
+ */
+export function apply(ctx: Context): void {
+  // 只在**失败**路径上留话：这条链横跨「会话投影 → 桥接行 → provider → 宿主 → 页面」，
+  // 任一环断掉在页面上都只表现为「球上没有清单」，正常路径一声不响。
+  const trace = (line: string): void => { try { process.stderr.write('[browser-task-todos] ' + line + '\n') } catch { /* no stderr */ } }
+  const browser = (ctx as unknown as { readonly browser?: TodoSink }).browser
+  if (browser === undefined || typeof browser.pushTaskTodos !== 'function') {
+    trace('skip: the browser seam has no pushTaskTodos')
+    return
+  }
+  const push = browser.pushTaskTodos.bind(browser)
+  // `ctx.inject` keeps the row loadable when the registry is absent: the
+  // callback simply never runs and the browser keeps working without a plan.
+  ctx.inject(['sessionProjections'], (scoped: Context) => {
+    const registry = (scoped as unknown as { readonly sessionProjections?: ProjectionRegistry }).sessionProjections
+    if (registry === undefined || typeof registry.onChanged !== 'function') {
+      trace('sessionProjections arrived without onChanged')
+      return
+    }
+    // 每个会话最后一份清单。宿主重启会丢掉它内存里那份，而桥接只在**变化**时推 ——
+    // 存一份就能在「这个会话又发生了什么」时顺手补推（见下面的 !isTodos 分支）。
+    const lastTodos = new Map<string, readonly TodoItem[]>()
+    const off = registry.onChanged((session, key, value) => {
+      const taskKey = typeof session?.id === 'string' ? session.id : ''
+      if (taskKey === '') return
+      if (key !== 'todos') {
+        // 该会话的**其它**投影变了 —— 说明它活着，把手里那份计划补推一次。
+        // 这覆盖「DSH 重启后 / 宿主重启后球上一直空着」：只要会话再有任何活动，清单就回来。
+        const known = lastTodos.get(taskKey)
+        if (known !== undefined) void push(taskKey, known).catch(() => undefined)
+        return
+      }
+      // The tool layer keys browser tasks by the calling Agent's id, which is the
+      // session id — so a plan written by an Agent lands on that Agent's task.
+      const todos = normalize(value)
+      lastTodos.set(taskKey, todos)
+      void push(taskKey, todos).catch(() => undefined)
+    })
+    // 监听器挂在 registry 自己的 fiber 上，插件被卸载/重载时要自己摘掉，
+    // 否则会残留一条绑在旧 seam 上的推送（review 报的 L5）。
+    if (typeof off === 'function') ctx.effect(() => off)
+  })
+}