@effect-agent/pr-review 0.1.0-beta.11 → 0.1.0-beta.111

package/NOTICE

@@ -0,0 +1,26 @@
+This package includes adaptations of the review instructions from PR-Agent:
+
+https://github.com/The-PR-Agent/pr-agent
+Pinned source: 9e6d6a5b40f9ce90bcc085466ba7a42c0837c37a
+
+MIT License
+
+Copyright (c) 2026 The PR Agent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,178 +1,187 @@
 # @effect-agent/pr-review
 
-A bounded, fail-closed GitHub pull-request reviewer built on the effect-agent
-public surface. One read-only Agent reviews a pull request through typed
-ports; the host validates every finding anchor against the real diff and
-posts one review after the run settles.
-
-**Deployment class E (ephemeral).** One `AgentRuntime.run` per invocation, no
-durability claim, and review posting is never exactly-once: a failed or
-truncated run posts nothing.
-
-## Use
-
-```ts
-import { Effect, Layer } from "effect";
-import {
-  PrReview,
-  gitHubReviewLayers,
-  resolveReviewTarget,
-  makeOpenAiReviewModel,
-  openAiClientLayer,
-} from "@effect-agent/pr-review";
-
-const reviewer = PrReview.make({ model: makeOpenAiReviewModel() });
-
-const program = Effect.gen(function* () {
-  const target = yield* resolveReviewTarget({ repository: "acme/api", number: 123 });
-  return yield* reviewer
-    .run({ post: true })
-    .pipe(Effect.provide(Layer.merge(gitHubReviewLayers(target), openAiClientLayer)));
-});
-```
-
-The run's requirement channel keeps every real dependency visible: the
-`PullRequestSource` and `ReviewPublisher` ports, the provider client, and the
-handler Layer of any extra tool you add. Anthropic is equally supported
-(`makeAnthropicReviewModel`, `anthropicClientLayer`), and the factory accepts
-any Effect AI Model.
-
-## Adapt
-
-```ts
-const reviewer = PrReview.make({
-  model: makeAnthropicReviewModel("claude-sonnet-5"),
-  guidance: (mission) => [
-    "This is an Effect codebase. Flag naked Promises in public APIs.",
-    mission.changedFileCount > 50 ? "Large PR: prioritize breadth over nit depth." : "",
-  ],
-  ignore: ["**/*.lock", "dist/**"],
-  maxFindings: 10,
-  policy: { maxTurns: 20, maxToolCalls: 40, maxDuration: "10 minutes", toolConcurrency: 2 },
-  extraTools: [MyReadonlyTool], // must be annotated ToolExecutionClass "readonly"
-});
-```
-
-Every knob widens what goes INTO the review. What leaves it is not
-configurable: model output is untrusted input, so finding anchors are
-re-validated against the parsed unified diff (invalid ones are demoted into
-the review body with the reason named, never trusted), the findings bound is
-enforced host-side, and publication happens only through the
-`ReviewPublisher` port after the run settles. `PrReview.makeFanOut` builds
-the delegating variant — bounded per-unit child reviewers (S1 attached
-ephemeral delegation) merged under the same output contract and the same
-publication path; the shared `guidance` and `maxFindings` shape the
-coordinator's merge as well as the children.
-
-## What a posted review looks like
-
-The body opens with a host-derived callout tier — `[!CAUTION]` when any
-finding is blocking, `[!IMPORTANT]` for important findings, an ℹ️ blockquote
-for nits, `✅` for a clean approval — computed from the validated severities,
-never from model prose. Below the summary, non-anchored `concerns` (deletion
-plans, rollout sequencing, coverage gaps, scope questions — things with no
-diff line to point at) render as severity-tagged sections. The footer names
-the model binding, the observed token usage, and links to the workflow run;
-an invisible metadata comment pins the reviewed head commit so later readers
-know when line callouts have gone stale.
-
-## Swap a port
-
-Tools observe the pull request only through `PullRequestSource`; publication
-happens only through `ReviewPublisher`. Provide your own Layers to review
-anything diff-shaped or publish anywhere else — the GitHub REST adapters are
-one implementation, not the contract.
-
-## Test what you adapted
+A provider-neutral agent that reviews an exact base-to-head change using a complete change
+index, paged diffs, and immutable source tools. One conversation follows related behavior across
+files. There are no separate patch batches, candidate pipeline, voting, or repository execution.
+
+## Evidence and findings
+
+The initial prompt includes every admitted path and its character range in one literal diff
+artifact. Changes up to 32,000 characters are included directly. Larger changes use `read_diff`:
+start at offset zero and follow `nextOffset`, or select a file's start offset from the index.
+Pages contain at most 32,000 UTF-16 characters and can cross file boundaries or split lines.
+Original unified patches, hunk coordinates, deletions, renames, and mode metadata remain intact.
+
+`read_file` reads up to 200 lines and 20,000 characters at the exact base or head.
+`find_files` searches filenames. `search_code` searches literal, case-sensitive source text to
+find definitions, callers, consumers, and tests, including unchanged code. Its path filter is a
+filename substring; cursor zero starts the search. Each page scans twenty authorized files,
+returns up to five matching lines per file, and provides `nextCursor` for more files.
+`truncated` identifies omitted matching lines and `unreadablePaths` identifies failed reads.
+A partial or failed search cannot establish that a caller is absent.
+
+The reviewer starts with the promised consumer outcome and traces supported execution paths,
+including unchanged callers and consumers. It distinguishes missing promised behavior from
+optional feature expansion. Before recording a defect, it checks the
+strongest relevant guard, documented exception, or alternative interpretation and establishes
+why the supported trigger still causes concrete impact. It checks base/head causation, boundary
+values, cleanup, concurrency, and whether changed tests would detect the claimed failure.
+New features must satisfy their stated contracts, including validation, limits, isolation,
+and aggregation; a bypass can be a defect even when the old code also accepted that input.
+Unrelated old bugs, speculation, style, compiler diagnostics, and generic test requests are
+excluded. Incremental reviews limit new findings to their exact delta.
+
+The shared finding rubric, parent review procedure, and host-supplied repository policy are
+separate instructions. Policy findings identify the specific rule and applicable exceptions,
+citing instruction paths and lines when available. An explicitly reviewable architecture
+contract can warrant a finding without a runtime failure; its supplied severity takes precedence.
+
+`record_finding` is the only way to add findings to the report. The model is instructed to record
+each distinct root cause once and recover the saved ledger with `review_status` after `new_context`,
+without re-recording an issue with revised wording or severity. Counterevidence must be checked
+before recording because the ledger has no retraction or revision operation. `submit_review` is the
+required native completion tool and accepts only `blockedOn` and `resolutions` metadata.
+The host builds the final report directly from the ledger, so completion never rewrites or merges
+findings. Extra completion fields fail validation.
+
+The host validates changed paths and RIGHT-side line anchors, demotes invalid anchors to
+top-level findings, and removes only exact repeated records. Distinct defects at the same path
+and line remain separate. Up to 24 findings are retained, prioritizing blocking over important
+over minor findings. Overflow always marks the result incomplete, regardless of later completion.
+Finding paths, titles, and bodies retain their 512, 200, and 2,000-character bounds.
+
+## Coverage and limits
+
+Requests admit up to 1,000 distinct changed paths, 2,000,000 characters per patch, and 8,000,000
+patch characters overall. These are host input limits, separate from the model's working context.
+Source hosts can apply additional authorization and admission bounds.
+
+The host tracks diff ranges available to completed model requests. Merely issuing a read, repeating
+a page, skipping ahead, or failing a tool does not establish complete coverage. `pendingPaths`
+includes partially read files. `review_status` recovers saved findings and outstanding ranges;
+its optional cursor pages through the current pending list. While a range remains unread,
+`submit_review` returns a recoverable error with the next unread offset. The same run continues
+under its original budgets. A native budget stop preserves the pending paths and findings as
+incomplete; repeated completion refusals cannot restart the run or reset its allowance.
+Reading all ranges is necessary, but it does not prove that the model assessed every behavior.
+
+`review_status` also keeps a bounded investigation notebook for the lifetime of the review.
+Replace it with `notes: { text, expectedRevision }`; text is limited to 4,000 characters and
+stale revisions fail without overwriting newer notes. The response supplies the current text and
+revision. Notes preserve unresolved questions, exact evidence references, and next checks across
+rollover. They are model-authored context, never proof of coverage or a source of findings.
+Only the accepted-update count (`notesUpdates`) leaves the review; note text is not persisted in
+the outcome. Children cannot update the parent's notebook.
+
+Completion means a source-based assessment of the admitted changes and material supported
+hypotheses, not proof of correctness or an exhaustive audit of every dependency. The model can
+report `blockedOn` only for specific unavailable evidence, naming the affected behavior and its
+attempts to retrieve that evidence. It must still review the remaining patches. The bounded
+reason is retained in the outcome and summary, forces incompleteness, and prevents resolutions.
+Excluded artifacts, lack of live execution, and hypothetical uncertainty do not themselves
+block assessment of the admitted change.
+
+Every parent conversation has 128 model turns, 512 tool calls, four concurrent tools, and a five-minute deadline.
+The default `compaction: "rollover"` strategy uses a 48,000-token working context to bound
+context growth during large reviews. Hosts can select `compaction: "prune"`
+and an integer `contextTokenLimit` from 16,000 to 128,000. These settings do not widen host input
+admission or create new spending, turn, or tool allowances. Invalid options fail before model work.
+
+Native rollover starts a fresh window without a summarizer call. Its bounded recovery excerpt
+may omit unseen tool results, so undelivered diff pages remain unread and must be fetched again.
+Already delivered ranges and saved findings survive. Both strategies support calling `new_context`
+alone with a handoff; original instructions and the complete change index remain available.
+After rollover, the reviewer resumes unread offsets from `review_status`. Once every range has
+been delivered, it follows the remaining investigation notes with targeted reads instead of
+starting another complete diff sweep.
+
+Logs identify each successful diff read by character offsets, the first unread offset, and
+whether the whole page had already been delivered. Rollover logs count queued reads discarded
+before delivery. Navigation totals include successful reads, fully repeated reads, status calls,
+accepted note updates, pending paths, and emitted compactions. They contain no source or note text;
+repeated reads can be legitimate evidence checks and do not themselves establish wasted work.
+Failure logs retain the typed error category and specific policy limit. A duration stop is also
+identified as the five-minute deadline in the review summary.
+
+Every measured outcome includes `compactions`, an array of emitted native `CompactionPerformed`
+events containing only `kind`, `turn`, `tokensBeforeEstimate`, and `tokensAfterEstimate`.
+An empty array means no event was emitted; absence means the outcome supplied no measurement.
+The array is bounded to 512 entries and includes events retained before a typed failure. It does
+not expose source or handoff text, and events alone do not distinguish automatic from requested
+rollovers. Boundaries that fail before event emission are not counted.
+
+Without `costControl`, the engine applies a cumulative 416,000-token policy with a 160,000-token
+completion reserve. A host cost estimator alone does not disable it. With `costControl`, the
+host reserves the full possible charge before each provider call, replacing that token quota.
+The [GitHub Action](../../action/README.md) supplies spending admission for supported OpenAI models.
+Recorded findings survive a cost stop without requiring another paid call. `reservedCostMicrousd`
+reports maximum additional charges for sent requests whose usage remains unknown.
+
+Token, turn, tool, or cost exhaustion is incomplete. Expected failures preserve recorded findings
+and completed model attempts, including their accounting when no finding was recorded. Context/input-token
+refusals return an incomplete token-exhausted outcome before paid inference when possible.
+Failures before any model attempt, finding, or budget refusal remain typed. Defects and interruption propagate, and every
+resource belongs to the review's Scope. Excluded host `unreviewedPaths` remain separately disclosed.
+An empty result never proves that the repository is defect-free.
+
+## Optional research children
+
+The default reviewer runs alone. Experiments can provide `research: { model, concurrency: 2 }`
+to expose native `delegate_research`. Concurrency is either one or two (default two), with at
+most two children established per review. Each child has six ordinary model turns, twelve tool
+calls, a 60-second deadline, and a 32,000-token context using native pruning. The runtime can
+reserve a final completion response after structural exhaustion. The host configures the child
+model's output limit; the eval uses 4,000 tokens.
+
+A delegation supplies one unresolved, falsifiable question whose answer could change a finding,
+and one to three distinct admitted changed paths. Instructions ask neutrally for supporting or
+refuting evidence and discourage generic second reviews; children use the same finding rubric.
+The host selects their exact patches, rejecting more than 32,000 total patch characters.
+Children receive the immutable revisions and current saved findings, and can use only the
+three repository read tools, `record_finding`, and `finish_research`. The completion contains
+an evidence summary and incomplete flag; findings go directly to the same canonical ledger.
+Children cannot delegate further, establish parent diff coverage, or resolve prior reviews.
+
+Native reservations and child fibers belong to the review's Scope. Child compaction cannot
+change the parent's unread ranges. Child model requirements remain visible in the review's
+Effect requirements, and usage contributes to the existing accounting. A host supplying
+`costControl` must use the same admission service for both model layers, so all requests draw
+from one spending cap. Without host admission, the parent and child native token policies are
+separate; the parent token quota is not a combined spending cap.
+
+Research-enabled runs break equal-severity finding ties by their complete serialized values
+before retaining 24, so child completion order cannot select the survivors. Exact duplicates
+are still the only records removed. A rejected delegation, failed or interrupted child,
+unfinished join, child-reported incomplete result, or child budget exhaustion makes the parent
+incomplete and suppresses resolutions. Defects and external interruption still propagate.
+
+Measured outcomes include `research` counters: `delegations` counts declared delegation calls;
+`started`, `completed`, `failed`, and `interrupted` count emitted native child events; `incomplete`
+counts completed child results that report incomplete or exhausted work. Zero counts are measured
+zero, while an absent field means no measurement was supplied. Counts contain no child source,
+summary, or transcript; prestart refusals have a declaration but no child event.
+
+## Follow-ups and hosting
+
+Hosts can supply up to eight prior `ReviewFollowUp` values, each up to 32,000 characters. The
+reviewer verifies every blocker in a follow-up against current source before returning its exact
+ID and fixing evidence. Unknown or duplicate resolution IDs fail verification. Incomplete,
+exhausted, pending-path, or excluded-path results return no resolutions. History selection,
+credentials, dismissal authorization, and publication belong to the host.
 
 ```ts
-import {
-  fixturePullRequestSourceLayer,
-  collectingReviewPublisherLayer,
-  makeOfflineReviewerModel,
-  makePromptKeyedModel,
-} from "@effect-agent/pr-review/testing";
+const reviewer = makeReviewer({ model, guidance, costControl });
+const program = reviewer.review(request).pipe(Effect.provideService(ReviewRepository, repository));
 ```
 
