Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 4 additions & 0 deletions configs/project-config.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ allowed_profiles: [code, review]
budget:
max_turns: 20
max_tool_calls: 10
browser_limits:
max_origins: 4
max_requests: 200
timeout_ms: 180000
exclude_paths:
- fixtures
- "secrets/**"
Expand Down
39 changes: 39 additions & 0 deletions configs/project-config.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,45 @@
}
}
},
"browser_limits": {
"type": "object",
"additionalProperties": false,
"description": "Operator-narrowed browser session budget. Zero or absent fields keep the builtin profile value; present values may only narrow it (a widening value fails when the browser session plan is built). At least one positive bound is required.",
"properties": {
"max_origins": {
"type": "integer",
"minimum": 0
},
"max_url_bytes": {
"type": "integer",
"minimum": 0
},
"max_requests": {
"type": "integer",
"minimum": 0
},
"max_response_bytes": {
"type": "integer",
"minimum": 0
},
"max_download_bytes": {
"type": "integer",
"minimum": 0
},
"timeout_ms": {
"type": "integer",
"minimum": 0
}
},
"anyOf": [
{ "required": ["max_origins"], "properties": { "max_origins": { "minimum": 1 } } },
{ "required": ["max_url_bytes"], "properties": { "max_url_bytes": { "minimum": 1 } } },
{ "required": ["max_requests"], "properties": { "max_requests": { "minimum": 1 } } },
{ "required": ["max_response_bytes"], "properties": { "max_response_bytes": { "minimum": 1 } } },
{ "required": ["max_download_bytes"], "properties": { "max_download_bytes": { "minimum": 1 } } },
{ "required": ["timeout_ms"], "properties": { "timeout_ms": { "minimum": 1 } } }
]
},
"exclude_paths": {
"description": "Pinned root-relative file-tool exclusions. Supports *, ?, character classes and whole ** segments; matching directories excludes descendants. Not an OS command sandbox.",
"type": "array",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,16 @@ resolve an explicitly approved target to private space, but cloud metadata, link
multicast, unspecified, and reserved address classes remain blocked. Literal-IP targets
must resolve to the identical address.

Operator narrowing adds optional `max_origins` and `max_url_bytes` to the target scope.
Zero/absent fields retain the builtin ceiling and keep existing v1 JSON and fingerprints
unchanged. Positive bounds cannot exceed the builtin ceiling and enter the scope digest;
construction, validation, navigation, redirects, and intercepted requests enforce them.
The URL byte bound covers both the supplied URL and its canonical form. A session plan
requires its scope bounds to match its effective limits. Older readers discard the new
fields and reject narrowed scopes on fingerprint mismatch; new readers accept existing
default scopes. Previously built plans with narrowed origin/URL limits but no matching
scope bounds must be rebuilt. The builtin profile descriptor and fingerprint stay fixed.

`browser_session_plan.v1` binds Session, Run, Workspace, fixed profile fingerprint, target
scope fingerprint, proxy endpoint, optional system credential reference, requested tooling,
isolation, evidence class, limits, backend class, and sorted launch blockers. Proxy URL
Expand Down
71 changes: 71 additions & 0 deletions docs/reviews/browser-limits-config/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# 浏览器会话预算的 .prayu 窄化:OCR delegate 复审

日期:2026-11-05。基线:`6a10b7c8`(origin/main,含 #519–#524 与其他会话对隔离区的改进)。
评审对象:PR 分支 Qiyuanqiii/browser-limits-config(单提交,9 文件 / 331 行)。
主题:#491 P2 的预算运维项(issue 问题 #7:"5 分钟 / 500 请求 / 8 origin 对'调一个
bug'不够")。`.prayu/config.yaml` 新增 `browser_limits` 段——操作者对 builtin profile
预算(8 origins / 4096B URL / 500 req / 8 MiB 响应 / 16 MiB 下载 / 300000 ms)的窄化:
零值/缺省字段保留 profile 值、至少一个正整数、只窄不宽(widen 在 session plan 构建
时以命名错误失败;恰等于 ceiling 合法为 no-op——与 budget.max_turns 的 strictly-lower
差异已注释锚定并有测试)。SessionPlan 新增 `limits_override`(进 plan 指纹),验证器
从 override+profile 重算期望 limits,篡改变宽即使重签指纹仍被拒(不可超越 builtin
ceiling 的不变量无条件成立,信任模型已注释)。

OCR 负责文件选择(`ocr delegate preview --from origin/main --to HEAD`:7 个可审生产
文件)与规则解析(Rule Group 1 system Go),主 agent 与独立评审子代理实际阅读判断。

## 覆盖范围

纳入审查 10 个(评审记录不计入):
- 生产代码(7 个,OCR 检出):`internal/browserruntime/plan.go`、
`internal/projectconfig/projectconfig.go`、`internal/application/browser_runtime.go`
(browserLimitsOverrideForRun 解码 helper + safe-web 接线)、
`internal/application/full_cdp_runtime_service.go` 与 `full_cdp_service.go`
(另两个调用方接线)、`configs/project-config.schema.json` + example.yaml。
- 测试(2 个,人工补入):`internal/browserruntime/plan_test.go`
(窄化矩阵/篡改拒绝/ProfileToken 不变性/等值 no-op)、
`internal/projectconfig/projectconfig_test.go`(TestBrowserLimitsValidateAndNarrowPassthrough)。
- 工作树中其他会话遗留的 gofmt 残留(dependency_wait.go、child_task_*.go 等)不在
本提交内,不在评审范围。

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

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

| 发现 | 具体问题 | 最终处理 |
| --- | --- | --- |
| F1,P3 | schema 自相矛盾:description 写 "zero/absent fields keep the profile value" 但字段 `minimum: 1` 拒绝 0;且缺 `minProperties: 1`(空对象过 schema 但被 Go 拒)。 | schema 改 `minimum: 0` + `minProperties: 1`,description 补"至少一个正整数、widen 在 plan 构建时失败",与 Go 语义对齐。 |
| F2,P3 | override 恰等于 profile ceiling 被静默接受为 no-op(`> base` 才拒),与 budget.max_turns 的 strictly-lower(`>=` 拒)语义不同,且无注释锚定与边界测试。 | 注释写明"等于 ceiling 合法且为 no-op"及理由(浏览器 ceiling 即 profile 本身,等值既不宽也不窄);补等值通过用例。 |
| F3,P3 | 指纹为无密钥 sha256:同时篡改 override+limits 并重签指纹可使 Validate 通过(回到 builtin ceiling);"篡改 override 变宽→拒绝"仅在超 profile 时成立。 | LimitsOverride 注释写明信任模型(篡改上限=builtin ceiling,不变量无条件成立;plan 仅在构建时同步验证,无不可信存储回读路径)。 |
| F4,P3 | usage.md 的 .prayu 章节声称 "Any widening attempt aborts Run creation",但 browser_limits 的 widening 在 plan 构建时才失败;且 browser_limits 未见于该章节。 | 章节补 browser_limits 语义(零值=保留、只窄化、ceiling 检查发生在 plan 构建)并修正表述(browser_limits 的 widening 在 plan 构建时以命名错误失败)。 |

评审确认(No blocking findings):ProfileLimits 6 字段全覆盖、builtin 三 profile 共享
严格为正的 baseLimits(无 base=0 边界);LimitsOverride 经 `json.Marshal` 整 plan 自动
入指纹;`Validate` 从 override+profile 重算 expectedLimits 并复验指纹/Token/isolation/
scope/backend;ProfileToken 不含预算(token 标识一次性 profile 目录身份,预算不影响
profile 内容,测试断言该不变性);执行侧消费窄化后的 session.Limits(cdp.go、
full_cdp_transport.go),LimitsOverride 仅为验证溯源;三个调用方统一经
browserLimitsOverrideForRun 解码(空/畸形/缺段 nil 回退 builtin ceiling 兜底);
projectconfig validate 镜像 budget 分支(负值/全零拒绝)、Narrow 透传、schema/example
一致;go test browserruntime+projectconfig 全过。

## 验证

- `gofmt -l` 无输出(改动包);`go vet` 三包无告警;`go build ./internal/...` 通过。
- `go test ./internal/browserruntime/ ./internal/projectconfig/ -count=1` 全过(窄化矩阵、
篡改拒绝、等值 no-op、ProfileToken 不变性、projectconfig 解析校验)。
- `go test -race ./internal/application/ -run "TestAgentBrowserUpload|
TestAgentBrowserDownload|TestBrowserHeaded|TestBrowserSessionLifetime"` 通过
(相邻浏览器功能无回归)。

## 复审附记(2026-11-05,第二轮)

独立复审发现 F2 的"最终处理"与代码不符:plan_test.go 此前只有"全零 override = no-op"
用例,恰等 profile ceiling 的通过分支没有任何测试锚定(上文覆盖范围里"等值 no-op"的
表述实际指全零用例,不准确)。F2 所述的注释锚定确实存在,本轮已补上恰等 ceiling 的
通过用例并断言其仍进入 plan 指纹。另按复审意见补两处:
`browserLimitsOverrideForRun` 对畸形 pinned 快照的静默回退改为 `slog.Warn` 留痕(快照
在 Run 创建时已 validate + 指纹固定,触发即存储损坏,但操作者窄化意图被静默忽略应可
观察);usage.md 补写作用面——browser_limits 只约束走 BuildSessionPlan 的会话面
(Safe Web 与两个 Full CDP 产品),agent-managed browser 工具链不在该预算内。
验证:`go test ./internal/browserruntime/ ./internal/projectconfig/ -count=1` 全过。
35 changes: 35 additions & 0 deletions docs/reviews/browser-limits-config/coverage.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"schema_version": "1",
"mode": "ocr_delegate",
"base": "6a10b7c8",
"reviewed_head": "HEAD",
"review_metadata_excluded": [
"docs/reviews/browser-limits-config/README.md",
"docs/reviews/browser-limits-config/coverage.json"
],
"reviewers": [
"主 agent:四层实现(plan 窄化+验证器、projectconfig、三调用方接线、schema/example)与测试",
"review_delegate:OCR delegate 规则检查(Rule Group 1 system Go)与独立全文复审,含指纹篡改信任模型与 schema/Go 语义一致性专项"
],
"summary": {
"total_git_changed_files": 11,
"review_scope_files": 10,
"ocr_selected_production": 7,
"manually_added_tests": 2,
"review_metadata_excluded_count": 2,
"unread_in_scope": 0,
"coverage_rate": 1.0
},
"files": [
{ "path": "internal/browserruntime/plan.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/projectconfig/projectconfig.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/browser_runtime.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/full_cdp_runtime_service.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/application/full_cdp_service.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "configs/project-config.schema.json", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "configs/project-config.example.yaml", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/browserruntime/plan_test.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "internal/projectconfig/projectconfig_test.go", "coverage": "full", "reviewer": "primary_and_delegate" },
{ "path": "docs/usage.md", "coverage": "full", "reviewer": "primary_and_delegate" }
]
}
2 changes: 1 addition & 1 deletion docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -1969,7 +1969,7 @@ cyberagent project-config validate <path-to-config.yaml>
cyberagent project-config show <path-to-config.yaml> --profile code --max-turns 100 --max-tool-calls 100
```

The file uses `project_config.v1` (JSON schema in `configs/project-config.schema.json`, example in `configs/project-config.example.yaml`). It is untrusted input: it can only reduce the operator/process/policy limits, never widen them. `budget.max_turns`/`budget.max_tool_calls` must be strictly lower than the requested ceiling; `allowed_profiles` may only shrink the set; `read_only: true` forbids write-capable profiles (`code`/`script`); `exclude_paths` are workspace-relative paths without escapes; `skill_suggestions` use the signed Skill identity contract (`name@version`); `test_command_id`/`format_command_id` may only reference registered Tool Gateway typed action IDs — never Shell text. Unknown fields, duplicate keys, type errors, YAML aliases/anchors, files over 64 KiB, nesting deeper than 32, more than 4096 nodes, symlinks/junctions/reparse points, and oversized path lists all fail closed. Any widening attempt aborts Run creation with the offending field named.
The file uses `project_config.v1` (JSON schema in `configs/project-config.schema.json`, example in `configs/project-config.example.yaml`). It is untrusted input: it can only reduce the operator/process/policy limits, never widen them. `budget.max_turns`/`budget.max_tool_calls` must be strictly lower than the requested ceiling; `allowed_profiles` may only shrink the set; `read_only: true` forbids write-capable profiles (`code`/`script`); `exclude_paths` are workspace-relative paths without escapes; `skill_suggestions` use the signed Skill identity contract (`name@version`); `test_command_id`/`format_command_id` may only reference registered Tool Gateway typed action IDs — never Shell text. `browser_limits` narrows the browser session budget (`max_origins`, `max_url_bytes`, `max_requests`, `max_response_bytes`, `max_download_bytes`, `timeout_ms`): zero or absent fields keep the builtin profile value, at least one positive bound is required, and widening values fail when the browser session plan is built (values equal to the profile ceiling are accepted as no-ops). The budget applies to the session-plan surfaces (Safe Web and the Full CDP products); the agent-managed browser tools run under their own runtime budget and are not affected by `browser_limits`. Unknown fields, duplicate keys, type errors, YAML aliases/anchors, files over 64 KiB, nesting deeper than 32, more than 4096 nodes, symlinks/junctions/reparse points, and oversized path lists all fail closed. Any widening attempt aborts Run creation with the offending field named (browser_limits widening aborts when the browser session plan is built).

At Run creation the normalized effective view and its SHA-256 fingerprint are pinned into the Run config snapshot; editing `.prayu/config.yaml` afterwards never changes a running Run.

Expand Down
35 changes: 35 additions & 0 deletions internal/application/browser_runtime.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,15 @@ package application
import (
"context"
"errors"
"log/slog"
"strings"
"time"

"cyberagent-workbench/internal/browserruntime"
"cyberagent-workbench/internal/domain"
"cyberagent-workbench/internal/idgen"
"cyberagent-workbench/internal/projectconfig"
"encoding/json"
)

// BrowserRuntimeStore supplies the durable browser launch preparation, review,
Expand Down Expand Up @@ -103,6 +106,37 @@ func (s *BrowserRuntimeService) LaunchUIEvidence(ctx context.Context,
return s.launch(ctx, request, true)
}

// browserLimitsOverrideForRun decodes the run's pinned project config and
// returns the operator-narrowed browser limits, if any. The stored snapshot is
// the marshaled projectconfig.Effective; a missing, malformed, or absent
// browser_limits section yields nil (keep the builtin profile limits).
func browserLimitsOverrideForRun(run domain.Run) *browserruntime.ProfileLimits {
if len(run.Config.ProjectConfig) == 0 {
return nil
}
var effective projectconfig.Effective
if json.Unmarshal(run.Config.ProjectConfig, &effective) != nil {
// The pinned snapshot was validated and fingerprint-bound at Run
// creation, so reaching this branch means stored state was corrupted.
// The builtin profile limits are the safe fallback, but the operator's
// narrowing intent silently disappearing deserves a record.
slog.Warn("browser limits override snapshot is malformed; using the builtin profile limits", "run_id", run.ID)
return nil
}
if effective.BrowserLimits == nil {
return nil
}
limits := effective.BrowserLimits
return &browserruntime.ProfileLimits{
MaxOrigins: limits.MaxOrigins,
MaxURLBytes: limits.MaxURLBytes,
MaxRequests: limits.MaxRequests,
MaxResponseBytes: limits.MaxResponseBytes,
MaxDownloadBytes: limits.MaxDownloadBytes,
TimeoutMS: limits.TimeoutMS,
}
}

func (s *BrowserRuntimeService) launch(ctx context.Context,
request BrowserRuntimeLaunchRequest, uiEvidence bool,
) (*BrowserRuntimeHandle, error) {
Expand Down Expand Up @@ -148,6 +182,7 @@ func (s *BrowserRuntimeService) launch(ctx context.Context,
session, err := browserruntime.BuildSessionPlan(browserruntime.NewSessionPlanRequest{
SessionID: run.SessionID, RunID: run.ID, WorkspaceID: mission.WorkspaceID,
ProfileID: browserruntime.ProfileSafeWeb, Targets: []string{request.Target},
LimitsOverride: browserLimitsOverrideForRun(run),
})
if err != nil {
return nil, err
Expand Down
1 change: 1 addition & 0 deletions internal/application/full_cdp_runtime_service.go
Original file line number Diff line number Diff line change
Expand Up @@ -490,6 +490,7 @@ func (s *FullCDPProductionService) openReservedEntry(ctx context.Context,
session, err := browserruntime.BuildSessionPlan(browserruntime.NewSessionPlanRequest{
SessionID: run.SessionID, RunID: run.ID, WorkspaceID: mission.WorkspaceID,
ProfileID: browserruntime.ProfileCTFLab, Targets: []string{request.Target},
LimitsOverride: browserLimitsOverrideForRun(run),
Features: browserruntime.FeatureRequest{InterceptRequests: true,
ModifyRequests: true, ReplayRequests: true, EditCookies: true},
})
Expand Down
1 change: 1 addition & 0 deletions internal/application/full_cdp_service.go
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@ func (s *FullCDPService) Open(ctx context.Context,
session, err := browserruntime.BuildSessionPlan(browserruntime.NewSessionPlanRequest{
SessionID: run.SessionID, RunID: run.ID, WorkspaceID: mission.WorkspaceID,
ProfileID: browserruntime.ProfileCTFLab, Targets: []string{request.Target},
LimitsOverride: browserLimitsOverrideForRun(run),
Features: browserruntime.FeatureRequest{
InterceptRequests: true, ModifyRequests: true,
ReplayRequests: true, EditCookies: true,
Expand Down
Loading
Loading