@mrclrchtr/supi-review 3.0.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +41 -20
  2. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  3. package/package.json +2 -2
  4. package/src/git-choices.ts +42 -0
  5. package/src/git-command.ts +172 -2
  6. package/src/git.ts +126 -291
  7. package/src/history/collect.ts +15 -6
  8. package/src/review-input.ts +36 -0
  9. package/src/review-limits.ts +12 -0
  10. package/src/review-path.ts +18 -12
  11. package/src/review-result.ts +26 -5
  12. package/src/review.ts +201 -76
  13. package/src/session/review-artifact-store.ts +97 -0
  14. package/src/session/review-plan-store.ts +93 -12
  15. package/src/target/change-metadata.ts +125 -0
  16. package/src/target/diff.ts +43 -0
  17. package/src/target/file-manifest.ts +40 -0
  18. package/src/target/packet.ts +17 -6
  19. package/src/target/resolve.ts +209 -0
  20. package/src/tool/agent-review-schemas.ts +21 -9
  21. package/src/tool/agent-review-tools.ts +66 -17
  22. package/src/tool/child-failure-diagnostics.ts +35 -0
  23. package/src/tool/child-lifecycle-trace.ts +27 -11
  24. package/src/tool/child-session-runner.ts +28 -11
  25. package/src/tool/child-usage.ts +73 -0
  26. package/src/tool/diagnostic-sanitizer.ts +35 -0
  27. package/src/tool/output-page.ts +26 -0
  28. package/src/tool/planner-runner.ts +28 -10
  29. package/src/tool/review-output-tool.ts +93 -0
  30. package/src/tool/review-runner.ts +9 -7
  31. package/src/tool/review-tools.ts +90 -12
  32. package/src/tool/review-workflow.ts +163 -83
  33. package/src/tool/schemas.ts +24 -5
  34. package/src/tool/session-lifecycle.ts +44 -54
  35. package/src/tool/usage-format.ts +15 -0
  36. package/src/tui/common.ts +58 -1
  37. package/src/tui/prepare.ts +57 -31
  38. package/src/tui/run.ts +13 -3
  39. package/src/types.ts +62 -19
package/src/tui/common.ts CHANGED
@@ -8,7 +8,10 @@
8
8
  import type { Theme } from "@earendil-works/pi-coding-agent";
9
9
  import { type Container, Spacer, Text } from "@earendil-works/pi-tui";
10
10
  import { formatEvidenceBadge } from "@mrclrchtr/supi-core/evidence-badge";