-Deterministic in-memory adapters for both ports plus prompt-keyed scripted
-models that walk the real tool surface — no network, no credentials, every
-ordinary gate.
-
-## Incremental Action reviews
-
-A completely covered posted Action review carries bounded, versioned,
-HMAC-authenticated continuity state:
-the exact PR/base/head lineage, profile and accepted-scope fingerprints, and
-the still-unresolved findings and concerns. A later Action run validates the
-state and reviews the GitHub comparison from that reviewed head to the
-current head, not the complete base...HEAD diff. Unchanged accepted scope is
-not sent back to the model; unchanged unresolved findings remain active;
-changed or reverted paths invalidate their prior findings. Non-anchored
-concerns are carried conservatively until a full audit because they cannot be
-mapped safely to one path.
-
-The state marker must be terminal, signed with the configured stable
-`PR_REVIEW_STATE_SECRET`, authored by the configured review-posting bot, and
-pinned to the reviewed commit. The expected author defaults to
-`github-actions[bot]`; set `PR_REVIEW_AUTHOR_LOGIN` (or the Action's
-`review-author` input) to `<app-slug>[bot]` when posting with a custom GitHub
-App token. State lookup, authentication, schema, identity, ancestry, profile,
-and comparison checks are fail-closed for scope selection: missing, stale,
-incompatible, or truncated state/comparisons produce a visible full-diff
-fallback. An ancestor base advance remains incremental and adds overlapping
-PR paths as affected context; a materially changed base lineage falls back to
-full. Re-running the same covered head skips model execution by default while
-preserving its stored blocking/success conclusion.
-
-After a new state-bearing Action review posts, prior marker-bearing bot reviews
-are retired by default: their bodies become collapsed, superseded history,
-resolved findings are struck through, and matching inline comments are
-minimized as outdated. Only strictly older reviews from the same GitHub actor
-are eligible, so copied markers and newer concurrent reviews are untouched.
-The machine-state comments remain byte-identical and terminal, so an edited
-body still participates in incremental state recovery.
-This cosmetic pass is fail-open and can be disabled with the Action input
-`retire-stale-reviews: "false"`.
-
-Authentication is an explicit Effect service supplied by the Action host;
-WebCrypto import/sign/verify failures stay typed. The terminal marker is
-schema-branded and capped at 24,000 characters. If signing fails or state
-exceeds that bound, the completed review is posted without continuity state
-and with a bounded warning, so the next run safely performs a full review.
-
-`review-mode: final` is the explicit bounded merge-readiness audit. It reviews
-the full current PR diff and resets the incremental baseline; normal
-`synchronize` events use `incremental` and do not perform this audit.
-
-## Hosts
-
-- **GitHub Actions**: the repository ships a prebuilt node-runtime action
-  supporting a committed review-profile document via `guidance-file` (this
-  repository's own profile lives at `.github/review-guidance.md`)
-  (`action/` at the repo root) — `uses` it with an API-key secret and nothing
-  else. For custom reviewers in CI, `@effect-agent/pr-review/action` exports
-  `runReviewAction` (event resolution, typed draft/non-PR skips, bounded range
-  selection, step outputs, and conservative check gate) to harness your own
-  `reviewer.run`.
-- **CLI**: `bun src/cli.ts --repo owner/name --pr 123 [--post] [--provider anthropic] [--fan-out]`
-  (also exported as the `./cli` entry).
-
-Environment: `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` for the model,
-`PR_REVIEW_STATE_SECRET` to authenticate incremental state,
-`PR_REVIEW_AUTHOR_LOGIN` to match a custom review-posting bot (defaults to
-`github-actions[bot]`),
-`GITHUB_TOKEN` to post (optional for public-repository reads), and the
-standard `GITHUB_REPOSITORY` / `GITHUB_EVENT_PATH` / `GITHUB_API_URL`
-variables inside Actions.
-
-## Bounds, spelled out
-
-Finite `AgentPolicy` on every definition plus run-level `UsageBudgetLimits`
-(tokens, tool calls, cost, duration). Reading a file head version beyond 200k
-characters is refused typed. The changeset surface is bounded at 300 files:
-files beyond the bound are not fetched, and the review body reports
-`Reviewed N of M changed files` instead of claiming completeness. Fan-out
-capacity overflow is reported in the review summary, never dropped. Any
-blocking active finding fails the Action check. Any required-file coverage
-gap — undiffable/unassigned paths, failed units (including policy exhaustion),
-truncation, or coordinator/run failure — is non-success rather than green.
+`ReviewRepository` implementations provide typed Effect operations for `readFile`, `findFiles`,
+and `searchCode`. Hosts authorize source sent to models, pin immutable revisions, enforce read
+bounds, and treat all source and model output as untrusted. The reviewer has no ambient filesystem
+or network access. `ReviewSource.fromText` applies the shared source-range bounds.
+
+The navigable diff approach is informed by [Pullfrog's review workflow](https://github.com/pullfrog/pullfrog/blob/0212dedb0f92b8ba4020c17dc30d3eced32415d7/modes.ts)
+and [Codex's review task](https://github.com/openai/codex/blob/588b781ab4924ce7352488394028e63d74cf807f/codex-rs/core/src/tasks/review.rs).
+These designs do not establish accuracy. The [eval bench](../../tooling/pr-review-eval/README.md)
+measures first-trial detection, false positives, and incomplete runs against adjudicated cases.
+Portions of the original review instructions were adapted from
+[PR-Agent](https://github.com/The-PR-Agent/pr-agent); see `NOTICE` for its MIT attribution.