Repository navigation
docs(adr): add ADR 0158 on overlay runtime-fetch grants - #9086
Conversation
E2E tests did not runE2E tests run automatically for pull requests authored by users with write access or higher. For other contributors, someone with write access must add the Reason: See E2E testing guide for details. |
PR Summary by QodoDocument bounded runtime-fetch grants for harness overlays
AI Description
Diagram
High-Level Assessment
Files changed (4)
|
Code Review by Qodo🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)
Great, no issues found!Qodo reviewed your code and found no material issues that require reviewTip of the day💡 Did you know, you can tweak Display settings with a live preview to see your comment before it ships |
|
🤖 Finished Review · ✅ Success · Started 7:57 PM UTC · Completed 8:05 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.77 |
Site previewPreview: https://b47d2e80-site.fullsend-ai.workers.dev Commit: |
|
<!-- fullsend:risk-assessment --> DetailsDocumentation-only PR adding ADR 0158 with no protected paths or security-sensitive changes, elevated to moderate risk by high commit churn and multi-author contention on existing architecture documentation. Previous run<!-- fullsend:risk-assessment --> DetailsDocumentation-only PR adding ADR 0158 with no protected paths or security-sensitive changes, elevated to moderate risk by high commit churn and multi-author contention on existing architecture documentation. |
|
Looks good to me Previous run<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOltdfQ== --> Looks good to me |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
waynesun09
left a comment
There was a problem hiding this comment.
ADR review: 0158, overlays may grant runtime fetch within the config-level allowlist
The direction is right: give the three fetch fields a merge rule, and bound an overlay's prefixes by the config-level list. I checked every code claim in the PR body against 04fc17ae2, and they all hold. I found no way around the prefix test: case, .. (including %2e%2e), an org/ vs org-evil/ mismatch, ports, userinfo, and a query or fragment in an entry all fail closed. The 0112 note is an annotation only, and 0158 doesn't collide with main or any open PR.
Requesting changes for item 1. Items 2 and 3 are medium. Details are in the inline comments.
Blocking
- Turning fetch on also enables a top-level list that was never checked. At fetch time, the service checks a URL only against the harness's own merged list (
fetchsvc/service.go:160). The config-level list isn't consulted. This ADR checks only the prefixes an overlay adds, and the top-level list is checked only when the harness has URL references (the gap the last Consequence names). An overlay that sets justallow_runtime_fetch: truetherefore enables fetch over a list the ADR never bounds.- Today this is hidden because any non-empty top-level list already starts the fetch service (#7155). Once that opt-in goes, the overlay switch becomes the way fetch turns on, and "bounded by the config-level allowlist" no longer holds for that run.
- Suggest adding to the Decision: "When a matching overlay turns fetch on, every prefix of the merged list must pass the same test." At minimum, extend the last Consequence to say the bound covers only the prefixes the overlay adds.
Medium
-
max_runtime_fetches"replaced" has no stated direction. An overlay can raise the cap up to ADR 0024's maximum, and nothing bounds that the way the allowlist bounds prefixes. An overlay meant to lower the cap for a narrower context does nothing whenever its condition doesn't match. Please say whether an overlay may raise the cap, only lower it (min), or both. Also say how several matching overlays combine: prefixes append in order, and the last cap set wins? -
Cross-field rules are checked only on the merged harness, so
lintand dispatch miss them. Prefixes are checked on every entry without an event, but the cross-field rules run after overlay resolution, and an overlay keyed on an event never matches there. Examples:- An overlay sets
allow_runtime_fetch: true, with no prefix in the overlay or at top level. max_runtime_fetchesis set at top level withallow_runtime_fetchonly in an overlay. Every context where the overlay doesn't match then fails, and dispatch skips the agent.
Suggest checking each overlay entry merged alone onto the top level, or adding a Consequence that these failures surface only in runs where the overlay matches.
- An overlay sets
Low
- An overlay
allow_runtime_fetch: falseis silently ignored. ADR 0112 drops false, zero and empty overlay values. "An overlay cannot turn fetch off" is right, but an author who writesfalseon a fork-PR overlay gets no error. Consider making afalseor empty value in an overlay a validation error. - Overlays in a
base:harness. Their prefixes are checked against the child's config list, butmergeBaseIntoChilddrops the fetch fields, so the grants never reach the child. A shared base can then break children whose config lacks the prefix, for no security gain. Either skip the allowlist check for base overlays, or name bases in Consequence 3. - Consequence 3 overstates where failures surface.
lockreturns early when its entry is current, so it fails only when it recomposes. Dispatch skips the agent with an error annotation, or falls back to the write-access gate, rather than failing. - Implicit opt-in. While #7155 remains, an overlay that only adds prefixes also starts the fetch service. One sentence would say so.
- Readability.
- Gloss "overlay", "
base:composition" and "config-level allowlist" on first use. - List the three merge rules as bullets.
- Split the "check runs on every overlay entry" sentence.
- Make Options two bullets.
- In
docs/architecture.md, change "inside the config-level allowlist" to "within".
- Gloss "overlay", "
Record the decision that a matching overlay may grant runtime fetch, with every prefix it adds bounded by the config-level allowlist, and annotate ADR 0112, docs/architecture.md and the harness field reference. Refs https://redhat.atlassian.net/browse/AISDLC-500. Signed-off-by: Tim Pouyer <tim.pouyer@gmail.com>
Land round 1: the doc edits the round's change needs. Signed-off-by: Tim Pouyer <tim.pouyer@gmail.com>
Land round 1: the doc edits the round's change needs. Signed-off-by: Tim Pouyer <tim.pouyer@gmail.com>
25861e2 to
466670b
Compare
|
🤖 Finished Review · ✅ Success · Started 12:48 PM UTC · Completed 12:57 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.89 |
Superseded by updated review
waynesun09
left a comment
There was a problem hiding this comment.
Approving at 466670b. All five findings from my review are addressed in the ADR text: an overlay that turns on fetch now makes the whole merged list, top level included, pass the config-level prefix test; the cap is replaced within ADR 0024's range with the last overlay winning; Consequence 3 says where each failure shows; false or an empty list fails the load; and a base's fetch fields stay in the base while its entries are still checked. The remaining top-level gap is named as separate work. 0158 is still free on main.
Summary
Adds ADR 0158: a matching overlay may grant runtime fetch (
allowed_remote_resources,allow_runtime_fetch,max_runtime_fetches), bounded by the config-level allowlist. It amends ADR 0112, whose Decision 1 lets an overlay set any field but leaves these three with no merge rule, becausebase:composition drops them.The decision, after review:
allow_runtime_fetch, every prefix of the merged list, top level included, must pass the same test, whether or not the harness has URL references.allow_runtime_fetch: falseor an emptyallowed_remote_resourcesfails validation.Docs only, no implementation, per
docs/contributing/adrs.md. The implementation is the AISDLC-445 work, which will stack on this PR and implement all four rules.Review of #8829 asked for this to be recorded as a decision rather than as an annotation on the accepted ADR.
Changes
docs/ADRs/0158-overlays-may-grant-runtime-fetch-within-the-config-allowlist.md: new ADR, status Accepted.docs/ADRs/0112-overlays-may-set-any-harness-field.md: an Amended by ADR 0158 note under Status, after the ADR 0151 note. A minor annotation; no other text changes.docs/architecture.md: one sentence in the overlays bullet, still marked "Decided, not yet implemented".docs/contributing/harness-fields.md: ADR 0158 added to the "Decided, not yet implemented" banner, beside ADR 0112, because the field tables there change when both are implemented. This edit goes beyond the three the issue lists.Numbering
The issue first named this ADR 0152. 0152 is now
0152-hook-interpreter-truston main, and open PRs #8969, #9024 and #9026 hold 0155–0157, so 0158 is the lowest number free on main and in open PRs.Evidence for claims about current behavior (at 04fc17a)
base:composition drops the three fetch fields. The "NOT merged from base" comment is atinternal/harness/compose.go:918, inmergeBaseIntoChild.docs/reference/harness-reference.md:507says the same.(*Harness).ValidateAllowedRemoteResources, atinternal/harness/harness.go:1067.run,lintandlock, and only when the harness has URL references. The checks are behindHasURLReferences()atinternal/cli/run.go:780,internal/cli/lint.go:344andinternal/cli/lock.go:335.shouldStartFetchServiceatinternal/cli/run.go:3274.[]stays empty. Seeconfig.EnsureDefaultAllowedRemoteResourcesatinternal/config/config.go:669.lockdoes not compose a harness whose lock entry is current. It returns atinternal/cli/lock.go:234.internal/fetchsvc/service.go:174.OverlayEntryholds onlywhenandForgeConfig(internal/harness/forge.go:38), andForgeConfighas no fetch fields.Scope notes
agent,agent_input,pluginsandapi_serversin the overlays of a URL-fetched harness is not part of this ADR. It is an implementation limitation documented in the field reference and removed by later work.allow_runtime_fetch, a harness's own top-level list is checked against the config-level list only byrun,lintandlock, and only when the harness has URL references.Overlapping open PRs
Checks
make lintpasses, including the ADR status, number and frontmatter linters and the markdown link check.go vetpasses too.hack/ci-local/ci-local go-testpasses.Jira: AISDLC-500