11
+ import { getChildDiagnosticErrorRows } from "../tool/child-failure-diagnostics.ts";
12
+ import { formatReviewUsage } from "../tool/usage-format.ts";
11
13
  import type {
14
+ ChildFailureDiagnostics,
12
15
  FindingEffort,
13
16
  FindingImpact,
14
17
  ReviewFinding,
@@ -118,6 +121,56 @@ function renderFinding(container: Container, finding: ReviewFinding, theme: Them
118
121
  container.addChild(new Spacer(1));
119
122
  }
120
123
 
124
+ /** Build a compact diagnostics section for non-completed (failed/canceled/timeout) task results. */
125
+ function buildNonCompletedSection(
126
+ container: Container,
127
+ result: ReviewTaskResult & { status: "failed" | "canceled" | "timeout" },
128
+ theme: Theme,
129
+ ): void {
130
+ const diagnostics: ChildFailureDiagnostics | undefined =
131
+ "diagnostics" in result ? result.diagnostics : undefined;
132
+ if (!diagnostics) return;
133
+
134
+ container.addChild(new Spacer(1));
135
+ container.addChild(
136
+ new Text(
137
+ theme.fg("dim", `${diagnostics.turns} turns · ${diagnostics.toolUses} tool uses`),
138
+ 1,
139
+ 0,
140
+ ),
141
+ );
142
+
143
+ if (diagnostics.lastAssistantStopReason) {
144
+ container.addChild(
145
+ new Text(
146
+ theme.fg(
147
+ diagnostics.lastAssistantStopReason === "error" ? "error" : "dim",
148
+ `Last assistant stop: ${diagnostics.lastAssistantStopReason}`,
149
+ ),
150
+ 1,
151
+ 0,
152
+ ),
153
+ );
154
+ }
155
+
156
+ const errors = getChildDiagnosticErrorRows(diagnostics);
157
+ for (const error of errors) {
158
+ container.addChild(new Text(theme.fg("error", `${error.label}: ${error.text}`), 1, 0));
159
+ }
160
+ if (errors.length === 0 && diagnostics.lastAssistantStopReason === "error") {
161
+ container.addChild(
162
+ new Text(
163
+ theme.fg(
164
+ "dim",
165
+ "The model produced an error with no further details — check provider quota, auth, or configuration.",
166
+ ),
167
+ 1,
168
+ 0,
169
+ ),
170
+ );
171
+ }
172
+ }
173
+
121
174
  /** Build an expanded-view section for a single review task result. */
122
175
  export function buildTaskSection(
123
176
  container: Container,
@@ -155,11 +208,15 @@ export function buildTaskSection(
155
208
  const metaParts = [
156
209
  theme.fg("dim", `model: ${result.modelId}`),
157
210
  theme.fg("dim", `hash: ${result.packetHash.slice(0, 12)}…`),
211
+ ...(result.usage ? [theme.fg("dim", formatReviewUsage(result.usage))] : []),
158
212
  ];
159
213
  container.addChild(new Text(metaParts.join(" "), 1, 0));
160
214
 
161
215
  // Completed task — show summary and findings
162
- if (result.status !== "completed") return;
216
+ if (result.status !== "completed") {
217
+ buildNonCompletedSection(container, result, theme);
218
+ return;
219
+ }
163
220
 
164
221
  if (result.summary) {
165
222
  container.addChild(new Spacer(1));
@@ -6,6 +6,7 @@
6
6
 
7
7
  import type { Theme } from "@earendil-works/pi-coding-agent";
8
8
  import { Container, Spacer, Text } from "@earendil-works/pi-tui";
9
+ import { formatReviewUsage } from "../tool/usage-format.ts";
9
10
  import type { PreparedReviewDetails } from "../types.ts";
10
11
  import { renderError, renderPartial, renderReviewToolCall } from "./common.ts";
11
12
 
@@ -59,7 +60,7 @@ export function renderPrepareResult(
59
60
  // ── Collapsed ────────────────────────────────────────────────────
60
61
 
61
62
  function buildCollapsed(details: PrepareDetails, theme: Theme): Text {
62
- const fileCount = details.snapshot.changedFiles.length;
63
+ const fileCount = details.snapshot.changes.length;
63
64
  const targetKind = details.snapshot.requestedTarget.kind;
64
65
  const hasPlanner = details.plannerDraft !== undefined;
65
66
 
@@ -67,15 +68,64 @@ function buildCollapsed(details: PrepareDetails, theme: Theme): Text {
67
68
  segments.push(theme.fg("accent", "Plan ready"));
68
69
  segments.push(theme.fg("muted", targetKind));
69
70
  segments.push(theme.fg("dim", `${fileCount} file${fileCount !== 1 ? "s" : ""} changed`));
70
- if (hasPlanner) {
71
- segments.push(theme.fg("muted", "with draft"));
72
- }
71
+ if (hasPlanner) segments.push(theme.fg("muted", "with draft"));
72
+ else if (details.plannerFailure) segments.push(theme.fg("warning", "planner unavailable"));
73
73
 
74
74
  return new Text(segments.join(` ${theme.fg("dim", "·")} `), 0, 0);
75
75
  }
76
76
 
77
77
  // ── Expanded ─────────────────────────────────────────────────────
78
78
 
79
+ function plannerFailureReason(details: PrepareDetails): string | undefined {
80
+ const failure = details.plannerFailure;
81
+ if (!failure) return undefined;
82
+ if (failure.kind === "failed") return failure.failureCode;
83
+ if (failure.kind === "timeout") return `timeout (${failure.timeoutMs} ms)`;
84
+ return failure.kind;
85
+ }
86
+
87
+ function addPlannerMetadata(container: Container, details: PrepareDetails, theme: Theme): void {
88
+ container.addChild(new Spacer(1));
89
+ container.addChild(new Text(theme.fg("dim", `Reviewer model: ${details.reviewerModelId}`), 1, 0));
90
+ if (details.plannerModelId) {
91
+ container.addChild(new Text(theme.fg("dim", `Planner model: ${details.plannerModelId}`), 1, 0));
92
+ }
93
+ if (details.plannerUsage) {
94
+ container.addChild(
95
+ new Text(theme.fg("dim", `Planner usage: ${formatReviewUsage(details.plannerUsage)}`), 1, 0),
96
+ );
97
+ }
98
+ const failure = plannerFailureReason(details);
99
+ if (failure) {
100
+ container.addChild(
101
+ new Text(
102
+ theme.fg("warning", `Planner unavailable (${failure}); use-review remains available.`),
103
+ 1,
104
+ 0,
105
+ ),
106
+ );
107
+ }
108
+ }
109
+
110
+ function addPlannerDraft(container: Container, details: PrepareDetails, theme: Theme): void {
111
+ const draft = details.plannerDraft;
112
+ if (!draft) return;
113
+ container.addChild(new Spacer(1));
114
+ container.addChild(new Text(theme.fg("accent", theme.bold("Planner Draft")), 1, 0));
115
+ if (draft.sharedContext) {
116
+ container.addChild(new Spacer(1));
117
+ container.addChild(new Text(theme.fg("muted", draft.sharedContext), 1, 0));
118
+ }
119
+ if (draft.tasks.length === 0) return;
120
+ container.addChild(new Spacer(1));
121
+ for (const task of draft.tasks) {
122
+ container.addChild(
123
+ new Text(`${theme.fg("accent", task.id)}: ${theme.fg("muted", task.instructions)}`, 1, 0),
124
+ );
125
+ container.addChild(new Text(theme.fg("dim", "─".repeat(40)), 1, 0));
126
+ }
127
+ }
128
+
79
129
  function buildExpanded(details: PrepareDetails, theme: Theme): Container {
80
130
  const container = new Container();
81
131
 
@@ -95,38 +145,14 @@ function buildExpanded(details: PrepareDetails, theme: Theme): Container {
95
145
  new Text(
96
146
  theme.fg(
97
147
  "dim",
98
- `${snapshot.changedFiles.length} file${snapshot.changedFiles.length !== 1 ? "s" : ""} changed · +${snapshot.stats.additions} / -${snapshot.stats.deletions}`,
148
+ `${snapshot.changes.length} file${snapshot.changes.length !== 1 ? "s" : ""} changed · +${snapshot.stats.additions} / -${snapshot.stats.deletions}`,
99
149
  ),
100
150
  1,
101
151
  0,
102
152
  ),
103
153
  );
104
154
 
105
- // Model info
106
- container.addChild(new Spacer(1));
107
- container.addChild(new Text(theme.fg("dim", `Reviewer model: ${details.reviewerModelId}`), 1, 0));
108
- if (details.plannerModelId) {
109
- container.addChild(new Text(theme.fg("dim", `Planner model: ${details.plannerModelId}`), 1, 0));
110
- }
111
-
112
- // Planner draft
113
- if (details.plannerDraft) {
114
- container.addChild(new Spacer(1));
115
- container.addChild(new Text(theme.fg("accent", theme.bold("Planner Draft")), 1, 0));
116
- if (details.plannerDraft.sharedContext) {
117
- container.addChild(new Spacer(1));
118
- container.addChild(new Text(theme.fg("muted", details.plannerDraft.sharedContext), 1, 0));
119
- }
120
- if (details.plannerDraft.tasks.length > 0) {
121
- container.addChild(new Spacer(1));
122
- for (const task of details.plannerDraft.tasks) {
123
- container.addChild(
124
- new Text(`${theme.fg("accent", task.id)}: ${theme.fg("muted", task.instructions)}`, 1, 0),
125
- );
126
- container.addChild(new Text(theme.fg("dim", "─".repeat(40)), 1, 0));
127
- }
128
- }
129
- }
130
-
155
+ addPlannerMetadata(container, details, theme);
156
+ addPlannerDraft(container, details, theme);
131
157
  return container;
132
158
  }
package/src/tui/run.ts CHANGED
@@ -6,6 +6,7 @@
6
6
 
7
7
  import type { Theme } from "@earendil-works/pi-coding-agent";
8
8
  import { Container, Spacer, Text } from "@earendil-works/pi-tui";
9
+ import { formatReviewUsage } from "../tool/usage-format.ts";
9
10
  import type { ReviewBatchDetails, ReviewTaskResult } from "../types.ts";
10
11
  import {
11
12
  buildTaskSection,
@@ -86,7 +87,7 @@ export function renderRunResult(
86
87
 
87
88
  function buildCollapsed(details: ReviewBatchDetails, theme: Theme): Container {
88
89
  const taskLines = details.results.map((r) => formatTaskCollapsed(r, theme));
89
- const fileCount = details.snapshot.changedFiles.length;
90
+ const fileCount = details.snapshot.changes.length;
90
91
 
91
92
  const container = new Container();
92
93
  // Per-task verdicts
@@ -113,7 +114,7 @@ function buildExpanded(details: ReviewBatchDetails, theme: Theme): Container {
113
114
  ? theme.fg("muted", "(planner-assisted)")
114
115
  : theme.fg("dim", "(caller-supplied)");
115
116
  container.addChild(
116
- new Text(`${theme.fg("accent", theme.bold("Review Complete"))} ${provenanceLabel}`, 1, 0),
117
+ new Text(`${theme.fg("accent", theme.bold("Review Finished"))} ${provenanceLabel}`, 1, 0),
117
118
  );
118
119
  container.addChild(new Spacer(1));
119
120
 
@@ -124,7 +125,7 @@ function buildExpanded(details: ReviewBatchDetails, theme: Theme): Container {
124
125
  container.addChild(
125
126
  new Text(`${theme.fg("dim", "target:")} ${theme.fg("muted", details.snapshot.title)}`, 1, 0),
126
127
  );
127
- const fileCount = details.snapshot.changedFiles.length;
128
+ const fileCount = details.snapshot.changes.length;
128
129
  container.addChild(
129
130
  new Text(
130
131
  theme.fg(
@@ -146,6 +147,15 @@ function buildExpanded(details: ReviewBatchDetails, theme: Theme): Container {
146
147
  0,
147
148
  ),
148
149
  );
150
+ if (details.planning.usage) {
151
+ container.addChild(
152
+ new Text(
153
+ theme.fg("dim", `planner usage: ${formatReviewUsage(details.planning.usage)}`),
154
+ 1,
155
+ 0,
156
+ ),
157
+ );
158
+ }
149
159
  }
150
160
 
151
161
  // Per-task sections
package/src/types.ts CHANGED
@@ -1,18 +1,26 @@
1
- import type { Model } from "@earendil-works/pi-ai";
1
+ import type { Model, Usage } from "@earendil-works/pi-ai";
2
2
  import type { ChildLifecycleTrace } from "./tool/child-lifecycle-trace.ts";
3
3
 
4
- /** A full hexadecimal Git commit object id supplied by an agent caller. */
4
+ /** A 7-64 character hexadecimal Git commit id, pinned to its full object id during resolution. */
5
5
  export type CommitId = string;
6
6
 
7
- /** The Git change selected for review. */
7
+ /**
8
+ * The Git change selected for review. A working-tree target may use an optional
9
+ * base commit to include committed branch work and current filesystem changes.
10
+ */
8
11
  export type ReviewTargetSpec =
9
- | { kind: "working-tree" }
12
+ | { kind: "working-tree"; baseCommit?: CommitId }
10
13
  | { kind: "comparison"; baseCommit: CommitId }
11
14
  | { kind: "commit"; commit: CommitId };
12
15
 
13
16
  /** Resolved identity of a selected review target. */
14
17
  export type ResolvedReviewTarget =
15
- | { kind: "working-tree"; headCommit: CommitId }
18
+ | {
19
+ kind: "working-tree";
20
+ headCommit: CommitId;
21
+ requestedBaseCommit?: CommitId;
22
+ mergeBaseCommit?: CommitId;
23
+ }
16
24
  | {
17
25
  kind: "comparison";
18
26
  requestedBaseCommit: CommitId;
@@ -27,17 +35,34 @@ export interface DiffStats {
27
35
  deletions: number;
28
36
  }
29
37
 
30
- /** Concrete target metadata and diff resolved before reviewer execution. */
38
+ /** One changed path with Git status and per-file line statistics. */
39
+ export interface ReviewChange {
40
+ /** Git name-status token, such as `M`, `A`, `D`, or `R100`. */
41
+ status: string;
42
+ /** Path on the target's after side, or the deleted path when no after-side path exists. */
43
+ path: string;
44
+ /** Before-side path for a detected rename or copy. */
45
+ previousPath?: string;
46
+ /** Null for binary changes. */
47
+ additions: number | null;
48
+ /** Null for binary changes. */
49
+ deletions: number | null;
50
+ }
51
+
52
+ /** Concrete target metadata and diff identity resolved before reviewer execution. */
31
53
  export interface ReviewSnapshot {
54
+ /** Canonical worktree root retained only inside the Review Engine. */
55
+ repositoryRoot: string;
32
56
  requestedTarget: ReviewTargetSpec;
33
57
  target: ResolvedReviewTarget;
34
58
  title: string;
35
- changedFiles: string[];
36
- diffText: string;
59
+ changes: ReviewChange[];
60
+ /** SHA-256 of the exact canonical target patch bytes. */
61
+ diffHash: string;
37
62
  stats: DiffStats;
38
63
  }
39
64
 
40
- export type ReviewSnapshotSummary = Omit<ReviewSnapshot, "diffText">;
65
+ export type ReviewSnapshotSummary = Omit<ReviewSnapshot, "repositoryRoot">;
41
66
 
42
67
  /** One independent caller-defined review objective. */
43
68
  export interface ReviewTask {
@@ -109,6 +134,10 @@ export interface ChildFailureDiagnostics {
109
134
  recentActivity?: string[];
110
135
  lastAssistantStopReason?: string;
111
136
  lastAssistantToolCalls?: string[];
137
+ /** Bounded, redacted canonical provider error from the last errored assistant message. */
138
+ lastAssistantErrorText?: string;
139
+ /** Bounded, redacted provider error from the most recent recovery lifecycle event. */
140
+ lastLifecycleErrorText?: string;
112
141
  }
113
142
 
114
143
  export type ChildFailedResult =
@@ -128,9 +157,6 @@ export interface ReviewProgress {
128
157
  cacheRead?: number;
129
158
  cacheWrite?: number;
130
159
  };
131
- toolCounts?: Record<string, number>;
132
- currentFocus?: { label: string; detail: string };
133
- elapsedMs?: number;
134
160
  }
135
161
 
136
162
  export interface PlannerInvocation {
@@ -143,10 +169,10 @@ export interface PlannerInvocation {
143
169
  }
144
170
 
145
171
  export type PlannerRunResult =
146
- | { kind: "success"; draft: PlannerDraft }
147
- | ({ kind: "failed" } & ChildFailedResult)
148
- | { kind: "canceled"; diagnostics: ChildFailureDiagnostics }
149
- | { kind: "timeout"; timeoutMs: number; diagnostics: ChildFailureDiagnostics };
172
+ | { kind: "success"; draft: PlannerDraft; usage?: Usage }
173
+ | ({ kind: "failed"; usage?: Usage } & ChildFailedResult)
174
+ | { kind: "canceled"; diagnostics: ChildFailureDiagnostics; usage?: Usage }
175
+ | { kind: "timeout"; timeoutMs: number; diagnostics: ChildFailureDiagnostics; usage?: Usage };
150
176
 
151
177
  export interface ReviewerInvocation {
152
178
  prompt: string;
@@ -159,14 +185,15 @@ export interface ReviewerInvocation {
159
185
  }
160
186
 
161
187
  export type ReviewerRunResult =
162
- | { kind: "success"; submission: ReviewSubmission; modelId: string }
163
- | ({ kind: "failed"; modelId: string } & ChildFailedResult)
164
- | { kind: "canceled"; modelId: string; diagnostics: ChildFailureDiagnostics }
188
+ | { kind: "success"; submission: ReviewSubmission; modelId: string; usage?: Usage }
189
+ | ({ kind: "failed"; modelId: string; usage?: Usage } & ChildFailedResult)
190
+ | { kind: "canceled"; modelId: string; diagnostics: ChildFailureDiagnostics; usage?: Usage }
165
191
  | {
166
192
  kind: "timeout";
167
193
  timeoutMs: number;
168
194
  modelId: string;
169
195
  diagnostics: ChildFailureDiagnostics;
196
+ usage?: Usage;
170
197
  };
171
198
 
172
199
  interface ReviewTaskResultIdentity {
@@ -174,6 +201,8 @@ interface ReviewTaskResultIdentity {
174
201
  modelId: string;
175
202
  /** SHA-256 of the exact reviewer packet bytes. */
176
203
  packetHash: string;
204
+ /** Aggregate nested-model usage for this task, when reported by the provider. */
205
+ usage?: Usage;
177
206
  }
178
207
 
179
208
  export type ReviewTaskResult = ReviewTaskResultIdentity &
@@ -203,11 +232,21 @@ export type ReviewTaskResult = ReviewTaskResultIdentity &
203
232
  export interface PlanningRecord {
204
233
  promptVersion: string;
205
234
  modelId: string;
235
+ /** Planner usage is informational here and is not charged again by the run tool. */
236
+ usage?: Usage;
206
237
  draft: PlannerDraft;
207
238
  effectiveReview: ReviewInput;
208
239
  decision: "accept-draft" | "use-review";
209
240
  }
210
241
 
242
+ /** Retrieval metadata for a bounded parent-facing review output page. */
243
+ export interface ReviewOutputReference {
244
+ artifactId: string;
245
+ offset: number;
246
+ nextOffset?: number;
247
+ totalCharacters: number;
248
+ }
249
+
211
250
  export interface ReviewBatchDetails {
212
251
  kind: "review-batch";
213
252
  mode: "direct" | "prepared";
@@ -216,6 +255,7 @@ export interface ReviewBatchDetails {
216
255
  review: ReviewInput;
217
256
  planning?: PlanningRecord;
218
257
  results: ReviewTaskResult[];
258
+ output?: ReviewOutputReference;
219
259
  }
220
260
 
221
261
  export interface PreparedReviewDetails {
@@ -226,6 +266,9 @@ export interface PreparedReviewDetails {
226
266
  plannerDraft?: PlannerDraft;
227
267
  plannerModelId?: string;
228
268
  plannerPromptVersion?: string;
269
+ plannerUsage?: Usage;
270
+ plannerFailure?: Exclude<PlannerRunResult, { kind: "success" }>;
271
+ output?: ReviewOutputReference;
229
272
  }
230
273
 
231
274
  export interface ReviewPacket {