@effect-agent/pr-review 0.1.0-beta.38 → 0.1.0-beta.39

package/NOTICE

@@ -1,5 +1,4 @@
-This package includes adaptations of the review instructions and numbered diff
-hunk presentation from PR-Agent:
+This package includes adaptations of the review instructions from PR-Agent:
 
 https://github.com/The-PR-Agent/pr-agent
 Pinned source: 9e6d6a5b40f9ce90bcc085466ba7a42c0837c37a

package/README.md

@@ -1,16 +1,33 @@
 # @effect-agent/pr-review
 
-A small, provider-neutral review agent. One bounded model run receives every admitted patch as
-numbered new and old hunks, reads immutable base or head source when needed, and returns findings
-through a required native completion Tool. There is no voting, candidate cache, private hypothesis
+A small, provider-neutral review agent. Bounded model runs receive admitted patches as
+literal unified diffs, read immutable base or head source when needed, record established
+findings with `record_finding`, and return findings through a required native completion Tool.
+There is no voting, candidate cache, private hypothesis
 handoff, or repository code execution.
 
-The reviewer traces changed entry points and boundaries through downstream consumers, guards,
-finite resources, transformations, effects, completion, and unchanged callees. A finding must have
-a supported trigger, concrete terminal failure, causative changed edge, reachable impact, and a
-cause-level repair checked against both a legitimate boundary input and excluded scope. Incremental
-findings must be introduced, exposed, or materially affected by the exact delta; unrelated old bugs
-and target-only changes remain out of scope, while explicit reverts remain reviewable.
+The native Agent `inputPrompt` projects each complete patch once, with literal newlines. It keeps
+file headers, hunk ranges, additions, deletions, context, and mode or rename metadata. It does not
+duplicate context into separate old/new views or JSON-escape the source for the model. The canonical
+`ReviewRequest` and finding validation retain the original patches. This reduces repeated input
+overhead without excluding changes; it does not guarantee a complete review within a spending cap.
+
+The reviewer assesses every supplied patch first. Source reads resolve concrete questions about
+plausible defects, such as a missing caller, guard, contract, or limit. It reuses supplied evidence
+and finishes when those questions are resolved; straightforward changes can finish without source
+tools. Reads prioritize implementation and owned boundary schemas over test examples, including
+the definitions needed to resolve the question rather than only a nearby call site.
+Findings explain a supported trigger, concrete impact, and needed correction. Changes that
+expose an unchanged downstream failure remain eligible. Incremental findings must arise from the
+exact delta; unrelated old bugs and target-only changes stay out of scope, while explicit reverts
+remain reviewable.
+Changes to collection membership, cardinality, or representation warrant checking affected
+consumer limits with a supported boundary input, including transformations and aggregation.
+New or moved resource acquisition warrants checking an early-failure sequence and its cleanup.
+Owned untrusted-input and model-output Schema boundaries must safely handle every admitted value,
+including adversarial values at the field and collection bounds.
+Novelty compares base and head with the same supported operation input, including when a
+previously failing helper becomes newly reachable.
 
 The result contains model findings with host-validated paths and line anchors, exact duplicate
 removal, aggregate usage, and optional host-priced cost. Unknown changed paths fail closed and
@@ -22,8 +39,53 @@ The reviewer does not resolve previous findings or declare a partial review safe
 to merge. GitHub history, credentials, diff collection, and publication belong to
 the host channel.
 
