gitea_admin/pragent
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(review): ADDITIONAL_CONTEXT_URL — repo-provided static context cached per review

Browse Source 
Long agent loops re-send the brief prefix on every step; cheap reusable
knowledge (architecture summary, module map, conventions, glossary) belongs
in a versioned file the maintainers control so the agent doesn't re-derive
it from the source tree on every PR. Two wiring paths, merged (env first):

* env var PRAGENT_ADDITIONAL_CONTEXT_URL — comma-separated, deployment-wide
* .pr-review.json:additional_context_urls — list[str], read from the PR's
  base branch (same trust boundary as the rest of the file)

Implementation:
* _parse_additional_context_env splits/dedupes/trims.
* _resolve_additional_context_urls(config) merges env (first) + config
  (then, skipping env-dupes); caps at 8.
* fetch_additional_context(urls) fetches each URL with urllib (5s timeout,
  http/https only — file://, javascript:, ftp:// rejected defensively),
  caches by URL in a module-level dict for the pod lifetime, truncates
  per-URL to 4k chars + total to 16k chars, best-effort (network errors
  are logged and skipped — never aborts the review).
* Result injected into build_user_prompt under "## Repo-provided context"
  between repo config and prior reviews. In the opencode engine it lands
  in .pragent/brief.md under its own section. The brief explicitly labels
  each block's CONTENT as untrusted (same as PR description) — section
  heading is trustworthy, body isn't.
* parse_repo_config accepts the field, caps at 8 entries, drops
  non-strings and empty strings.

Docs: pilot/README-webhook.md "Repo-provided static context" section —
env var + JSON example + Nexus raw-hosted recipe.

Tests: 14 new (208 total), covering env merging + dedup, scheme rejection,
per-URL cap, total cap, caching by URL, brief injection. All mock urllib
with a context-manager stand-in (no real network).

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Marcos
2026-08-20 17:45:51 +00:00
parent 998f793ec2
commit e8ebc54362
4 changed files with 428 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pilot/ai_review.py
+151 -2
View File
@@ -416,8 +416,9 @@ def build_user_prompt(
diff: str,
config: dict | None = None,
prior_reviews: list[str] | None = None,
additional_context: str = "",
) -> str:
"""Assemble the user prompt: repo config + prior reviews + PR meta + diff."""
"""Assemble the user prompt: repo config + additional context + prior reviews + PR meta + diff."""
parts: list[str] = []
eff = effective_config(config) if config else {}
@@ -448,6 +449,17 @@ def build_user_prompt(
if cfg_lines:
parts.append("## Repo review config (.pr-review.json)\n" + "\n".join(cfg_lines))
if additional_context:
# Repo-provided static background (architecture summary, module map,
# conventions, glossary, …). Cached for the review; the agent reads
# this ONCE per review and the prompt-cached prefix absorbs it on
# later steps — much cheaper than re-discovering the same facts from
# the source tree on every PR.
parts.append(
"## Repo-provided context (.pr-review.json:additional_context_urls "
"+ PRAGENT_ADDITIONAL_CONTEXT_URL — cached per review)\n" + additional_context
)
if prior_reviews:
joined = "\n\n---\n\n".join(prior_reviews)
if len(joined) > 4000:
@@ -1158,6 +1170,7 @@ def parse_repo_config(raw: str) -> dict:
require_tests bool — default: False
patterns {allow:[…], deny:[…]} — post-filter globs
cost_target <key of cost_model.PRICES> — see equivalent_cost
additional_context_urls list[str] (≤ 8) — see fetch_additional_context
"""
if not raw:
return {}
@@ -1219,6 +1232,19 @@ def parse_repo_config(raw: str) -> dict:
if isinstance(ct, str) and ct.strip():
out["cost_target"] = ct.strip()
acu = data.get("additional_context_urls")
if isinstance(acu, list):
urls: list[str] = []
for x in acu:
if isinstance(x, str):
u = x.strip()
if u:
urls.append(u)
if urls:
# Cap is also enforced later by _resolve_additional_context_urls;
# this just stops a 10k-entry file from making the config huge.
out["additional_context_urls"] = urls[:8]
return out
@@ -1436,6 +1462,124 @@ def gitea_post(api: str, repo: str, path: str, token: str, body: dict) -> tuple[
return _http("POST", f"{api}/api/v1/repos/{repo}/{path}", token, body)
# ---------------------------------------------------------------------------
# Additional context URLs — static repo-provided background fetched once
# per review and injected into the brief. The idea is the cheap reusable
# knowledge (architecture summary, module map, conventions, glossary, past
# incident write-ups, …) lives in a versioned file the maintainers control,
# so the agent doesn't have to re-read the source tree to rediscover it on
# every PR. Cached by URL for the lifetime of the process.
# ---------------------------------------------------------------------------
# Hard caps — these guard against a single repo-config entry pulling down a
# 2 MB doc and blowing the brief budget. Per-URL truncation keeps the worst
# case bounded; total truncation caps the sum across URLs.
_ADDITIONAL_CONTEXT_MAX_URLS = 8
_ADDITIONAL_CONTEXT_MAX_PER_URL_CHARS = 4000
_ADDITIONAL_CONTEXT_MAX_TOTAL_CHARS = 16_000
_ADDITIONAL_CONTEXT_TIMEOUT_S = 5
# Module-level cache, keyed by URL. The webhook server is a single Python
# process per pod and reviews happen sequentially, so this stays bounded.
_ADDITIONAL_CONTEXT_CACHE: dict[str, str] = {}
def _parse_additional_context_env(value: str) -> list[str]:
"""Comma-split an env var into a deduped, ordered URL list."""
if not value:
return []
seen: set[str] = set()
out: list[str] = []
for piece in value.split(","):
u = piece.strip()
if u and u not in seen:
seen.add(u)
out.append(u)
return out
def _resolve_additional_context_urls(config: dict | None) -> list[str]:
"""Merge the env var `PRAGENT_ADDITIONAL_CONTEXT_URL` with the per-repo
config field `additional_context_urls`. Env var wins on ordering — it
appears first so a one-off override can shadow a stale config entry."""
env = _parse_additional_context_env(os.environ.get("PRAGENT_ADDITIONAL_CONTEXT_URL", ""))
cfg_raw = (config or {}).get("additional_context_urls") or []
cfg: list[str] = []
if isinstance(cfg_raw, list):
for x in cfg_raw:
if isinstance(x, str):
u = x.strip()
if u and u not in set(env):
cfg.append(u)
merged = env + cfg
return merged[:_ADDITIONAL_CONTEXT_MAX_URLS]
def _fetch_one_additional_context(url: str) -> str | None:
"""Fetch a single URL. Returns the body (UTF-8, truncated) or None on
any failure — never raises; additional-context is best-effort.
Reject non-http(s) schemes defensively so a misconfigured `file://` or
`javascript:` URL cannot escape the pod. Cap per-URL size before parsing
to avoid a 50 MB response landing in memory.
"""
try:
parsed = urllib.parse.urlparse(url)
except ValueError:
return None
if parsed.scheme not in ("http", "https"):
return None
try:
req = urllib.request.Request(url, headers={"User-Agent": "pragent/1.0 (+context)"})
with urllib.request.urlopen(req, timeout=_ADDITIONAL_CONTEXT_TIMEOUT_S) as r:
raw = r.read(_ADDITIONAL_CONTEXT_MAX_PER_URL_CHARS + 1)
if len(raw) > _ADDITIONAL_CONTEXT_MAX_PER_URL_CHARS:
raw = raw[:_ADDITIONAL_CONTEXT_MAX_PER_URL_CHARS]
truncated = True
else:
truncated = False
body = raw.decode("utf-8", errors="replace")
except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError, ValueError):
return None
if truncated:
body += "\n…[truncated]"
return body
def fetch_additional_context(urls: list[str]) -> str:
"""Fetch a list of URLs, join into one string for the brief. Cached.
Empty when no URLs are given. Best-effort: a URL that errors is logged
to stderr and skipped — never aborts the review. Each fetched body is
truncated to `_ADDITIONAL_CONTEXT_MAX_PER_URL_CHARS` and the joined
output to `_ADDITIONAL_CONTEXT_MAX_TOTAL_CHARS`. Already-cached URLs
are not refetched.
"""
if not urls:
return ""
blocks: list[str] = []
total = 0
for url in urls:
if url in _ADDITIONAL_CONTEXT_CACHE:
body = _ADDITIONAL_CONTEXT_CACHE[url]
else:
body = _fetch_one_additional_context(url) or ""
_ADDITIONAL_CONTEXT_CACHE[url] = body
if not body:
continue
block = f"### {url}\n\n{body}"
if total + len(block) > _ADDITIONAL_CONTEXT_MAX_TOTAL_CHARS:
remaining = _ADDITIONAL_CONTEXT_MAX_TOTAL_CHARS - total
if remaining <= 80:
break
block = block[:remaining] + "\n…[truncated]"
blocks.append(block)
total = _ADDITIONAL_CONTEXT_MAX_TOTAL_CHARS
break
blocks.append(block)
total += len(block)
return "\n\n".join(blocks)
def fetch_pr_diff(api: str, repo: str, index: str, token: str, max_chars: int) -> tuple[str, bool, int]:
"""Get the unified diff. Try the `.diff` suffix first, fall back to the
files endpoint (join `patch` fields) if the server does not serve .diff."""
@@ -1657,6 +1801,10 @@ def review_pr(
engine = os.environ.get("PRAGENT_ENGINE", "opencode").strip().lower()
review_summary = ""
# Static repo-provided context (architecture summary, module map, …)
# fetched once from `additional_context_urls` (env + .pr-review.json).
# Cheap, cached, capped — see fetch_additional_context.
additional_context = fetch_additional_context(_resolve_additional_context_urls(config))
if engine == "opencode":
# The review "brain" runs on opencode: it gets the checked-out repo,
# the brief, and the pragent agent factory; returns stdout with a
@@ -1671,6 +1819,7 @@ def review_pr(
title=title, body=body, diff=diff, config=config,
prior_reviews=prior, model=oc_model,
compression_note=compression_note,
additional_context=additional_context,
)
review_summary, findings, summary_changes, risks = parse_review_output(stdout)
if not findings and not review_summary:
@@ -1690,7 +1839,7 @@ def review_pr(
model, sha, usage_section=usage_section))
return True
else:
user_prompt = build_user_prompt(title, body + compression_note, diff, config, prior)
user_prompt = build_user_prompt(title, body + compression_note, diff, config, prior, additional_context)
raw_findings = call_model(ollama_url, model, SYSTEM_PROMPT, user_prompt, max_tokens)
findings = parse_findings(raw_findings)
usage = None