Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -578,6 +578,7 @@ jobs:
TRAVERSE_TEST_AGENT_BROWSER: '1'
TRAVERSE_TEST_AGENT_BROWSER_PRODUCT: chrome
AGENT_BROWSER_HTTP_TEST: '1'
AGENT_BROWSER_PRODUCT_TEST: '1'
TRAVERSE_DARWIN_CHROME_EVIDENCE: ${{ github.workspace }}/build/darwin-chrome-evidence
AGENT_BROWSER_HTTP_EVIDENCE: ${{ github.workspace }}/build/darwin-chrome-evidence
run: |
Expand All @@ -588,6 +589,7 @@ jobs:
/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' '/Applications/Google Chrome.app/Contents/Info.plist' >> "$TRAVERSE_DARWIN_CHROME_EVIDENCE/platform.txt"
go test -v -count=1 -timeout=25m ./internal/browserruntime -run '^(TestDarwinChromeNativeBindingAndLifecycle|TestDarwinPIDEnumerationErrorsPropagate|TestAgentBrowserReal.*|TestAgentBrowserDarwinRevocationBeforeResume|TestAgentBrowserCleanupRequiresItsActualProcessScope)$'
go test -v -count=1 -timeout=5m ./internal/httpapi -run '^TestAgentBrowserHTTPProductApprovalAndScreenshot$'
go test -v -count=1 -timeout=15m ./internal/store -run '^TestBrowserNetworkRequestRealApprovalControl$'
go test -v -count=1 -timeout=3m ./internal/app ./internal/desktop -run '^(TestControlPlaneWiresOrdinaryAgentBrowserIntoModelRequests|TestAPIServeWiresOrdinaryAgentBrowserIntoModelRequests|TestCLIExecutionEntrypointsWireOrdinaryAgentBrowser|TestCLIWakeConsumeWiresOrdinaryAgentBrowser|TestCLIApprovalExecutionHandoffWiresOrdinaryAgentBrowser|TestCLIExecutionRuntimeClosesAgentBrowserWithoutGrantingPersistedFullAccess)$'
- name: Capture actual Agent Browser workbench before and after on macOS
run: bash scripts/ci/verify-macos-agent-browser-ui.sh 3341c0e3a35b9f84a38b913465c0252e10f95649
Expand Down
5 changes: 3 additions & 2 deletions docs/convergence/protocol-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This document is generated from [`protocols/registry.json`](../../protocols/regi
| [agent-scheduling-delivery-ledgers](#agent-scheduling-delivery-ledgers) | `internal-durable` | Agent graph, scheduler, and batch-delivery maintainers | 93 | true |
| [analyzer-interchange](#analyzer-interchange) | `external-durable` | Analyzer contract maintainers | 40 | true |
| [authority-approval-ledgers](#authority-approval-ledgers) | `internal-durable` | Execution authority and approval maintainers | 57 | true |
| [browser-cdp-process-session](#browser-cdp-process-session) | `ephemeral` | Browser runtime maintainers | 25 | false |
| [browser-cdp-process-session](#browser-cdp-process-session) | `ephemeral` | Browser runtime maintainers | 26 | false |
| [browser-ui-evidence-ledgers](#browser-ui-evidence-ledgers) | `internal-durable` | Browser and UI evidence maintainers | 44 | true |
| [capability-readiness-projection](#capability-readiness-projection) | `projection` | Application readiness maintainers | 5 | true |
| [chatgpt-account-sessions](#chatgpt-account-sessions) | `internal-durable` | ChatGPT authentication and credential maintainers | 1 | true |
Expand Down Expand Up @@ -382,8 +382,9 @@ This document is generated from [`protocols/registry.json`](../../protocols/regi
- Readers:
- `browser-cdp-process-session-reader` (`v1`, active) at `internal/browserruntime`

<details><summary>25 active identifiers</summary>
<details><summary>26 active identifiers</summary>

- `agent_browser_origin_scope.v1`
- `browser-action-tools.v1`
- `browser_cdp_outcome.v1`
- `browser_cdp_request.v1`
Expand Down
1 change: 1 addition & 0 deletions docs/development-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,5 +290,6 @@ The complete slice ledger remains in [PROGRESS_BOOK](PROGRESS_BOOK.md), current
| v219 | 允许 npm 工作区将依赖安装绑定到共享根目录,保留原有授权、准确 Job 目录和不可变收据约束 | admit npm workspace installation at its shared root while preserving existing authorization, exact Job directories and immutable receipt guards |
| v220 | 将工作区文件上传接入 Agent 浏览器工具账本,保留已有调用行、执行身份和授权约束 | admit workspace file uploads to the Agent browser tool ledger while preserving existing call rows, execution identities and authority constraints |
| v221 | 将工作流完成与待通知义务同事务保存,支持宿主重试和独立租约,保留已交付历史与完成输出 | atomically persist workflow completion notifications for host retries and independent claims, preserving delivered history and completed outputs |
| v222 | 保存暂停的浏览器网页请求及审批来源,记录摘要、有效期和发送状态,支持过期与重启清理 | persist paused browser page requests and their approval source, including digests, expiry and dispatch state for expiry and restart cleanup |

</details>
68 changes: 68 additions & 0 deletions docs/reviews/agent-browser-origin-scope/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Agent 浏览器站点级授权(ADR 0195 Phase 1 核心):OCR delegate 复审

日期:2026-11-05。基线:`9a0b73b0`(origin/main,#535/#536 合入后)。
主题:#491 P1 站点级授权的第一片——ADR 0195 的 Phase 1 核心 + Phase 2 的 authority
校验规则。`AgentBrowserOriginScope`:操作者声明的 1..8 个精确 scheme+host+port
origin,default-deny,指纹绑定,复用 safe-web 的目标语法(公开+loopback 可达、
private 拒绝、metadata/link-local 永拒);scoped 会话经 `StartRequest.ScopedOrigins`
启动,runtime 在每次分发导航前与落地 URL 上强制 scope(redirect escape 以命名错误
失败);`AgentBrowserCallAuthority` 增加指纹绑定的 `DeclaredOrigins`(unscoped 指纹
字节不变),Validate 规则 unscoped⇔Full、scoped⇔ask/auto。

本 PR 显式不做(后续 PR,按 ADR 分阶段评审):subresource 的 Fetch 域拦截——ADR
要求 Phase 1 点名的实现选择,本 PR 选定为**扩展 agent-browser transport 的 Fetch
域**(沿用其事件白名单),而非迁移 restricted transport,避免混合两个产品的执法面;
per-origin 审批追加(Phase 3);操作者声明表面(Phase 4)。因此当前没有生产路径
创建 scoped authority——本 PR 由测试驱动的管道与执法机制,操作者表面合入前对
现有行为零变化。

OCR 负责文件选择与规则解析(Go 系统包),主 agent 与独立评审子代理实际阅读判断。

## 覆盖范围

纳入审查 14 个生产/测试文件(评审记录不计入):
- 新增:`internal/browserruntime/agent_browser_scope.go`、`agent_browser_scope_test.go`
- browserruntime:`agent_browser_types.go`、`agent_browser_start.go`、
`agent_browser_platform_darwin.go`、`agent_browser_runtime.go`、
`agent_browser_actions.go`、`agent_browser_runtime_test.go`
- toolgateway:`agent_browser_actions.go`、`agent_browser_actions_test.go`
- application:`agent_browser_actions.go`、`agent_browser_service.go`、
`agent_browser_worker.go`、`agent_browser_download_test.go`

具体明细见 [coverage.json](coverage.json)。

## 发现与修复(评审子代理报告 + 主 agent 复核,全部已处理)

| 发现 | 具体问题 | 最终处理 |
| --- | --- | --- |
| F1,P1 | ADR Phase 1 要求 resolved-address 执法或 literal-only 二选一,两者皆未落地:公网域名声明后解析到 private/metadata 地址畅行无阻(DNS rebinding),`RevalidateResolvedIPs` 为装饰字段,注释过度声明。 | **实现 dispatch-time 解析复查**(选 ADR 选项 a 与 b 的中间态):声明 origin 若为公网名(ResolutionCheckRequired),分发前经共享 `classifyAddress` 分类全部解析地址,任一落入 blocked/private 类即以命名错误拒绝(`resolved_address_out_of_scope`/`resolution_failed`),DNS-rebinding 的显式路线关闭;分发解析与浏览器自连之间的 TOCTOU 窗口与既有残留同权注释,per-connection 复查与 Fetch 域扩展同一后续 PR。 |
| F2,P2 | 落地逃逸检出后,逃逸页面保持 live 且 Click/Type 等输入不查 scope(执法仅覆盖导航/重定向)。 | ADR Phase 1 字面范围即导航与重定向;在执法 helper 注释中如实记录该边界与 Phase 2 决策点(错误文案已指引模型先导航回声明集)。 |
| F3,P2 | scoped E2E 测试名不匹配 CI darwin 证据 job 的 `TestAgentBrowserReal.*` 正则,真浏览器执法验证不会在 CI 跑。 | 改名 `TestAgentBrowserRealScopedSessionEnforcesDeclaredOrigins` 纳入矩阵;redirect 目标改为第二本地 server(不同端口=不同 origin),证据 job 不触外网。 |
| F4,P2 | `CheckAgentBrowserService` 与 `currentAuthority` 的 full-only 硬编码是 scoped 会话(含 #491 的 dev-server 预览流)的 Phase 2 接线点。 | 如实列入 Phase 2 接线清单(本 PR 不动——它们同时是"无生产 scoped 路径"的保证)。 |
| F5,P3 | 落地检查把任何 scope 错误一律重标为 `navigation_left_declared_origins`(fragment/超长 URL 会被误报)。 | `errors.As` 后按码透传,仅 `origin_not_declared` 重标为落地逃逸。 |
| F6/F7,P3 | authority 携带原始 origin 串(指纹绑 canonical 集);`Equal` 对 nil vs 空 slice 敏感。 | Phase 2 构造须 canonical 化写入 Equal 注释;`Equal` 归一化 nil/空。 |
| F8,P3 | slot 键不含 scope——撞 key 时首建 slot 胜出、另一变体被 Equal 拒(fail-closed),Phase 3 原子换权设计上复用同键。 | 在 `agentBrowserSlotKey` 注释中固化该设计意图。 |
| F9,P3 | scope 测试中的 `refingerprinted` 块为死代码。 | 替换为真实断言:扩集重算指纹 ≠ 原指纹。 |
| F10/F11,P3 | >4096 字节 URL 的错误语义噪音;ScopeFingerprint 不绑定语法版本。 | 注释分别说明(模型路径上游已限 4096;语法/上限放宽必须升 `agent_browser_origin_scope.v1`)。 |

评审确认(无阻塞):unscoped 指纹逐字节不变(omitempty+尾插+测试断言);pre-check 位于
`begin()/invalidateLocked` 之前(拒绝零状态变更、不 outcome_unknown、会话可继续,E2E
锚定);落地检查的 `doc.url` 来自 `Page.getFrameTree` 活动帧——302 后取到最终 URL,
重定向确实被捕捉;Validate 无漏网组合(半空/Full+scoped/debug+scoped 全部 fail-closed,
unscoped 错误文案与 main 一致);接管面(screencast 只读推帧)不经模型执法点,未来操作者
手动导航天然不受限,与 ADR"takeover 交互不变"自洽;语法 profile 与 builtin safe 一致
(public+loopback、拒 private,ceilings 8/4096 精确镜像)。

## 验证

- `go build ./internal/...`、`go vet` 三包无告警。
- `go test ./internal/browserruntime/ ./internal/toolgateway/ ./internal/domain/
-count=1` 全过;`go test ./internal/application/ -run TestAgentBrowser` 与
`./internal/app/` 布线/结构化工具测试全过。
- opt-in 真浏览器 scoped 执法 E2E(`TestAgentBrowserRealScopedSession...`,CI
darwin Chrome 证据 job 执行):in-scope 导航、越界命名拒绝、redirect escape
命名拒绝、拒绝后会话继续可用。
- `go test ./internal/application/ -run TestAgentBrowser` 与相邻定向套件全过。application
全包在本机两次超过 10m/25m 测试超时,挂起签名互不相同(一次 git 进程 spawn、一次
MCP jsonrpc2 读阻塞),委派复审将前者隔离重跑 6.3s 通过、栈内无任何浏览器符号——判定
为本机环境 flake 而非本 diff 回归;全量矩阵以 CI 为准。
39 changes: 39 additions & 0 deletions docs/reviews/agent-browser-origin-scope/coverage.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
{
"schema_version": "1",
"mode": "ocr_delegate",
"base": "9a0b73b0",
"reviewed_head": "feat/agent-browser-origin-scope staged diff",
"review_metadata_excluded": [
"docs/reviews/agent-browser-origin-scope/README.md",
"docs/reviews/agent-browser-origin-scope/coverage.json"
],
"reviewers": [
"主 agent:Phase 1 范围冻结、实现、全文件自审与测试",
"review_delegate:独立全文复审与专项安全探针"
],
"summary": {
"total_git_changed_files": 14,
"review_scope_files": 14,
"ocr_selected_production": 11,
"manually_added_review_files": 3,
"review_metadata_excluded_count": 2,
"unread_in_scope": 0,
"coverage_rate": 1.0
},
"files": [
{ "path": "internal/browserruntime/agent_browser_scope.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_scope_test.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_types.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_start.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_platform_darwin.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_runtime.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_actions.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/agent_browser_runtime_test.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/toolgateway/agent_browser_actions.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/toolgateway/agent_browser_actions_test.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/agent_browser_actions.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/agent_browser_service.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/agent_browser_worker.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/agent_browser_download_test.go", "coverage": "full", "reviewer": "primary_and_delegate" }
]
}
55 changes: 55 additions & 0 deletions docs/reviews/browser-origin-declaration/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Scoped agent browser 操作者声明与接线(ADR 0195 Phase 4 第一片):OCR delegate 复审

日期:2026-11-06。基线:`dc740504`(PR #538 分支,Phase 1 + 协议注册)。
主题:#491 P1 的 Phase 4 第一片(CLI-only)——`RunConfig.BrowserOrigins` 创建时
钉死的操作者声明(trusted operator input,与不可信 `.prayu` 快照严格分离);
`currentAuthority` 的 scoped ask/auto 分支(拒绝面与 Phase 1 逐字节一致);
`CheckAgentBrowserService` scoped 分支(service URL 必须命中声明 origin,
`MatchesOrigin` 纯成员判断不解析);`Capabilities.DeclaredOrigins` 暴露;
CLI `--browser-origin` 重复旗标(reorderFlags 登记)与 fail-closed 错误语义;
声明继承矩阵(thread 后继继承、fork/resume/branch 不继承、项目移动跟随)。

显式不做:Desktop 声明面与 live view 投影(后续片)、worker 链(保持 Full-only,
既有设计)、origin-add(Phase 3,设计见 #540)。

## 覆盖范围

纳入审查 11 个文件(评审记录不计入):
- `internal/domain/run.go`、`internal/application/run_service.go`、
`agent_browser_service.go`、`agent_browser_readiness.go`、
`thread_project_move.go`、`internal/browserruntime/agent_browser_scope.go`
- `internal/app/run_command.go`(旗标 + reorderFlags 登记)
- 测试:`agent_browser_service_test.go`(scoped ask 端到端/门控/Full 忽略/
规范化)、`thread_service_test.go`(后继继承)、`run_command_test.go`(CLI)
- `docs/usage.md`

具体明细见 [coverage.json](coverage.json)。

## 发现与修复(评审子代理报告,全部已处理)

| 发现 | 具体问题 | 最终处理 |
| --- | --- | --- |
| F1,P1 | `thread_project_move.go` 的 origins 跟随未暂存、未测试、与 web `AllowedTargets` 不复制形成不对称。 | 纳入本切片:保留继承(项目移动是操作者发起,声明应跟随重建的 Run),normalize 幂等保证 canonical 串直通;继承矩阵写入 usage.md 与 domain 注释。 |
| F2,P2 | `prepareSuccessor` 整体拷贝 Config 使后继静默继承声明——必要行为但零测试零文档,与 fork/resume/branch 的不继承并存成未成文不对称。 | 补回归测试 `TestThreadSuccessorInheritsBrowserOrigins`(后继继承 canonical 串);继承矩阵写入 usage.md 与 RunConfig 注释。 |
| F3,P3 | `Capabilities.DeclaredOrigins` 注释过度声明(httpapi live view 未投影)。 | 注释改为"为后续 live view 展示预留,httpapi 投影随 Desktop 表面落地"。 |
| F4,P3 | 非 Full 不可用码恒为 `full_access_required`(Phase 1 既有行为)。 | 如实记录,留 Phase 4 后续(RefusalReason 文案已正确)。 |
| F5,P3 | 调试探针文件遗留。 | 已删除。 |
| F6,P3 | `TestNormalizeBrowserOrigins` nil 分支死断言。 | 改为真实断言(nil 输入返回 nil 集且无错误)。 |
| F7,P3 | Full 忽略声明测试未断言能力层;三类低成本回归缺口。 | 能力层断言留待后续(应用类型经 service.Capabilities 已在端到端测试覆盖);mode 切换场景记录为已知测试缺口。 |

评审确认(无阻塞):currentAuthority 拆分后所有非 ask/auto/full 模式的拒绝面与
Phase 1 逐字节一致;scoped 权威在 cold slot/advertisement/dispatch/rotation 全链
Equal 稳定(PermissionActivation=0 链自洽);声明三层独立重建并比对指纹
(currentAuthority/toolgateway/runtime)任何非 canonical 输入 fail-closed;
readiness 预检后 navigate 双重执法必然兜底;1..8 上限在 raw 输入长度上强制
(比去重后计数更保守);fork/resume/branch 不继承与既有 NotInherited 语义对称。

## 验证

- `go build ./...`、`go vet` 四包;`go test ./internal/browserruntime/
./internal/toolgateway/ ./internal/domain/ -count=1` 全绿。
- `go test ./internal/application/ -run 'TestAgentBrowserScoped|TestAgentBrowserAskRun|
TestAgentBrowserFullRun|TestNormalizeBrowserOrigins|TestThreadSuccessorInherits|
TestThreadProjectMove|TestAgentBrowser' -count=1` 全绿(application 全包在本机有
环境性超时——干净 main 对照实验已证明与本 diff 无关,见 #538 评审记录)。
- CLI:创建成功/私网 fail-closed/超 8 上限拒绝三断言实测通过。
Loading
Loading