+Without host spending admission, the engine owns a cumulative 416,000-token stop policy and
+reserves 160,000 tokens for a final context and completion response. The model sees its current
+turn, tool, and token usage. Token, turn, or tool exhaustion permits one constrained completion
+through `submit_review`; it returns validated findings and accounted usage with
+`ReviewOutcome.exhausted` naming the limit. Hosts must
+treat that outcome as incomplete, even when it contains no findings. Measured usage can exceed a
+policy threshold before the engine observes it; this is not a provider-side spending cap.
+The usage ledger records research, compaction, and finalization without a second token limit that
+could abort delivery.
+
+An optional `costControl` reports the host's pre-request spending admission and provider usage.
+Supplying it replaces the cumulative token quota and completion reserve with that admission.
+Cached reads still contribute to usage diagnostics, but cannot force early token finalization.
+The 8-turn, 64-tool-call, 5-minute, and 128,000-token context bounds remain in force. A cost
+estimator alone does not disable the token quota. Capped hosts own model-visible spending feedback
+at their provider boundary; the generic turn/tool status is disabled for these runs. The Action
+counts its outgoing spending status before admission and keeps it outside the reusable cache prefix.
+With `costControl`, large requests run in sequential batches of at most 256,000 patch characters,
+preserving the host's file order and keeping each patch complete. Each batch has a fresh context
+and the same source service. All batches share the host ledger, turn and tool allowances, deadline,
+and 24-finding capacity. They stop on an incomplete result or exhaustion. `pendingPaths` identifies
+admitted patches never sent to a model, including a batch refused before paid inference. Hosts
+must disclose those paths as unreviewed. Without `costControl`, the reviewer retains one run and its
+cumulative token policy.
+When the host stops research for cost, the reviewer returns `exhausted: "cost"` and delivers
+recorded findings without requiring another paid call. Hosts must reserve the full possible charge
+before sending each request; the port itself does not enforce a cap. The
+[GitHub Action](../../action/README.md) supplies that implementation for its supported OpenAI models.
+`reservedCostMicrousd` reports the maximum additional charge for requests whose usage is still
+unknown, separately from the observed usage estimate.
+
+Recorded findings also survive a later expected execution or verification failure. Such a result
+has `incomplete: true`; hosts must not treat an empty or partial result as clearing the change.
+The model can also set `incomplete: true` in `submit_review` when it cannot finish assessing the
+supplied patches. That declaration preserves findings and becomes `ReviewOutcome.incomplete`
+even when no engine limit or provider failure occurred. Host-tracked `unreviewedPaths` remain
+disclosed separately and do not by themselves mark the admitted patches unfinished. An empty
+complete result is not proof that the repository is defect-free.
+With `costControl`, an accounted provider attempt also returns an incomplete outcome after an
+expected failure, even without findings, so hosts can publish its usage and outstanding charges.
+Otherwise failures without recorded findings remain typed. Defects and interruption still
+propagate, and these records belong to the current run's Scope, not persistent storage.
+The report retains recorded findings before adding newly submitted findings, removes exact
+duplicates, and marks coverage incomplete if the combined report exceeds 24 findings.
+
 ```ts
-const reviewer = makeReviewer({ model, guidance, estimateCostMicrousd });
+const reviewer = makeReviewer({ model, guidance, estimateCostMicrousd, costControl });
 const program = reviewer.review(request).pipe(Effect.provideService(ReviewRepository, repository));
 ```
 
@@ -36,5 +98,5 @@ access and does not cache review answers.
 `ReviewSource.fromText(request, text)` applies the shared line and character
 bounds after the host authorizes and reads a file.
 
