Skip to content

feat: external Chrome CDP host, Node runner and dual-host acceptance - #11

Merged
jiangkoumo merged 13 commits into
mainfrom
integration/p1-external-cdp
Oct 25, 2026
Merged

jiangkoumo merged 13 commits into
mainfrom
integration/p1-external-cdp

Conversation

@jiangkoumo

Copy link
Copy Markdown
Owner

Adds an external Chrome CDP host and a standalone Node runner, exposed through --cdp-endpoint, while preserving the default ego lite path. Both hosts share 12 controlled acceptance tasks. Tasks create their own targets, retain unrelated pages, stop on cancellation and verify final URL conditions.

Fixes #8
Fixes #9
Fixes #10

Validation on the integrated tree: CDP host 167/167, runner 104/104 (its standalone browser case is explicitly SKIP and covered by integration), CLI 15/15, ego lite 12/12, external Chrome 12/12 with no false successes. node bench/test-host-integration-live.mjs --suite passed with real jev-1.14.0 HN navigation, local form submission and the real Bash CLI, with connection release and Chrome process cleanup confirmed. Windows path 36/36, route trace 62/62, release consistency 20/20 and no external harness dependency 9/9 passed.

Limits: Wikipedia search is variable within five steps and remains optional; real CDP was tested on macOS only. The existing local skill-route check reports four official symlinks; no global settings were changed. No version/tag/Release change. Detailed evidence and recorded workflow deviations: docs/P1-PARALLEL-REPORT.md.

在普通 Node + 外部 Chrome 上复用引擎的默认 DOM 路径,为 CLI/runner 提供会等新文档
提交的 goto 入口。

- scripts/hosts/host-contract.mjs: Host Adapter 契约 v1(能力自述 + fail-closed 自检、
  错误码语义、导航/超时判据与引擎保持一致)
- scripts/hosts/cdp-host.mjs: 零依赖 CDP 宿主(Node 自带 WebSocket)。默认只新建自有
  target,close 只关自有页面/连接、从不关外部浏览器;evaluate/cdp/url/title/
  waitForLoadState/keyboard.press(Enter)/goto;取消后 page 方法立即失败、close 仍可清理;
  snapshot/ref 路径显式拒绝
- bench/test-cdp-host.mjs: 离线假 CDP 服务器协议测试(请求对应、事件路由、超时、取消、
  断连、close 归属、goto 提交判定、能力边界)+ 真实 Chrome 测试(evaluate、真实 CDP
  点击/输入、goto 同站跨站与失败导航、断连、页面归属与清理、引擎默认 DOM 路径端到端)
- docs/HOST-ADAPTER.md: 契约、能力边界、取消与归属语义、验证方式与未验证项

Fixes #8
评审发现 waitForLoadState 把未知 state 静默按 load 处理:误传 "commit" / "networkidle0" 会变成
一次真等待,调用方拿到的语义与它以为的不同。

- waitForLoadState 只接受 load / domcontentloaded;其他值在发任何探针之前抛
  HostCapabilityError(零 Runtime.evaluate),并把支持的状态名列在消息里
- 测试补:4 个非法状态名各断言「抛错 + 探针数为 0」、白名单常量、拒绝消息含支持清单;
  补结构推断正例(无 hostCapabilities 声明但方法齐全 → snapshotPath true),
  并修正原先自相矛盾的测试名(断言未改)
- docs:记录两条边界——导航被 supersede 未复现、不扩导航策略;单条命令默认 30s 兜底仍
  有界(等待类探针受等待预算约束,page.cdp/evaluate 可传 {timeoutMs} 收窄)

验证:node bench/test-cdp-host.mjs → exit 0(167 通过 / 0 失败 / 0 SKIP)

Refs #8
Add scripts/run-cdp-task.mjs: a plain-Node entry that drives the existing
engine against an external Chrome over CDP, plus its offline behaviour test
and usage doc. Engine exports, the shared Bash CLI, host adapter sources and
version metadata are untouched.

- exports runCdpTask(cfg, deps); CLI is `--config <file>`, logs to stderr and
  result JSON to stdout so it can be parsed directly
- consumes the existing CLI cfg fields (goal/url/until/texts/steps/cache/
  cacheFile/cacheContext/batch/visualFallback/deciderConfig/apiKey/baseUrl/
  fallbackBaseUrl/forceViewport/strictViewport/extractInstruction/
  extractSchema/extractionModel/routeFile/keepSpace) plus cdpEndpoint
