dsh-browser-verify 0.1.0

package/lib/types/cleanup.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Orphan cleanup for dsh-browser-verify: temp dirs and zombie Chromium
+ * processes left by crashes. Parsers are pure; callers do the I/O.
+ * @module dsh-browser-verify/cleanup
+ */
+/** One line from `ps -Ao pid=,ppid=,command=` (macOS). */
+export declare function parseZombiePids(psText: string, prefix: string, selfPid: number): number[];
+export interface OrphanDir {
+    path: string;
+    mtimeMs: number;
+}
+/** Pick degraded-run temp dirs: name prefixed, old enough, not the current pid dir. */
+export declare function selectOrphanDirs(entries: Array<{
+    path: string;
+    mtimeMs: number;
+}>, nowMs: number, ageMs: number, prefix: string): OrphanDir[];
+//# sourceMappingURL=cleanup.d.ts.map

package/lib/types/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Debug CLI for dsh-browser-verify: exercises the same core the tools use,
+ * without the harness. Prints structured JSON results.
+ * @module dsh-browser-verify/cli
+ */
+export interface CliOptions {
+    url: string;
+    mockFile?: string;
+    waitSelector?: string;
+    assertSelector?: string;
+    screenshot?: boolean;
+    persistDir?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export declare function parseCliArgs(argv: string[]): CliOptions;
+//# sourceMappingURL=cli.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "browser-verify";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/tools/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The four model-facing browser verification tools. Thin shells: validate
+ * args, take the driver lock, run the scenario core, translate failures.
+ * @module dsh-browser-verify/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare function registerBrowserTools(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/tools/timeout.d.ts

@@ -0,0 +1,3 @@
+/** Race a promise against a deadline; the loser's work is abandoned, not awaited. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "dsh-browser-verify",
+  "description": "Read-only browser verification tools for the DeepSeek Harness web GUI: browser_open / browser_mock / browser_assert / browser_screenshot — verify a page (H5/desktop) in ≤4 tool calls with mock interception, DOM assertions, and screenshots that auto-project into the model context.",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "pnpm@11.7.0",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.1.2-alpha.1"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('lib', { recursive: true, force: true })\" && tsc -b && tsdown",
+    "typecheck": "tsc -b --pretty false && tsc -p tsconfig.vitest.json --pretty false",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "playwright-core": "1.62.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.4",
+    "@types/node": "^22.20.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "tsdown": "0.22.2",
+    "typescript": "~5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "license": "Apache-2.0"
+}

package/src/attachments.ts

@@ -0,0 +1,91 @@
+/**
+ * Screenshot persistence + model projection, mirroring the read_image output
+ * direction: save into the durable attachment store, render a text envelope
+ * beside the image block the harness projects into the next model request.
+ * @module dsh-browser-verify/attachments
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment'
+import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+
+export interface ScreenshotImage {
+  attachmentId: string
+  mediaType: ImageMediaType
+  bytes: number
+  width: number
+  height: number
+  name?: string
+}
+
+export interface ScreenshotValue {
+  image: ScreenshotImage
+  sha256: string
+  identicalToPrevious: boolean
+}
+
+export function imageRefFromValue(image: ScreenshotImage): ImageAttachmentRef {
+  return {
+    attachmentId: AttachmentId(image.attachmentId),
+    mediaType: image.mediaType,
+    bytes: image.bytes,
+    width: image.width,
+    height: image.height,
+    ...image.name === undefined ? {} : { name: image.name },
+  }
+}
+
+export function renderScreenshotBlocks(value: ScreenshotValue): ContentBlock[] {
+  const dup = value.identicalToPrevious
+    ? '（与上一张截图哈希相同，疑似页面未刷新；请 browser_open 重开场景后重试）'
+    : ''
+  return [
+    {
+      type: 'text',
+      text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`,
+    },
+    { type: 'image', attachment: imageRefFromValue(value.image) },
+  ]
+}
+
+/** Persist screenshot bytes, mapping store refusals to actionable errors. */
+export async function saveScreenshot(ctx: Context, data: Buffer, name: string | undefined): Promise<ImageAttachmentRef> {
+  const attachments = ctx.get('attachments')
+  if (attachments === undefined) {
+    throw new Error('browser-verify: 附件存储未挂载，无法持久化截图。请检查当前 DSH 组合是否包含 attachment 插件。')
+  }
+  try {
+    return await attachments.saveImage({ data, mediaType: 'image/png', ...name === undefined ? {} : { name } })
+  } catch (error: unknown) {
+    if (!(error instanceof AttachmentError)) throw error
+    if (error.code === 'IMAGE_TOO_LARGE') {
+      throw new Error('browser-verify: 截图超过 attachment 存储字节上限。请改用 fullPage:false 或调低 deviceScaleFactor 后重试。', { cause: error })
+    }
+    if (error.code === 'IMAGE_DIMENSION_TOO_LARGE' || error.code === 'IMAGE_TOO_MANY_PIXELS') {
+      throw new Error('browser-verify: 截图尺寸超过 attachment 存储限制。请改用 fullPage:false 或调低 deviceScaleFactor 后重试。', { cause: error })
+    }
+    if (error.code === 'IMAGE_TYPE_MISMATCH') {
+      throw new Error(`browser-verify: 截图格式校验失败：${error.message} 请改用其他附件类型或重试。`, { cause: error })
+    }
+    throw error
+  }
+}
+
+/** Gate: the calling route must be able to see image input (mirror of read-image). */
+export async function assertImageCapable(
+  ctx: Context,
+  exec: { agent?: { session?: { requestHeader?: () => { config?: { provider?: string; model?: string } } | undefined }; options?: { provider?: string; model?: string } } },
+): Promise<void> {
+  const routed = exec.agent?.session?.requestHeader?.()?.config
+  const provider = routed?.provider ?? exec.agent?.options?.provider
+  const model = routed?.model ?? exec.agent?.options?.model
+  const llm = ctx.get('llm')
+  if (provider === undefined || model === undefined || llm === undefined) {
+    throw new Error('browser-verify: 无法解析当前模型路由（或模型服务未挂载），无法判断图片输入能力。请检查当前会话的模型路由配置后重试。')
+  }
+  const active = await llm.resolveModelInfo(provider, model)
+  if (active.inputModalities === undefined || !active.inputModalities.includes('image')) {
+    throw new Error('browser-verify: 当前模型不支持看图：请改用 browser_assert 做文本断言（更省 token），或切换到图片模型后重试。')
+  }
+}

package/src/browser/discover.ts

@@ -0,0 +1,104 @@
+/**
+ * Locate a Browser-for-Testing binary in the machine playwright cache. Pure:
+ * filesystem probing is injected so every branch is unit-testable.
+ * @module dsh-browser-verify/browser/discover
+ */
+
+import { existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export type BrowserKind = 'headless-shell' | 'chromium' | 'custom'
+
+/** Revision numbers verified against the matching playwright-core browsers.json. */
+export const KNOWN_REVISIONS: Readonly<Record<number, string>> = {
+  1234: '1.62.x',
+}
+
+export interface DiscoveredBrowser {
+  executablePath: string
+  kind: BrowserKind
+  revision: number
+  known: boolean
+  versionHint: string | null
+}
+
+export interface DiscoverOptions {
+  cacheDir?: string
+  overridePath?: string
+  exists?: (path: string) => boolean
+  /** Directory listing of cacheDir; defaults to readdirSync(cacheDir) (throws → treated as missing). */
+  entries?: string[]
+}
+
+const SUBDIRS: Readonly<Record<'headless-shell' | 'chromium', string>> = {
+  'headless-shell': 'chrome-headless-shell-mac-arm64/chrome-headless-shell',
+  chromium: 'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+}
+
+const LIST_PREFIXES: Readonly<Array<{ kind: 'headless-shell' | 'chromium'; prefix: string }>> = [
+  { kind: 'headless-shell', prefix: 'chromium_headless_shell-' },
+  { kind: 'chromium', prefix: 'chromium-' },
+]
+
+/** Default cache location on macOS. */
+export function defaultCacheDir(): string {
+  return join(homedir(), 'Library', 'Caches', 'ms-playwright')
+}
+
+function maxRevision(list: string[], prefix: string): number | null {
+  let max: number | null = null
+  for (const entry of list) {
+    if (!entry.startsWith(prefix)) continue
+    const suffix = entry.slice(prefix.length)
+    if (!/^\d+$/.test(suffix)) continue
+    const value = Number(suffix)
+    if (max === null || value > max) max = value
+  }
+  return max
+}
+
+/**
+ * Find the browser binary: env override wins, then headless shell (highest
+ * revision), then full chromium. Throws with an install hint when absent.
+ */
+export function discoverBrowser(opts: DiscoverOptions = {}): DiscoveredBrowser {
+  const exists = opts.exists ?? existsSync
+  if (opts.overridePath !== undefined) {
+    if (!exists(opts.overridePath)) {
+      throw new Error(`browser-verify: DSH_BROWSER_VERIFY_CHROMIUM 指向的二进制不存在: ${opts.overridePath}。请检查路径或取消该环境变量。`)
+    }
+    return { executablePath: opts.overridePath, kind: 'custom', revision: 0, known: true, versionHint: null }
+  }
+  const cacheDir = opts.cacheDir ?? defaultCacheDir()
+  let list: string[] | null = null
+  if (opts.entries !== undefined) {
+    list = opts.entries
+  } else {
+    try {
+      list = readdirSync(cacheDir)
+    } catch {
+      list = null
+    }
+  }
+  if (list === null) {
+    throw new Error(`browser-verify: 未找到浏览器缓存目录 ${cacheDir}。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`)
+  }
+  for (const { kind, prefix } of LIST_PREFIXES) {
+    const revision = maxRevision(list, prefix)
+    if (revision === null) continue
+    const executablePath = join(cacheDir, `${kind === 'headless-shell' ? `chromium_headless_shell-${revision}` : `chromium-${revision}`}`, SUBDIRS[kind])
+    if (!exists(executablePath)) {
+      throw new Error(`browser-verify: 缓存目录存在 ${prefix}${revision} 但可执行文件缺失（${cacheDir}）。请删除该目录后重新执行 npx playwright install chromium。`)
+    }
+    const known = KNOWN_REVISIONS[revision] !== undefined
+    return {
+      executablePath,
+      kind,
+      revision,
+      known,
+      versionHint: known ? null : `浏览器 revision ${revision} 不在已认证表（playwright-core 1.62.0 认证 ${Object.keys(KNOWN_REVISIONS).join('/')}）；若协议异常，请安装匹配版本`,
+    }
+  }
+  throw new Error(`browser-verify: 未找到浏览器二进制。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`)
+}

package/src/browser/driver.ts

@@ -0,0 +1,213 @@
+/**
+ * Browser driving: one lazy launch per process, one active verification
+ * scenario, FIFO-serialized tool access, idle reclamation, graceful close +
+ * temp dir removal on dispose. launch args are pure for unit tests.
+ * @module dsh-browser-verify/browser/driver
+ */
+
+import { exec } from 'node:child_process'
+import { rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { chromium, type Browser } from 'playwright-core'
+import { discoverBrowser, type DiscoveredBrowser } from './discover.ts'
+import { Scenario, type OpenResult } from './scenario.ts'
+
+export interface OpenScenarioResult extends OpenResult {
+  browserKnown: boolean
+  versionHint: string | null
+}
+
+/**
+ * Headless launch args. Deviation D8-3: playwright-core >= 1.41 rejects
+ * `--user-data-dir` inside `args` (misuse error, both launch and
+ * launchPersistentContext); the user data dir must be passed as the
+ * launchPersistentContext first parameter. Only the headless-mode flag remains.
+ */
+export function buildLaunchArgs(headlessShell: boolean): string[] {
+  return [headlessShell ? '--headless' : '--headless=new']
+}
+
+export class BrowserDriver {
+  private browser: Browser | null = null
+  private discovered: DiscoveredBrowser | null = null
+  private scenario: Scenario | null = null
+  private readonly userDataDir = join(tmpdir(), `dsh-browser-verify-${process.pid}`, 'profile')
+  private idleTimer: NodeJS.Timeout | null = null
+  private lockChain: Promise<unknown> = Promise.resolve()
+  private disposed = false
+
+  constructor(
+    private readonly opts: {
+      discover?: typeof discoverBrowser
+      viewport?: { width: number; height: number }
+      deviceScaleFactor?: number
+      timeoutMs?: number
+      idleMs?: number
+    } = {},
+  ) {}
+
+  /** FIFO serialization: every tool op runs alone. */
+  private chain<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.lockChain.then(fn)
+    this.lockChain = run.catch(() => undefined)
+    return run
+  }
+
+  /** Reject new op entries once disposed; the engine cannot come back. */
+  private ensureNotDisposed(): void {
+    if (this.disposed) {
+      throw new Error('browser-verify: 验证引擎已停止。请重新调用 browser_open 开始新的验证。')
+    }
+  }
+
+  /** Normalize errors at the driver boundary: prefix + context + advice. */
+  private wrapError(error: unknown, context: string, advice: string): Error {
+    if (error instanceof Error && error.message.startsWith('browser-verify: ')) return error
+    const message = error instanceof Error ? error.message : String(error)
+    return new Error(`browser-verify: ${context}: ${message}。${advice}`)
+  }
+
+  withScenario<T>(fn: (scenario: Scenario) => Promise<T>): Promise<T> {
+    this.ensureNotDisposed()
+    return this.chain(async () => {
+      this.ensureNotDisposed()
+      this.resetIdleTimer()
+      try {
+        return await fn(this.requireScenario())
+      } catch (error) {
+        throw this.wrapError(error, '场景操作失败', '请 browser_open 重开场景后重试。')
+      }
+    })
+  }
+
+  /** Open a fresh verification scenario; per design, each open = new context+page. */
+  async startScenario(reset: { url: string; waitSelector?: string; timeoutMs?: number; viewport?: { width: number; height: number }; deviceScaleFactor?: number; mocks?: Array<{ urlPattern: string; json: unknown; status?: number }> }): Promise<OpenScenarioResult> {
+    this.ensureNotDisposed()
+    return this.chain(async () => {
+      this.ensureNotDisposed()
+      this.resetIdleTimer()
+      return this.openScenario(reset)
+    })
+  }
+
+  private async openScenario(reset: { url: string; waitSelector?: string; timeoutMs?: number; viewport?: { width: number; height: number }; deviceScaleFactor?: number; mocks?: Array<{ urlPattern: string; json: unknown; status?: number }> }): Promise<OpenScenarioResult> {
+    const browser = await this.ensureBrowser()
+    await this.scenario?.close()
+    const context = await browser.newContext({
+      viewport: reset.viewport ?? this.opts.viewport ?? { width: 390, height: 844 },
+      deviceScaleFactor: reset.deviceScaleFactor ?? this.opts.deviceScaleFactor ?? 2,
+    })
+    const page = await context.newPage()
+    this.scenario = new Scenario(page, context)
+    this.resetIdleTimer()
+    try {
+      // Deviation D8-5: pre-register mocks before the first navigations so the
+      // app boots against mocked APIs (some apps bounce to a fallback route
+      // when real APIs answer "session invalid").
+      for (const rule of reset.mocks ?? []) {
+        await this.scenario.addMock({ ...rule, reload: false })
+      }
+      const opened = await this.scenario.navigate({
+        url: reset.url,
+        waitSelector: reset.waitSelector,
+        timeoutMs: reset.timeoutMs ?? this.opts.timeoutMs,
+      })
+      return {
+        ...opened,
+        browserKnown: this.discovered?.known ?? true,
+        versionHint: this.discovered?.versionHint ?? null,
+      }
+    } catch (error) {
+      await this.scenario.close()
+      this.scenario = null
+      throw this.wrapError(error, '打开页面失败', '请检查 URL 是否可访问、页面是否可在超时内加载，必要时调大 DSH_BROWSER_VERIFY_TIMEOUT。')
+    }
+  }
+
+  private resetIdleTimer(): void {
+    if (this.idleTimer !== null) clearTimeout(this.idleTimer)
+    this.idleTimer = setTimeout(() => { void this.dispose() }, this.opts.idleMs ?? 600000)
+  }
+
+  async ensureBrowser(): Promise<Browser> {
+    this.ensureNotDisposed()
+    if (this.browser !== null) return this.browser
+    try {
+      const found = (this.opts.discover ?? discoverBrowser)({ overridePath: process.env.DSH_BROWSER_VERIFY_CHROMIUM ?? undefined })
+      this.discovered = found
+      // Deviation D8-3: launchPersistentContext is the only launch path that
+      // puts our predictable temp dir on the chromium command line
+      // (`--user-data-dir` is appended by playwright itself), which the
+      // cleanup/zombie matchers and the smoke rely on.
+      const persistent = await chromium.launchPersistentContext(this.userDataDir, {
+        executablePath: found.executablePath,
+        args: buildLaunchArgs(found.kind === 'headless-shell'),
+        headless: true,
+      })
+      const browser = persistent.browser()
+      if (browser === null) throw new Error('browser-verify: 持久化上下文未返回浏览器实例。请检查 DSH_BROWSER_VERIFY_CHROMIUM 指向的浏览器，或重新执行 npx playwright install chromium。')
+      this.browser = browser
+    } catch (error) {
+      throw this.wrapError(error, '浏览器启动失败', '请检查 DSH_BROWSER_VERIFY_CHROMIUM 指向的浏览器路径，或重新执行 npx playwright install chromium。')
+    }
+    this.resetIdleTimer()
+    return this.browser
+  }
+
+  private requireScenario(): Scenario {
+    if (this.scenario === null) {
+      throw new Error('browser-verify: 尚未打开验证会话。请先调用 browser_open 打开页面。')
+    }
+    return this.scenario
+  }
+
+  /**
+   * Reset on dispose: mark disposed first (idempotent, blocks new ops), then
+   * run the teardown serialized on the FIFO chain so it waits out any
+   * in-flight op and cannot interleave with a launch or scenario op.
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    await this.chain(() => this.teardown())
+  }
+
+  /** Best-effort teardown: close scenario + browser, delete the profile dir. */
+  private async teardown(): Promise<void> {
+    if (this.idleTimer !== null) { clearTimeout(this.idleTimer); this.idleTimer = null }
+    const scenario = this.scenario
+    this.scenario = null
+    if (scenario !== null) { try { await scenario.close() } catch { /* ignore */ } }
+    const browser = this.browser
+    this.browser = null
+    if (browser !== null) {
+      try { await browser.close() } catch {
+        // Graceful close failed (hung process / dead transport; the persistent
+        // context path has no internal kill fallback). Hard-kill any process
+        // still carrying our user-data-dir so no orphan survives the teardown.
+        try { await this.hardKillChromium() } catch { /* ignore */ }
+      }
+    }
+    try { rmSync(join(tmpdir(), `dsh-browser-verify-${process.pid}`), { recursive: true, force: true }) } catch { /* ignore */ }
+  }
+
+  /**
+   * Hard-kill fallback: SIGKILL every process whose command line still
+   * carries our user-data-dir (playwright appends `--user-data-dir` itself;
+   * our predictable temp dir is the reverse-lookup key, per design §6).
+   */
+  private async hardKillChromium(): Promise<void> {
+    const out = await new Promise<string>((resolve) => {
+      exec('ps -Ao pid=,ppid=,command=', { maxBuffer: 10 * 1024 * 1024 }, (error, stdout) => resolve(error ? '' : stdout))
+    })
+    const marker = `--user-data-dir=${this.userDataDir}`
+    for (const line of out.split('\n')) {
+      const m = /^\s*(\d+)\s+\d+\s+(.+)$/.exec(line)
+      if (m === null) continue
+      if (m[2].includes(marker)) {
+        try { process.kill(Number(m[1]), 'SIGKILL') } catch { /* already gone */ }
+      }
+    }
+  }
+}