-The numbered hunk presentation and portions of the review instructions are adapted from
+Portions of the review instructions are adapted from
 [PR-Agent](https://github.com/The-PR-Agent/pr-agent). See `NOTICE` for its MIT license attribution.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Context, Effect, Schema } from "effect";
-import { IdGenerator, RunCostEstimator } from "effect-agent";
+import { IdGenerator, RunCostEstimator, ThreadHistory } from "effect-agent";
 import { LanguageModel, Model, Tool, Toolkit } from "effect/unstable/ai";
 //#region src/repository.d.ts
 declare const ReadFileInput: Schema.Struct<{
@@ -91,38 +91,43 @@ declare const ReviewUsage_base: Schema.Class<ReviewUsage, Schema.Struct<{
   readonly cacheWriteInputTokens: Schema.Natural;
   readonly outputTokens: Schema.Natural;
   readonly estimatedCostMicrousd: Schema.optionalKey<Schema.Natural>;
+  /** Maximum additional charge for sent requests whose usage remains unknown. */
+  readonly reservedCostMicrousd: Schema.optionalKey<Schema.Natural>;
 }>, {}>;
 declare class ReviewUsage extends ReviewUsage_base {}
+declare const ReviewCostSnapshot_base: Schema.Class<ReviewCostSnapshot, Schema.Struct<{
+  readonly stopped: Schema.Boolean;
+  /** Admitted provider attempts, including failed or still-unmetered requests. */
+  readonly modelCalls: Schema.Natural;
+  readonly usage: typeof ReviewUsage;
+}>, {}>;
+/** Host accounting covers every provider attempt, including compaction and failed requests. */
+declare class ReviewCostSnapshot extends ReviewCostSnapshot_base {}
+/**
+ * A host must reserve the full possible charge before provider I/O. If admission
+ * stops, the reviewer delivers recorded findings without another model request.
+ * This port reports that decision; it does not enforce a spending limit itself.
+ * Supplying it replaces the cumulative token quota with the host's admission;
+ * per-context, turn, tool, and duration limits still apply. Accounted attempts
+ * return incomplete outcomes on expected failure, even without findings.
+ * Capped hosts own model-visible spending feedback at their provider boundary;
+ * the reviewer's generic turn/tool status is disabled for these runs.
+ */
+interface ReviewCostControl {
+  readonly snapshot: Effect.Effect<ReviewCostSnapshot>;
+}
 declare const ReviewOutcome_base: Schema.Class<ReviewOutcome, Schema.Struct<{
   readonly report: typeof ReviewReport;
   readonly turns: Schema.Natural;
   readonly usage: typeof ReviewUsage;
+  /** Admitted patches in batches that never started. These are not reviewed files. */
+  readonly pendingPaths: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+  /** A constrained final answer preserves findings but cannot establish complete coverage. */
+  readonly exhausted: Schema.optionalKey<Schema.Literals<readonly ["tokens", "tool-calls", "turns", "cost"]>>;
+  /** Unfinished coverage, reported by the model or caused by failure or the report capacity bound. */
+  readonly incomplete: Schema.optionalKey<Schema.Literal<true>>;
 }>, {}>;
 declare class ReviewOutcome extends ReviewOutcome_base {}
-declare const ReviewSubmission_base: Schema.Class<ReviewSubmission, Schema.Struct<{
-  readonly findings: Schema.$Array<Schema.Struct<{
-    readonly path: Schema.NonEmptyString;
-    readonly line: Schema.optionalKey<Schema.Int>;
-    readonly category: Schema.Literals<readonly ["correctness", "security", "concurrency", "performance", "resources", "reliability", "error-handling", "testing", "maintainability", "docs"]>;
-    readonly title: Schema.NonEmptyString;
-    readonly body: Schema.NonEmptyString;
-    readonly priority: Schema.Literals<readonly [0, 1, 2, 3]>;
-  }>>;
-}>, {}>;
-declare class ReviewSubmission extends ReviewSubmission_base {}
-declare const FormattedReviewRequest_base: Schema.Class<FormattedReviewRequest, Schema.Struct<{
-  readonly title: Schema.String;
-  readonly description: Schema.String;
-  readonly baseRevision: Schema.NonEmptyString;
-  readonly headRevision: Schema.NonEmptyString;
-  readonly scope: Schema.optionalKey<Schema.Literals<readonly ["full", "incremental"]>>;
-  readonly unreviewedPaths: Schema.$Array<Schema.NonEmptyString>;
-  readonly changes: Schema.$Array<Schema.Struct<{
-    readonly path: Schema.NonEmptyString;
-    readonly formattedDiff: Schema.NonEmptyString;
-  }>>;
-}>, {}>;
-declare class FormattedReviewRequest extends FormattedReviewRequest_base {}
 declare const ReviewVerificationError_base: Schema.Class<ReviewVerificationError, Schema.TaggedStruct<"ReviewVerificationError", {
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -132,37 +137,11 @@ interface ReviewerOptions<Provider, ModelProvides, ModelRequires> {
   readonly model: Model.Model<Provider, LanguageModel.LanguageModel | ModelProvides, ModelRequires>;
   readonly guidance?: string | undefined;
   readonly estimateCostMicrousd?: RunCostEstimator | undefined;
+  readonly costControl?: ReviewCostControl | undefined;
 }
-/** One bounded, source-backed review of the complete admitted delta. */
+/** A bounded review, with sequential patch batches when a shared spending ledger is supplied. */
 declare const makeReviewer: <Provider, ModelProvides, ModelRequires>(options: ReviewerOptions<Provider, ModelProvides, ModelRequires>) => {
-  readonly review: (request: ReviewRequest) => Effect.Effect<ReviewOutcome, ReviewVerificationError | import("effect-agent").AgentRuntimeFailure<import("effect-agent").RuntimeBinding<typeof FormattedReviewRequest, typeof ReviewSubmission, string, {
-    readonly find_files: Tool.Tool<"find_files", {
-      readonly parameters: Schema.Struct<{
-        readonly query: Schema.String;
-        readonly revision: Schema.Literals<readonly ["base", "head"]>;
-      }>;
-      readonly success: typeof ReviewFileList;
-      readonly failure: typeof ReviewContextError;
-      readonly failureMode: "return";
-    }, never>;
-    readonly read_file: Tool.Tool<"read_file", {
-      readonly parameters: Schema.Struct<{
-        readonly path: Schema.NonEmptyString;
-        readonly revision: Schema.Literals<readonly ["base", "head"]>;
-        readonly startLine: Schema.Int;
-        readonly lineCount: Schema.Int;
-      }>;
-      readonly success: typeof ReviewSource;
-      readonly failure: typeof ReviewContextError;
-      readonly failureMode: "return";
-    }, never>;
-    readonly submit_review: Tool.Tool<"submit_review", {
-      readonly parameters: typeof ReviewSubmission;
-      readonly success: Schema.Null;
-      readonly failure: Schema.Never;
-      readonly failureMode: "error";
-    }, never>;
-  }, Provider, ModelProvides, ModelRequires, never, never, undefined>, import("effect-agent").BudgetAdapterError | import("effect-agent").BudgetExceeded, never>, ReviewRepository | Exclude<Exclude<Exclude<ModelRequires, import("effect-agent").EngineProvidedToolServices>, Tool.Handler<"submit_review"> | IdGenerator | Tool.HandlersFor<{
+  readonly review: (request: ReviewRequest) => Effect.Effect<ReviewOutcome, import("effect-agent").AgentApprovalDenied | import("effect-agent").AgentApprovalPending | import("effect-agent").AgentChildPending | import("effect-agent").AgentInputError | import("effect-agent").AgentOutputError | import("effect-agent").AgentPolicyError | import("effect-agent").AgentToolAuthorizationDenied | import("effect/unstable/ai/AiError").AiError | import("effect-agent").BudgetAdapterError | import("effect-agent").BudgetExceeded | import("effect-agent").CompactionError | import("effect-agent").ContextBudgetError | import("effect-agent").ContextOverflowError | import("effect-agent").ModelProtocolError | ReviewVerificationError | import("effect-agent").ThreadHistoryError, ReviewRepository | Exclude<Exclude<Exclude<Exclude<(import("effect-agent").ModelServices extends ModelProvides | LanguageModel.LanguageModel | Model.ModelName | Model.ProviderName ? Model.Model<Provider, ModelProvides | LanguageModel.LanguageModel, ModelRequires> : never) extends (infer T) ? T extends (import("effect-agent").ModelServices extends ModelProvides | LanguageModel.LanguageModel | Model.ModelName | Model.ProviderName ? Model.Model<Provider, ModelProvides | LanguageModel.LanguageModel, ModelRequires> : never) ? T extends import("effect/Layer").Layer<infer _Provides, infer _Error, infer Services> ? Services : never : never : never, import("effect-agent").EngineProvidedToolServices>, Tool.Handler<"record_finding">>, Tool.Handler<"submit_review"> | IdGenerator | ThreadHistory | Tool.HandlersFor<{
     readonly find_files: Tool.Tool<"find_files", {
       readonly parameters: Schema.Struct<{
         readonly query: Schema.String;
@@ -186,5 +165,5 @@ declare const makeReviewer: <Provider, ModelProvides, ModelRequires>(options: Re
   }>>, import("effect/Scope").Scope>>;
 };
 //#endregion
-export { ReviewCategory, ReviewChange, ReviewContextError, ReviewFileList, ReviewFinding, ReviewOutcome, ReviewReport, ReviewRepository, ReviewRequest, ReviewSeverity, ReviewSource, ReviewUsage, ReviewVerificationError, ReviewerOptions, type RunCostEstimator, isCommentableLine, makeReviewer };
+export { ReviewCategory, ReviewChange, ReviewContextError, ReviewCostControl, ReviewCostSnapshot, ReviewFileList, ReviewFinding, ReviewOutcome, ReviewReport, ReviewRepository, ReviewRequest, ReviewSeverity, ReviewSource, ReviewUsage, ReviewVerificationError, ReviewerOptions, type RunCostEstimator, isCommentableLine, makeReviewer };
 //# sourceMappingURL=index.d.mts.map