@mrclrchtr/supi-review 3.1.0 → 4.0.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 (47) hide show
  1. package/README.md +41 -20
  2. package/node_modules/@mrclrchtr/supi-core/package.json +2 -4
  3. package/node_modules/@mrclrchtr/supi-core/src/api.ts +0 -4
  4. package/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts +3 -2
  5. package/node_modules/@mrclrchtr/supi-core/src/index.ts +0 -4
  6. package/node_modules/@mrclrchtr/supi-core/src/llm.ts +0 -10
  7. package/node_modules/@mrclrchtr/supi-core/src/path-utils.ts +19 -15
  8. package/package.json +2 -2
  9. package/src/git-choices.ts +42 -0
  10. package/src/git-command.ts +172 -2
  11. package/src/git.ts +126 -294
  12. package/src/history/collect.ts +15 -6
  13. package/src/review-input.ts +36 -0
  14. package/src/review-limits.ts +12 -0
  15. package/src/review-path.ts +18 -12
  16. package/src/review-result.ts +26 -5
  17. package/src/review.ts +150 -62
  18. package/src/session/review-artifact-store.ts +97 -0
  19. package/src/session/review-plan-store.ts +93 -12
  20. package/src/target/change-metadata.ts +125 -0
  21. package/src/target/diff.ts +43 -0
  22. package/src/target/file-manifest.ts +40 -0
  23. package/src/target/packet.ts +17 -6
  24. package/src/target/resolve.ts +209 -0
  25. package/src/tool/agent-review-schemas.ts +9 -4
  26. package/src/tool/agent-review-tools.ts +46 -14
  27. package/src/tool/child-failure-diagnostics.ts +26 -49
  28. package/src/tool/child-lifecycle-trace.ts +3 -16
  29. package/src/tool/child-session-runner.ts +28 -11
  30. package/src/tool/child-usage.ts +73 -0
  31. package/src/tool/diagnostic-sanitizer.ts +35 -0
  32. package/src/tool/output-page.ts +26 -0
  33. package/src/tool/planner-runner.ts +28 -10
  34. package/src/tool/review-output-tool.ts +93 -0
  35. package/src/tool/review-runner.ts +9 -7
  36. package/src/tool/review-tools.ts +90 -12
  37. package/src/tool/review-workflow.ts +146 -82
  38. package/src/tool/schemas.ts +24 -5
  39. package/src/tool/session-lifecycle.ts +44 -54
  40. package/src/tool/usage-format.ts +15 -0
  41. package/src/tui/common.ts +8 -13
  42. package/src/tui/prepare.ts +57 -31
  43. package/src/tui/run.ts +13 -3
  44. package/src/types.ts +60 -21
  45. package/node_modules/@mrclrchtr/supi-core/src/abort-utils.ts +0 -31
  46. package/node_modules/@mrclrchtr/supi-core/src/substrate-types.ts +0 -11
  47. package/node_modules/@mrclrchtr/supi-core/src/types.ts +0 -2
@@ -1,3 +1,4 @@
1
+ import type { Usage } from "@earendil-works/pi-ai";
1
2
  import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
2
3
  import type { ChildFailureCode, ChildFailureDiagnostics, ReviewProgress } from "../types.ts";
3
4
  import { buildChildFailureDiagnostics } from "./child-failure-diagnostics.ts";
@@ -7,6 +8,10 @@ import {
7
8
  ChildLifecycleTraceCollector,
8
9
  getRegisteredToolNames,
9
10
  } from "./child-lifecycle-trace.ts";
11
+ import { collectChildUsage } from "./child-usage.ts";
12
+
13
+ /** Maximum time cancellation waits for a provider abort before host cleanup continues. */
14
+ export const CHILD_ABORT_GRACE_MS = 2_000;
10
15
 
11
16
  /**
12
17
  * Context passed to event handlers, timeout callbacks, and result factories.
@@ -33,15 +38,10 @@ export interface LifecycleCtx<TResult> {
33
38
  getLifecycleTrace: () => ChildLifecycleTrace;
34
39
  /** Build a safe non-success diagnostic artifact from the observed child run. */
35
40
  getFailureDiagnostics: () => ChildFailureDiagnostics;