- host adapter is imported lazily and can be overridden (cfg.hostModule,
  EGO_JEV_CDP_HOST, deps.connectCdpHost) for cross-worktree verification;
  navigation uses the adapter's goto only, no second navigation stack
- config/credential errors fail closed with exit 2/3 before any browser work;
  CDP mode rejects spaceId/keep
- deterministic `verified` (until re-checked on the final URL) is separate
  from model `done`; a missed until is never success (until_not_matched)
- cancellation stops new dispatch (gate in check), releases the connection in
  finally, keeps the page, and reports steps=null / outcomeUnknown instead of
  inferring progress from logs
- action records separate intent from dispatch evidence (true/false/null);
  partial batches stay dispatched=true + batchPartial even when later guarded
- EGO_HOST_ABORTED is host control stop unless this run's signal was aborted

Verified: node bench/test-cdp-runner.mjs -> 98 pass / 0 fail / 1 SKIP
(real external Chrome deferred to the adapter integration); real Chrome 156
cross-worktree run with the feat-8 adapter on Wikipedia reached /wiki/Jev
(exit 0, verified, targetClosed, browserClosed:false).

Fixes #9
…e step errors

Three confirmed review findings on the runner result contract:

1. `until` with no `goal` skipped the final-URL verification entirely, so a
   pure-extraction task could report success:true without any deterministic
   evidence. normalizeConfig now rejects it (exit 2) before the host adapter is
   loaded; docs and tests cover it.
2. `batchPartial` was true for `executedSubActions: []` (0 dispatched of N),
   which also forced `outcomeUnknown`. It now requires length > 0, so an empty
   batch reports dispatched=false / batchPartial=false / outcomeUnknown=false.
3. `result.error` was only ever populated by extraction (null otherwise) and
   `result.outcomeUnknown` ignored per-step evidence. error now falls back to
   the last real history error, and outcomeUnknown aggregates
   `actions[].outcomeUnknown` / `batchPartial`.

Verified: node bench/test-cdp-runner.mjs -> 104 pass / 0 fail / 1 SKIP;
node bench/test-no-bh-dependency.mjs -> 9 pass;
node bench/test-release-consistency.mjs -> 20 pass / 1 pre-existing failure
(worktree dir name, same baseline as before these changes).

Refs #9
首批 P1/P2 双宿主验收任务集(合成受控 DOM + 注入判定器,不冒充模型成功率):

- bench/host-acceptance/tasks.mjs:12 项任务(点击 / 链接导航 / 输入 / 搜索提交 /
  原生下拉 / 复选框 / 遮挡 / 陈旧 ref / 危险动作 / 控制停止 / 缺文本来源 / 批处理),
  每项都给出真实 DOM 或 URL 断言;fixture 的提交监听在 setup 里用 page.evaluate 安装。
- bench/host-acceptance/suite.mjs:runHostAcceptance(page, options) 复用同一引擎、
  同一输入与预算;包装 page 记录真实派发、注入控制停止并统计停止后的页面调用;
  taskPassed 与 engineGoalSuccess 分开统计,guard 任务不按 goal=false 计失败;
  超时可清 timer、关闸并停止整套验收,如实报告 notRun。
- bench/host-acceptance/run-ego.mjs:ego lite 入口(ASCII-only,经 stdin 执行,自建 TaskSpace
  并 finish({ keep: [] })),可 sed 覆盖引擎路径与任务子集。
- bench/host-acceptance/run-cdp.mjs:外部 Chrome 入口,按 connectCdpHost 契约调用适配器
  (--adapter/--engine 可指向其他 worktree),缺适配器显式 SKIP + exit 2,不伪装通过。
- docs/HOST-ACCEPTANCE.md:任务表、指标口径、退出码/SKIP、基线与本机未验证项。

Fixes #10
Copilot AI balanced review requested due to automatic review settings October 25, 2026 12:09

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@jiangkoumo
jiangkoumo merged commit 75a9ef8 into main Oct 25, 2026
1 check passed
@jiangkoumo
jiangkoumo deleted the integration/p1-external-cdp branch October 25, 2026 12:28
@jiangkoumo jiangkoumo mentioned this pull request Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants