dsh-browser-plus 0.5.0 → 0.5.1

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

@@ -6,9 +6,22 @@
  *   - `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,

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)
+  })
+}