@mrclrchtr/supi-review 1.11.3 → 1.12.0

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "SuPi Review extension — structured code review via /supi-review command",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.11.3"
+    "@mrclrchtr/supi-core": "1.12.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -51,9 +51,7 @@
     ],
     "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-review/assets/logo.png"
   },
-  "main": "src/api.ts",
   "exports": {
-    "./api": "./src/api.ts",
     "./extension": "./src/extension.ts",
     "./package.json": "./package.json"
   }

package/src/history/collect.ts

@@ -1,4 +1,5 @@
 import type { SessionContext } from "@earendil-works/pi-coding-agent";
+import { extractAssistantText } from "../tool/runner-helpers.ts";
 
 type ResolvedSessionMessage = SessionContext["messages"][number];
 
@@ -101,7 +102,7 @@ function serializeEntry(
   switch (message.role) {
     case "user":
     case "assistant": {
-      const text = normalizeText(extractMessageText(message.content));
+      const text = normalizeText(extractAssistantText(message.content) ?? "");
       if (!text) return undefined;
       return {
         label: message.role === "user" ? "User" : "Assistant",
@@ -110,7 +111,7 @@ function serializeEntry(
       };
     }
     case "custom": {
-      const text = normalizeText(extractMessageText(message.content));
+      const text = normalizeText(extractAssistantText(message.content) ?? "");
       if (!text) return undefined;
       return { label: "Custom", text, isSummary: false };
     }
@@ -129,25 +130,6 @@ function serializeEntry(
   }
 }
 
-function extractMessageText(content: unknown): string {
-  if (typeof content === "string") {
-    return content;
-  }
-
-  if (!Array.isArray(content)) {
-    return "";
-  }
-
-  return content
-    .map((part) => {
-      if (typeof part !== "object" || !part) return "";
-      const text = (part as { text?: unknown }).text;
-      return typeof text === "string" ? text : "";
-    })
-    .filter((text) => text.length > 0)
-    .join("\n");
-}
-
 function normalizeText(text: string): string {
   return text.replace(/\s+/g, " ").trim();
 }

package/src/history/synthesize.ts

@@ -1,8 +1,12 @@
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { listReviewInstructionBlocks } from "../target/review-instruction-blocks.ts";
+import { listReviewInstructionBlocks } from "../target/packet.ts";
 import { runBriefSynthesis } from "../tool/brief-runner.ts";
-import type { BriefSynthesisRunResult, ReviewProgress } from "../tool/runner-types.ts";
-import type { ReviewModelSelection, ReviewSnapshot } from "../types.ts";
+import type {
+  BriefSynthesisRunResult,
+  ReviewModelSelection,
+  ReviewProgress,
+  ReviewSnapshot,
+} from "../types.ts";
 
 const DIFF_EXCERPT_CHAR_BUDGET = 12_000;
 

package/src/review.ts

@@ -7,8 +7,8 @@ import { synthesizeReviewBrief } from "./history/synthesize.ts";
 import { normalizeReviewResult } from "./review-result.ts";
 import { buildReviewPacket } from "./target/packet.ts";
 import { runReviewer } from "./tool/review-runner.ts";
-import type { BriefSynthesisRunResult } from "./tool/runner-types.ts";
 import type {
+  BriefSynthesisRunResult,
   RawReviewResult,
   ReviewPlan,
   ReviewResult,

package/src/target/packet.ts

@@ -5,10 +5,60 @@ import type {
   ReviewSnapshot,
   SynthesizedReviewBrief,
 } from "../types.ts";
-import {
-  type ReviewInstructionBlock,
-  resolveReviewInstructionBlocks,
-} from "./review-instruction-blocks.ts";
+export interface ReviewInstructionBlock {
+  id: ReviewInstructionBlockId;
+  title: string;
+  instruction: string;
+}
+
+const REVIEW_INSTRUCTION_BLOCKS: readonly ReviewInstructionBlock[] = [
+  {
+    id: "public-surface",
+    title: "Public-surface / rename / merge audit",
+    instruction:
+      "Sweep source, tests, docs, user-facing strings, and debug/status lists for stale public names after renames, removals, or merges.",
+  },
+  {
+    id: "cross-layer",
+    title: "Cross-layer propagation audit",
+    instruction:
+      "Verify every provider/runtime/orchestration/presentation/test handoff and look for at least one end-to-end expectation covering the threaded behavior.",
+  },
+  {
+    id: "schema-widening",
+    title: "Enum / operation / schema widening audit",
+    instruction:
+      "Audit validation, unavailable paths, branch coverage, aliases, and negative tests for widened enums, operations, or schemas.",
+  },
+  {
+    id: "cleanup",
+    title: "Cleanup / deletion / orphan audit",
+    instruction:
+      "Check for orphan files, dead imports or re-exports, stale comments, and outdated expectations after deletions or consumer removals.",
+  },
+];
+
+/** Return the full fixed catalog of review instruction blocks. */
+export function listReviewInstructionBlocks(): readonly ReviewInstructionBlock[] {
+  return REVIEW_INSTRUCTION_BLOCKS;
+}
+
+/** Resolve a brief-selected block ID list into canonical host-owned prompt blocks. */
+export function resolveReviewInstructionBlocks(
+  ids: readonly ReviewInstructionBlockId[],
+): ReviewInstructionBlock[] {
+  const resolved: ReviewInstructionBlock[] = [];
+  const seen = new Set<ReviewInstructionBlockId>();
+
+  for (const id of ids) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const block = REVIEW_INSTRUCTION_BLOCKS.find((b) => b.id === id);
+    if (block) resolved.push(block);
+  }
+
+  return resolved;
+}
 
 export interface DiffSection {
   file: string;

package/src/tool/brief-runner.ts

@@ -7,13 +7,14 @@ import {
   defineTool,
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
-import type { SynthesizedReviewBrief } from "../types.ts";
 import type {
   BriefSynthesisInvocation,
   BriefSynthesisRunResult,
-  ReviewProgress,
-} from "./runner-types.ts";
+  SynthesizedReviewBrief,
+} from "../types.ts";
+import { buildProgressTokens, extractLastAssistantText } from "./runner-helpers.ts";
 import { reviewBriefSchema } from "./schemas.ts";
+import { type LifecycleCtx, runWithLifecycle } from "./session-lifecycle.ts";
 
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
 
@@ -78,51 +79,12 @@ async function createBriefSession(
   return session;
 }
 
-function extractLastAssistantText(session: AgentSession): string | undefined {
-  const messages = session.messages;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if (message?.role !== "assistant") continue;
-    const text = extractAssistantText(message.content);
-    if (text) return text;
-  }
-  return undefined;
-}
-
-function extractAssistantText(content: unknown): string | undefined {
-  if (typeof content === "string") {
-    return content.length > 0 ? content : undefined;
-  }
-
-  if (!Array.isArray(content)) {
-    return undefined;
-  }
-
-  const texts = content
-    .map((part) => {
-      if (typeof part !== "object" || !part) return "";
-      const text = (part as { text?: unknown }).text;
-      return typeof text === "string" ? text : "";
-    })
-    .filter((value) => value.length > 0);
-
-  return texts.length > 0 ? texts.join("\n") : undefined;
-}
-
-function emitProgress(session: AgentSession, progress: ReviewProgress): ReviewProgress {
-  try {
-    const stats = session.getSessionStats();
-    progress.tokens = stats?.tokens
-      ? {
-          input: stats.tokens.input ?? 0,
-          output: stats.tokens.output ?? 0,
-          total: stats.tokens.total ?? 0,
-        }
-      : undefined;
-  } catch {
-    // ignore missing stats
-  }
-  return { ...progress, activities: [...progress.activities] };
+function emitBriefProgress(
+  ctx: LifecycleCtx<BriefSynthesisRunResult>,
+  invocation: BriefSynthesisInvocation,
+): void {
+  ctx.progress.tokens = buildProgressTokens(() => ctx.session.getSessionStats());
+  invocation.onProgress?.({ ...ctx.progress, activities: [...ctx.progress.activities] });
 }
 
 function handleAgentEnd(options: {
@@ -140,7 +102,7 @@ function handleAgentEnd(options: {
   if (brief) {
     return cleanup({ kind: "success", brief });
   }
-  const lastText = extractLastAssistantText(session);
+  const lastText = extractLastAssistantText(session.messages);
   return cleanup({
     kind: "failed",
     reason: lastText
@@ -170,99 +132,50 @@ export async function runBriefSynthesis(
     };
   }
 
-  const progress: ReviewProgress = { turns: 0, toolUses: 0, activities: [], tokens: undefined };
-  const state = { settled: false, aborting: false };
-  let cancelTeardown: (() => void) | undefined;
-
-  const cleanup = (result: BriefSynthesisRunResult): BriefSynthesisRunResult => {
-    if (state.settled) return result;
-    state.settled = true;
-    cancelTeardown?.();
-    session.dispose();
-    return result;
-  };
-
-  const handleEvent = (
-    event: AgentSessionEvent,
-    resolve: (result: BriefSynthesisRunResult) => void,
-  ) => {
-    switch (event.type) {
-      case "turn_end":
-        progress.turns++;
-        invocation.onProgress?.(emitProgress(session, progress));
-        break;
-      case "tool_execution_start":
-        progress.toolUses++;
-        progress.activities = [
-          event.toolName === "submit_review_brief" ? "submitting brief" : event.toolName,
-        ];
-        invocation.onProgress?.(emitProgress(session, progress));
-        break;
-      case "tool_execution_end":
-        progress.activities = [];
-        invocation.onProgress?.(emitProgress(session, progress));
-        break;
-      case "agent_end": {
-        const result = handleAgentEnd({
-          event,
-          session,
-          brief: resultHolder.value,
-          state,
-          cleanup,
-        });
-        if (result) {
-          resolve(result);
+  return runWithLifecycle<BriefSynthesisRunResult>({
+    session,
+    prompt: invocation.prompt,
+    signal: invocation.signal,
+    timeoutMs: invocation.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    onEvent: (event, ctx) => {
+      switch (event.type) {
+        case "turn_end":
+          ctx.progress.turns++;
+          emitBriefProgress(ctx, invocation);
+          break;
+        case "tool_execution_start":
+          ctx.progress.toolUses++;
+          ctx.progress.activities = [
+            event.toolName === "submit_review_brief" ? "submitting brief" : event.toolName,
+          ];
+          emitBriefProgress(ctx, invocation);
+          break;
+        case "tool_execution_end":
+          ctx.progress.activities = [];
+          emitBriefProgress(ctx, invocation);
+          break;
+        case "agent_end": {
+          const result = handleAgentEnd({
+            event,
+            session,
+            brief: resultHolder.value,
+            state: ctx.state,
+            cleanup: ctx.cleanup,
+          });
+          if (result) {
+            ctx.resolve(result);
+          }
+          break;
         }
-        break;
+        default:
+          break;
       }
-      default:
-        break;
-    }
-  };
-
-  return new Promise<BriefSynthesisRunResult>((resolve) => {
-    session.subscribe((event: AgentSessionEvent) => handleEvent(event, resolve));
-
-    const onAbort = () => {
-      if (state.settled) return;
-      state.aborting = true;
-      void session
-        .abort()
-        .catch(() => {})
-        .finally(() => {
-          resolve(cleanup({ kind: "canceled" }));
-        });
-    };
-    invocation.signal?.addEventListener("abort", onAbort, { once: true });
-
-    const timeoutId = setTimeout(() => {
-      if (state.settled) return;
-      state.aborting = true;
-      void session
-        .abort()
-        .catch(() => {})
-        .finally(() => {
-          resolve(
-            cleanup({ kind: "timeout", timeoutMs: invocation.timeoutMs ?? DEFAULT_TIMEOUT_MS }),
-          );
-        });
-    }, invocation.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-    timeoutId.unref?.();
-
-    cancelTeardown = () => {
-      invocation.signal?.removeEventListener("abort", onAbort);
-      clearTimeout(timeoutId);
-    };
-
-    session.prompt(invocation.prompt).catch((error: unknown) => {
-      if (!state.settled) {
-        resolve(
-          cleanup({
-            kind: "failed",
-            reason: `Brief synthesis session error: ${error instanceof Error ? error.message : String(error)}`,
-          }),
-        );
-      }
-    });
+    },
+    canceledResult: () => ({ kind: "canceled" as const }),
+    failedResult: (reason) => ({
+      kind: "failed" as const,
+      reason,
+    }),
+    timeoutResult: (ms) => ({ kind: "timeout" as const, timeoutMs: ms }),
   });
 }

package/src/tool/review-debug.ts

@@ -0,0 +1,123 @@
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { ReviewFailureDebugInfo, ReviewProgress } from "../types.ts";
+import { buildProgressTokens, extractAssistantText } from "./runner-helpers.ts";
+
+export const RECENT_EVENTS_MAX = 10;
+export const LAST_ASSISTANT_TEXT_DEBUG_MAX = 2_000;
+
+export interface LastAssistantDebugInfo {
+  text?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  toolCalls?: string[];
+}
+
+export function extractLastAssistantDebugFromMessages(
+  messages: ArrayLike<Record<string, unknown>> | undefined,
+): LastAssistantDebugInfo | undefined {
+  if (!messages) return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "assistant") continue;
+
+    const text = extractAssistantText(message.content);
+    const stopReason =
+      typeof message.stopReason === "string" ? (message.stopReason as string) : undefined;
+    const errorMessage =
+      typeof message.errorMessage === "string" ? (message.errorMessage as string) : undefined;
+    const toolCalls = extractAssistantToolCalls(message.content);
+
+    return {
+      text: text ? truncateText(text, LAST_ASSISTANT_TEXT_DEBUG_MAX) : undefined,
+      stopReason,
+      errorMessage,
+      toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+    };
+  }
+  return undefined;
+}
+
+export function extractLastAssistantDebug(
+  session: AgentSession,
+): LastAssistantDebugInfo | undefined {
+  return extractLastAssistantDebugFromMessages(
+    session.messages as unknown as Array<Record<string, unknown>>,
+  );
+}
+
+function extractAssistantToolCalls(content: unknown): string[] {
+  if (!Array.isArray(content)) return [];
+
+  return content
+    .map((part) => {
+      if (typeof part !== "object" || !part) return undefined;
+      const toolPart = part as { type?: unknown; name?: unknown };
+      return toolPart.type === "toolCall" && typeof toolPart.name === "string"
+        ? toolPart.name
+        : undefined;
+    })
+    .filter((name): name is string => !!name);
+}
+
+export function summarizeSessionEvent(event: AgentSessionEvent): string | undefined {
+  switch (event.type) {
+    case "message_end": {
+      const message = event.message as unknown as Record<string, unknown>;
+      if (message.role !== "assistant") return undefined;
+      const stopReason =
+        typeof message.stopReason === "string" ? String(message.stopReason) : undefined;
+      const suffix = stopReason ? `:${stopReason}` : "";
+      return `assistant:end${suffix}`;
+    }
+    case "tool_execution_start":
+      return `tool:start:${event.toolName}`;
+    case "tool_execution_end":
+      return `tool:end:${event.toolName}${event.isError ? ":error" : ""}`;
+    case "turn_end":
+      return "turn:end";
+    case "agent_end":
+      return `agent:end${event.willRetry ? ":retry" : ""}`;
+    case "auto_retry_start":
+      return `retry:start:${event.attempt}/${event.maxAttempts}`;
+    case "auto_retry_end":
+      return `retry:end:${event.success ? "success" : "failed"}`;
+    default:
+      return undefined;
+  }
+}
+
+export function pushRecentEvent(recentEvents: string[], summary: string | undefined): void {
+  if (!summary) return;
+  recentEvents.push(summary);
+  if (recentEvents.length > RECENT_EVENTS_MAX) {
+    recentEvents.splice(0, recentEvents.length - RECENT_EVENTS_MAX);
+  }
+}
+
+export interface BuildFailureDebugInput {
+  progress: ReviewProgress;
+  session: AgentSession;
+  recentEvents: string[];
+}
+
+export function buildFailureDebug(input: BuildFailureDebugInput): ReviewFailureDebugInfo {
+  input.progress.tokens = buildProgressTokens(() => input.session.getSessionStats());
+  const lastAssistant = extractLastAssistantDebug(input.session);
+
+  return {
+    turns: input.progress.turns,
+    toolUses: input.progress.toolUses,
+    activities: input.progress.activities.length > 0 ? [...input.progress.activities] : undefined,
+    tokens: input.progress.tokens,
+    recentEvents: input.recentEvents.length > 0 ? [...input.recentEvents] : undefined,
+    lastAssistantText: lastAssistant?.text,
+    lastAssistantStopReason: lastAssistant?.stopReason,
+    lastAssistantErrorMessage: lastAssistant?.errorMessage,
+    lastAssistantToolCalls: lastAssistant?.toolCalls,
+  };
+}
+
+function truncateText(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, maxLen)}... (${text.length - maxLen} more chars)`;
+}