41
+ /** Aggregate nested-model usage observed in the child transcript. */
42
+ getUsage: () => Usage | undefined;
36
43
  /** Add one allowlisted runner-control marker to the Child Lifecycle Trace. */
37
44
  recordHostMarker: (marker: ChildLifecycleHostMarker) => void;
38
- /**
39
- * Register a teardown function that runs when cleanup is called.
40
- * Useful for custom timers or resources set up by `onTimeout`.
41
- */
42
- addTeardown: (fn: () => void) => void;
43
- /** Timestamp (ms) when the lifecycle started, for elapsed-time display. */
44
- startTime: number;
45
45
  }
46
46
 
47
47
  /** Configuration for `runWithLifecycle`. */
@@ -52,20 +52,13 @@ export interface RunWithLifecycleConfig<TResult> {
52
52
  prompt: string;
53
53
  /** Optional abort signal. */
54
54
  signal?: AbortSignal;
55
- /** Timeout in milliseconds before the session is aborted. */
56
- timeoutMs: number;
55
+ /** Optional timeout in milliseconds before the session is aborted. */
56
+ timeoutMs?: number;
57
57
  /**
58
58
  * Event handler. Receives each session event and the lifecycle context.
59
59
  * Call `ctx.resolve(ctx.cleanup(result))` to settle the promise.
60
60
  */
61
61
  onEvent: (event: AgentSessionEvent, ctx: LifecycleCtx<TResult>) => void;
62
- /**
63
- * Custom timeout behavior. When omitted, the session is hard-aborted
64
- * and resolved with `timeoutResult`. When provided, the callback can
65
- * steer the session and schedule a hard abort, registering cleanup
66
- * via `ctx.addTeardown`.
67
- */
68
- onTimeout?: (ctx: LifecycleCtx<TResult>) => void;
69
62
  /** Factory for the result produced when the abort signal fires. */
70
63
  canceledResult: (ctx: LifecycleCtx<TResult>) => TResult;
71
64
  /** Factory for the result produced when prompt preflight or execution fails. */
@@ -100,14 +93,12 @@ function startPrompt(options: StartPromptOptions): void {
100
93
  /**
101
94
  * Manages the lifecycle of a child agent session: subscribes to events,
102
95
  * wires abort-signal handling, enforces a timeout, and provides idempotent
103
- * cleanup. The caller supplies an event handler and optional custom timeout
104
- * behavior via `onTimeout`.
96
+ * cleanup. The caller supplies the structured event/result mapping.
105
97
  *
106
98
  * The returned promise resolves when:
107
99
  * - The event handler calls `ctx.resolve(ctx.cleanup(result))`
108
100
  * - The abort signal fires (resolves via `canceledResult(ctx)`)
109
- * - The timeout expires (resolves via `timeoutResult`, or `onTimeout` handles
110
- * it by calling `ctx.resolve(ctx.cleanup(...))` itself)
101
+ * - The optional timeout expires and resolves via `timeoutResult`
111
102
  * - `session.prompt()` rejects (resolves via `failedResult`)
112
103
  */
113
104
  // biome-ignore lint/complexity/noExcessiveLinesPerFunction: lifecycle ownership must remain in one state-machine closure
@@ -120,7 +111,6 @@ export function runWithLifecycle<TResult>(
120
111
  signal,
121
112
  timeoutMs,
122
113
  onEvent,
123
- onTimeout,
124
114
  canceledResult,
125
115
  failedResult,
126
116
  timeoutResult,
@@ -157,12 +147,14 @@ export function runWithLifecycle<TResult>(
157
147
  if (state.settled) return result;
158
148
  state.settled = true;
159
149
  cancelTeardown();
160
- session.dispose();
150
+ try {
151
+ session.dispose();
152
+ } catch {
153
+ // Disposal is best-effort after the outcome is already determined.
154
+ }
161
155
  return result;
162
156
  };
163
157
 
164
- const startTime = Date.now();
165
-
166
158
  return new Promise<TResult>((resolve) => {
167
159
  const ctx: LifecycleCtx<TResult> = {
168
160
  resolve,
@@ -178,9 +170,8 @@ export function runWithLifecycle<TResult>(
178
170
  lifecycleTrace: lifecycleTrace.snapshot(),
179
171
  recentActivity: lifecycleTrace.recentActivitySnapshot(),
180
172
  }),
173
+ getUsage: () => collectChildUsage(session),
181
174
  recordHostMarker: (marker) => lifecycleTrace.recordHostMarker(marker),
182
- addTeardown,
183
- startTime,
184
175
  };
185
176
 
186
177
  let promptSettled = false;
@@ -203,7 +194,7 @@ export function runWithLifecycle<TResult>(
203
194
  dispatchEvent(event);
204
195
  };
205
196
 
206
- session.subscribe((event: AgentSessionEvent) => {
197
+ const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
207
198
  lifecycleTrace.observe(event);
208
199
  if (event.type === "agent_settled" && !promptSettled) {
209
200
  deferredAgentSettled = event;
@@ -211,18 +202,29 @@ export function runWithLifecycle<TResult>(
211
202
  }
212
203
  dispatchEvent(event);
213
204
  });
205
+ if (typeof unsubscribe === "function") addTeardown(unsubscribe);
206
+
207
+ const finishAfterAbort = (result: () => TResult): void => {
208
+ let graceId: ReturnType<typeof setTimeout> | undefined;
209
+ const grace = new Promise<void>((resolveGrace) => {
210
+ graceId = setTimeout(resolveGrace, CHILD_ABORT_GRACE_MS);
211
+ graceId.unref?.();
212
+ });
213
+ const abort = Promise.resolve()
214
+ .then(() => session.abort())
215
+ .catch(() => undefined);
216
+ void Promise.race([abort, grace]).finally(() => {
217
+ if (graceId) clearTimeout(graceId);
218
+ resolve(cleanup(result()));
219
+ });
220
+ };
214
221
 
215
222
  // Abort signal handler
216
223
  const onAbort = () => {
217
224
  if (state.settled || state.aborting) return;
218
225
  state.aborting = true;
219
226
  ctx.recordHostMarker({ type: "abort_requested", reason: "canceled" });
220
- void session
221
- .abort()
222
- .catch(() => {})
223
- .finally(() => {
224
- resolve(cleanup(canceledResult(ctx)));
225
- });
227
+ finishAfterAbort(() => canceledResult(ctx));
226
228
  };
227
229
  if (signal) {
228
230
  signal.addEventListener("abort", onAbort, { once: true });
@@ -235,30 +237,18 @@ export function runWithLifecycle<TResult>(
235
237
 
236
238
  // Timeout handler
237
239
  const onTimeoutExpired = () => {
238
- if (state.settled || state.aborting) return;
240
+ if (timeoutMs === undefined || state.settled || state.aborting) return;
239
241
  ctx.recordHostMarker({ type: "timeout_expired" });
240
242
 
241
- if (onTimeout) {
242
- try {
243
- onTimeout(ctx);
244
- } catch {
245
- resolve(cleanup(failedResult("unexpected-runner-failure", ctx)));
246
- }
247
- } else {
248
- // Default: hard abort
249
- state.aborting = true;
250
- ctx.recordHostMarker({ type: "abort_requested", reason: "timeout" });
251
- void session
252
- .abort()
253
- .catch(() => {})
254
- .finally(() => {
255
- resolve(cleanup(timeoutResult(timeoutMs, ctx)));
256
- });
257
- }
243
+ state.aborting = true;
244
+ ctx.recordHostMarker({ type: "abort_requested", reason: "timeout" });
245
+ finishAfterAbort(() => timeoutResult(timeoutMs, ctx));
258
246
  };
259
- const timeoutId = setTimeout(onTimeoutExpired, timeoutMs);
260
- timeoutId.unref?.();
261
- addTeardown(() => clearTimeout(timeoutId));
247
+ if (timeoutMs !== undefined) {
248
+ const timeoutId = setTimeout(onTimeoutExpired, timeoutMs);
249
+ timeoutId.unref?.();
250
+ addTeardown(() => clearTimeout(timeoutId));
251
+ }
262
252
 
263
253
  // Start the session. Prompt rejection is a distinct host-owned outcome;
264
254
  // caught provider or runner errors are intentionally never retained.
@@ -0,0 +1,15 @@
1
+ import type { Usage } from "@earendil-works/pi-ai";
2
+
3
+ /** Format nested-model usage consistently across Markdown and TUI surfaces. */
4
+ export function formatReviewUsage(usage: Usage): string {
5
+ const tokens = `${usage.totalTokens.toLocaleString("en-US")} tokens`;
6
+ const parts = [
7
+ tokens,
8
+ `${usage.input.toLocaleString("en-US")} in`,
9
+ `${usage.output.toLocaleString("en-US")} out`,
10
+ ];
11
+ if (usage.cacheRead > 0) parts.push(`${usage.cacheRead.toLocaleString("en-US")} cache read`);
12
+ if (usage.cacheWrite > 0) parts.push(`${usage.cacheWrite.toLocaleString("en-US")} cache write`);
13
+ if (usage.cost.total > 0) parts.push(`$${usage.cost.total.toFixed(4)}`);
14
+ return parts.join(" · ");
15
+ }
package/src/tui/common.ts CHANGED
@@ -8,6 +8,8 @@
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 {
12
14
  ChildFailureDiagnostics,
13
15
  FindingEffort,
@@ -151,19 +153,11 @@ function buildNonCompletedSection(
151
153
  );
152
154
  }
153
155
 
154
- if (diagnostics.lastAssistantErrorText) {
155
- const truncated =
156
- diagnostics.lastAssistantErrorText.length > 200
157
- ? `${diagnostics.lastAssistantErrorText.slice(0, 200)}…`
158
- : diagnostics.lastAssistantErrorText;
159
- container.addChild(new Text(theme.fg("error", truncated), 1, 0));
160
- } else if (diagnostics.lastLifecycleErrorText) {
161
- const truncated =
162
- diagnostics.lastLifecycleErrorText.length > 200
163
- ? `${diagnostics.lastLifecycleErrorText.slice(0, 200)}…`
164
- : diagnostics.lastLifecycleErrorText;
165
- container.addChild(new Text(theme.fg("error", truncated), 1, 0));
166
- } else if (diagnostics.lastAssistantStopReason === "error") {
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") {
167
161
  container.addChild(
168
162
  new Text(
169
163
  theme.fg(
@@ -214,6 +208,7 @@ export function buildTaskSection(
214
208
  const metaParts = [
215
209
  theme.fg("dim", `model: ${result.modelId}`),
216
210
  theme.fg("dim", `hash: ${result.packetHash.slice(0, 12)}…`),
211
+ ...(result.usage ? [theme.fg("dim", formatReviewUsage(result.usage))] : []),
217
212
  ];
218
213
  container.addChild(new Text(metaParts.join(" "), 1, 0));
219
214
 
@@ -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,9 +134,9 @@ export interface ChildFailureDiagnostics {
109
134
  recentActivity?: string[];
110
135
  lastAssistantStopReason?: string;
111
136
  lastAssistantToolCalls?: string[];
112
- /** Error text extracted from the last assistant message when stopReason is "error". */
137
+ /** Bounded, redacted canonical provider error from the last errored assistant message. */
113
138
  lastAssistantErrorText?: string;
114
- /** Error text extracted from the most recent lifecycle event (compaction_end, auto_retry_end). */
139
+ /** Bounded, redacted provider error from the most recent recovery lifecycle event. */
115
140
  lastLifecycleErrorText?: string;
116
141
  }
117
142
 
@@ -132,9 +157,6 @@ export interface ReviewProgress {
132
157
  cacheRead?: number;
133
158
  cacheWrite?: number;
134
159
  };
135
- toolCounts?: Record<string, number>;
136
- currentFocus?: { label: string; detail: string };
137
- elapsedMs?: number;
138
160
  }
139
161
 
140
162
  export interface PlannerInvocation {
@@ -147,10 +169,10 @@ export interface PlannerInvocation {
147
169
  }
148
170
 
149
171
  export type PlannerRunResult =
150
- | { kind: "success"; draft: PlannerDraft }
151
- | ({ kind: "failed" } & ChildFailedResult)
152
- | { kind: "canceled"; diagnostics: ChildFailureDiagnostics }
153
- | { 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 };
154
176
 
155
177
  export interface ReviewerInvocation {
156
178
  prompt: string;
@@ -163,14 +185,15 @@ export interface ReviewerInvocation {
163
185
  }
164
186
 
165
187
  export type ReviewerRunResult =
166
- | { kind: "success"; submission: ReviewSubmission; modelId: string }
167
- | ({ kind: "failed"; modelId: string } & ChildFailedResult)
168
- | { 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 }
169
191
  | {
170
192
  kind: "timeout";
171
193
  timeoutMs: number;
172
194
  modelId: string;
173
195
  diagnostics: ChildFailureDiagnostics;
196
+ usage?: Usage;
174
197
  };
175
198
 
176
199
  interface ReviewTaskResultIdentity {
@@ -178,6 +201,8 @@ interface ReviewTaskResultIdentity {
178
201
  modelId: string;
179
202
  /** SHA-256 of the exact reviewer packet bytes. */
180
203
  packetHash: string;
204
+ /** Aggregate nested-model usage for this task, when reported by the provider. */
205
+ usage?: Usage;
181
206
  }
182
207
 
183
208
  export type ReviewTaskResult = ReviewTaskResultIdentity &
@@ -207,11 +232,21 @@ export type ReviewTaskResult = ReviewTaskResultIdentity &
207
232
  export interface PlanningRecord {
208
233
  promptVersion: string;
209
234
  modelId: string;
235
+ /** Planner usage is informational here and is not charged again by the run tool. */
236
+ usage?: Usage;
210
237
  draft: PlannerDraft;
211
238
  effectiveReview: ReviewInput;
212
239
  decision: "accept-draft" | "use-review";
213
240
  }
214
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
+
215
250
  export interface ReviewBatchDetails {
216
251
  kind: "review-batch";
217
252
  mode: "direct" | "prepared";
@@ -220,6 +255,7 @@ export interface ReviewBatchDetails {
220
255
  review: ReviewInput;
221
256
  planning?: PlanningRecord;
222
257
  results: ReviewTaskResult[];
258
+ output?: ReviewOutputReference;
223
259
  }
224
260
 
225
261
  export interface PreparedReviewDetails {
@@ -230,6 +266,9 @@ export interface PreparedReviewDetails {
230
266
  plannerDraft?: PlannerDraft;
231
267
  plannerModelId?: string;
232
268
  plannerPromptVersion?: string;
269
+ plannerUsage?: Usage;
270
+ plannerFailure?: Exclude<PlannerRunResult, { kind: "success" }>;
271
+ output?: ReviewOutputReference;
233
272
  }
234
273
 
235
274
  export interface ReviewPacket {
@@ -1,31 +0,0 @@
1
- /**
2
- * Abort controller/signal utility helpers.
3
- *
4
- * @module
5
- */
6
-
7
- /**
8
- * Combine a caller-provided abort controller with a generation timeout signal.
9
- *
10
- * Returns the combined signal and a cleanup function that removes both
11
- * event listeners. Callers must invoke cleanup in a `finally` block
12
- * to avoid listener leaks.
13
- */
14
- export function combineAbortSignals(
15
- abort: AbortController,
16
- timeoutMs: number,
17
- ): { signal: AbortSignal; cleanup: () => void } {
18
- const timeoutSignal = AbortSignal.timeout(timeoutMs);
19
- const combinedController = new AbortController();
20
- const onAbort = () => combinedController.abort();
21
- abort.signal.addEventListener("abort", onAbort, { once: true });
22
- timeoutSignal.addEventListener("abort", onAbort, { once: true });
23
-
24
- return {
25
- signal: combinedController.signal,
26
- cleanup: () => {
27
- abort.signal.removeEventListener("abort", onAbort);
28
- timeoutSignal.removeEventListener("abort", onAbort);
29
- },
30
- };
31
- }
@@ -1,11 +0,0 @@
1
- /** 0-based position used by LSP and code-intelligence internally. */
2
- export interface CodePosition {
3
- line: number;
4
- character: number;
5
- }
6
-
7
- /** Normalized location — flat replacement for LSP's nested Location/range shape. */
8
- export interface CodeLocation {
9
- uri: string;
10
- range: { start: CodePosition; end: CodePosition };
11
- }
@@ -1,2 +0,0 @@
1
- // supi-core types domain — shared substrate types (zero dependencies, pure types).
2
- export type { CodeLocation, CodePosition } from "./substrate-types.ts";