@mrclrchtr/supi-review 2.6.1 → 2.7.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "2.6.1",
+  "version": "2.7.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": "2.6.1",
+  "version": "2.7.0",
   "description": "SuPi Review extension — session-aware review command and agent tools",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "2.6.1"
+    "@mrclrchtr/supi-core": "2.7.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/review.ts

@@ -7,6 +7,7 @@ import { synthesizeReviewBrief } from "./history/synthesize.ts";
 import { normalizeReviewResult } from "./review-result.ts";
 import { buildReviewPacket } from "./target/packet.ts";
 import { registerAgentReviewTools } from "./tool/agent-review-tools.ts";
+import { createUnobservedChildFailureDiagnostics } from "./tool/child-failure-diagnostics.ts";
 import { runReviewer } from "./tool/review-runner.ts";
 import type {
   BriefSynthesisRunResult,
@@ -17,7 +18,11 @@ import type {
   ReviewTargetSpec,
 } from "./types.ts";
 import { collectReviewNote, previewReviewPlan, selectModel, selectTarget } from "./ui/flow.ts";
-import { formatReviewContent } from "./ui/format-content.ts";
+import {
+  formatBriefSynthesisFailureContent,
+  formatBriefSynthesisFailureCopy,
+  formatReviewContent,
+} from "./ui/format-content.ts";
 import { registerReviewRenderer } from "./ui/renderer.ts";
 
 type CommandContext = Parameters<Parameters<ExtensionAPI["registerCommand"]>[1]["handler"]>[1];
@@ -74,22 +79,21 @@ async function handleInteractive(ctx: CommandContext, pi: ExtensionAPI): Promise
   );
 
   if (!synthesis) {
-    notifyBriefDone(
-      pi,
-      {
-        kind: "failed",
-        reason: "Brief synthesis encountered an unexpected error",
-      } as BriefSynthesisRunResult,
-      snapshot,
-      model.canonicalId,
-    );
-    ctx.ui.notify("Brief synthesis was canceled or failed", "warning");
+    const failure: BriefSynthesisRunResult = {
+      kind: "failed",
+      failureCode: "unexpected-runner-failure",
+      diagnostics: createUnobservedChildFailureDiagnostics(),
+    };
+    notifyBriefDone(pi, failure, snapshot, model.canonicalId);
+    injectBriefSynthesisFailureMessage(pi, failure, snapshot, model.canonicalId);
+    ctx.ui.notify(formatBriefSynthesisFailureCopy(failure), "warning");
     return;
   }
 
   notifyBriefDone(pi, synthesis, snapshot, model.canonicalId);
 
   if (synthesis.kind !== "success") {
+    injectBriefSynthesisFailureMessage(pi, synthesis, snapshot, model.canonicalId);
     notifySynthesisFailure(synthesis, ctx);
     return;
   }
@@ -122,14 +126,17 @@ async function handleInteractive(ctx: CommandContext, pi: ExtensionAPI): Promise
   );
 
   if (!rawResult) {
-    notifyReviewDone(pi, {
+    const failure: ReviewResult = {
       kind: "failed",
-      reason: "Review encountered an unexpected error",
+      failureCode: "unexpected-runner-failure",
+      diagnostics: createUnobservedChildFailureDiagnostics(),
       snapshot,
       brief,
       modelId: model.canonicalId,
-    } as ReviewResult);
-    ctx.ui.notify("Review was canceled or failed", "warning");
+    };
+    notifyReviewDone(pi, failure);
+    injectReviewMessage(pi, failure);
+    ctx.ui.notify("Reviewer ended unexpectedly.", "warning");
     return;
   }
 
@@ -172,20 +179,27 @@ function notifySynthesisFailure(
   result: Exclude<BriefSynthesisRunResult, { kind: "success" }>,
   ctx: CommandContext,
 ): void {
-  switch (result.kind) {
-    case "failed":
-      ctx.ui.notify(result.reason, "error");
-      break;
-    case "timeout":
-      ctx.ui.notify(
-        `Brief synthesis timed out after ${(result.timeoutMs / 1000).toFixed(0)}s`,
-        "warning",
-      );
-      break;
-    case "canceled":
-      ctx.ui.notify("Review canceled", "warning");
-      break;
-  }
+  ctx.ui.notify(
+    formatBriefSynthesisFailureCopy(result),
+    result.kind === "failed" ? "error" : "warning",
+  );
+}
+
+/** Persist a brief-synthesis failure so bounded diagnostics remain inspectable in parent history. */
+function injectBriefSynthesisFailureMessage(
+  pi: ExtensionAPI,
+  result: Exclude<BriefSynthesisRunResult, { kind: "success" }>,
+  snapshot: ReviewSnapshot,
+  modelId: string,
+): void {
+  pi.sendMessage({
+    customType: "supi-review",
+    content: formatBriefSynthesisFailureContent(result),
+    display: true,
+    details: {
+      briefSynthesisFailure: { result, snapshot, modelId },
+    },
+  });
 }
 
 /** Ring the terminal bell so the user knows to check back. */

package/src/tool/agent-review-tools.ts

@@ -20,6 +20,7 @@ import type {
   ReviewProgress,
   ReviewTargetSpec,
 } from "../types.ts";
+import { formatBriefSynthesisFailureCopy } from "../ui/format-content.ts";
 import { formatAgentReviewBatch, formatPreparedAgentReview } from "../ui/review-tool-format.ts";
 import {
   type AgentReviewProgressDetails,
@@ -35,6 +36,7 @@ import {
   runAgentReviewSchema,
 } from "./agent-review-schemas.ts";
 import { prepareAgentReviewPlan, runAgentReviewBatch } from "./agent-review-workflow.ts";
+import { formatChildLifecycleTrace } from "./child-lifecycle-trace.ts";
 import {
   PREPARE_REVIEW_TOOL_NAME,
   prepareReviewPromptGuidelines,
@@ -228,14 +230,12 @@ function formatPreparationFailure(
   outcome: Exclude<Awaited<ReturnType<typeof prepareAgentReviewPlan>>, { kind: "prepared" }>,
 ): string {
   if (outcome.kind === "no-snapshot") return outcome.reason;
-  switch (outcome.result.kind) {
-    case "failed":
-      return `Brief synthesis failed: ${outcome.result.reason}`;
-    case "canceled":
-      return "Brief synthesis was canceled.";
-    case "timeout":
-      return `Brief synthesis timed out after ${(outcome.result.timeoutMs / 1_000).toFixed(0)}s.`;
-  }
+
+  const { result } = outcome;
+  const trace = result.diagnostics?.lifecycleTrace;
+  return trace
+    ? `${formatBriefSynthesisFailureCopy(result)}\n\n${formatChildLifecycleTrace(trace)}`
+    : formatBriefSynthesisFailureCopy(result);
 }
 
 function activateRunTool(pi: ExtensionAPI): void {

package/src/tool/agent-review-workflow.ts

@@ -22,8 +22,8 @@ import type {
   ReviewTargetSpec,
   SynthesizedReviewBrief,
 } from "../types.ts";
+import { createUnobservedChildFailureDiagnostics } from "./child-failure-diagnostics.ts";
 import { runReviewer } from "./review-runner.ts";
-
 /** Inputs required to synthesize and retain one agent-driven review plan. */
 export interface PrepareAgentReviewWorkflowInput {
   cwd: string;
@@ -35,13 +35,11 @@ export interface PrepareAgentReviewWorkflowInput {
   onProgress?: (progress: ReviewProgress) => void;
   planStore: ReviewPlanStore;
 }
-
 /** Typed preparation outcome before any reviewer child session starts. */
 export type PrepareAgentReviewWorkflowOutcome =
   | { kind: "prepared"; plan: StoredAgentReviewPlan }
   | { kind: "no-snapshot"; reason: string }
   | { kind: "synthesis-failed"; result: Exclude<BriefSynthesisRunResult, { kind: "success" }> };
-
 /** Inputs required to critique and execute one prepared review plan. */
 export interface RunAgentReviewWorkflowInput {
   cwd: string;
@@ -55,13 +53,11 @@ export interface RunAgentReviewWorkflowInput {
   onReviewerDone?: (reviewerId: string) => void;
   planStore: ReviewPlanStore;
 }
-
 /** Typed batch outcome after validation and snapshot freshness checks. */
 export type RunAgentReviewWorkflowOutcome =
   | { kind: "completed"; details: AgentReviewBatchDetails }
   | { kind: "invalid"; reason: string }
   | { kind: "stale"; reason: string };
-
 /** Prepare one session-scoped review plan without starting reviewer sessions. */
 export async function prepareAgentReviewPlan(
   input: PrepareAgentReviewWorkflowInput,
@@ -74,15 +70,27 @@ export async function prepareAgentReviewPlan(
     };
   }
 
-  const synthesis = await synthesizeReviewBrief({
-    model: input.model,
-    cwd: input.cwd,
-    snapshot,
-    serializedContext: input.serializedContext,
-    note: input.note,
-    signal: input.signal,
-    onProgress: input.onProgress,
-  });
+  let synthesis: BriefSynthesisRunResult;
+  try {
+    synthesis = await synthesizeReviewBrief({
+      model: input.model,
+      cwd: input.cwd,
+      snapshot,
+      serializedContext: input.serializedContext,
+      note: input.note,
+      signal: input.signal,
+      onProgress: input.onProgress,
+    });
+  } catch {
+    return {
+      kind: "synthesis-failed",
+      result: {
+        kind: "failed",
+        failureCode: "unexpected-runner-failure",
+        diagnostics: createUnobservedChildFailureDiagnostics(),
+      },
+    };
+  }
   if (synthesis.kind !== "success") {
     return { kind: "synthesis-failed", result: synthesis };
   }
@@ -195,13 +203,14 @@ async function runAssignment(
       onProgress: (progress) => input.onReviewerProgress?.(assignment.id, progress),
     });
     return { assignment, result: compactReviewResult(normalizeReviewResult(rawResult)) };
-  } catch (error) {
+  } catch {
     return {
       assignment,
       result: {
         kind: "failed",
-        reason: `Reviewer session failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`,
+        failureCode: "unexpected-runner-failure",
         modelId: plan.model.canonicalId,
+        diagnostics: createUnobservedChildFailureDiagnostics(),
       },
     };
   }
@@ -212,21 +221,30 @@ function compactReviewResult(result: ReviewResult): AgentReviewerResult {
     case "success":
       return { kind: "success", output: result.output, modelId: result.modelId };
     case "failed":
+      return result.failureCode === "session-creation-failed"
+        ? {
+            kind: "failed",
+            failureCode: result.failureCode,
+            modelId: result.modelId,
+          }
+        : {
+            kind: "failed",
+            failureCode: result.failureCode,
+            modelId: result.modelId,
+            diagnostics: result.diagnostics,
+          };
+    case "canceled":
       return {
-        kind: "failed",
-        reason: result.reason,
+        kind: "canceled",
         modelId: result.modelId,
-        debug: result.debug,
+        diagnostics: result.diagnostics,
       };
-    case "canceled":
-      return { kind: "canceled", modelId: result.modelId, debug: result.debug };
     case "timeout":
       return {
         kind: "timeout",
         timeoutMs: result.timeoutMs,
-        partialOutput: result.partialOutput,
         modelId: result.modelId,
-        debug: result.debug,
+        diagnostics: result.diagnostics,
       };
   }
 }

package/src/tool/brief-runner.ts

@@ -11,7 +11,8 @@ import type {
   BriefSynthesisRunResult,
   SynthesizedReviewBrief,
 } from "../types.ts";
-import { buildProgressTokens, extractLastAssistantText } from "./runner-helpers.ts";
+import { createEarlyCancellationDiagnostics } from "./child-failure-diagnostics.ts";
+import { buildProgressTokens } from "./runner-helpers.ts";
 import { reviewBriefSchema } from "./schemas.ts";
 import { type LifecycleCtx, runWithLifecycle } from "./session-lifecycle.ts";
 
@@ -88,24 +89,19 @@ function emitBriefProgress(
 
 /** Finalize after retries and compaction recovery, never at the earlier `agent_end` boundary. */
 function handleAgentSettled(options: {
-  session: AgentSession;
   brief: SynthesizedReviewBrief | undefined;
   state: { settled: boolean; aborting: boolean };
   cleanup: (result: BriefSynthesisRunResult) => BriefSynthesisRunResult;
+  getFailureDiagnostics: LifecycleCtx<BriefSynthesisRunResult>["getFailureDiagnostics"];
 }): BriefSynthesisRunResult | undefined {
-  const { session, brief, state, cleanup } = options;
-  if (state.settled || state.aborting) {
-    return undefined;
-  }
-  if (brief) {
-    return cleanup({ kind: "success", brief });
-  }
-  const lastText = extractLastAssistantText(session.messages);
+  const { brief, state, cleanup, getFailureDiagnostics } = options;
+  if (state.settled || state.aborting) return undefined;
+  if (brief) return cleanup({ kind: "success", brief });
+
   return cleanup({
     kind: "failed",
-    reason: lastText
-      ? `Brief synthesizer did not call submit_review_brief. Assistant said: ${lastText}`
-      : "Brief synthesizer did not produce any output.",
+    failureCode: "missing-structured-output",
+    diagnostics: getFailureDiagnostics(),
   });
 }
 
@@ -114,7 +110,7 @@ export async function runBriefSynthesis(
   invocation: BriefSynthesisInvocation,
 ): Promise<BriefSynthesisRunResult> {
   if (invocation.signal?.aborted) {
-    return { kind: "canceled" };
+    return { kind: "canceled", diagnostics: createEarlyCancellationDiagnostics() };
   }
 
   const resultHolder: { value: SynthesizedReviewBrief | undefined } = { value: undefined };
@@ -123,11 +119,8 @@ export async function runBriefSynthesis(
   let session: AgentSession;
   try {
     session = await createBriefSession(invocation, submitBriefTool);
-  } catch (error) {
-    return {
-      kind: "failed",
-      reason: `Failed to create brief synthesis session: ${error instanceof Error ? error.message : String(error)}`,
-    };
+  } catch {
+    return { kind: "failed", failureCode: "session-creation-failed" };
   }
 
   return runWithLifecycle<BriefSynthesisRunResult>({
@@ -155,10 +148,10 @@ export async function runBriefSynthesis(
           break;
         case "agent_settled": {
           const result = handleAgentSettled({
-            session,
             brief: resultHolder.value,
             state: ctx.state,
             cleanup: ctx.cleanup,
+            getFailureDiagnostics: ctx.getFailureDiagnostics,
           });
           if (result) {
             ctx.resolve(result);
@@ -169,11 +162,19 @@ export async function runBriefSynthesis(
           break;
       }
     },
-    canceledResult: () => ({ kind: "canceled" as const }),
-    failedResult: (reason) => ({
+    canceledResult: (ctx) => ({
+      kind: "canceled" as const,
+      diagnostics: ctx.getFailureDiagnostics(),
+    }),
+    failedResult: (failureCode, ctx) => ({
       kind: "failed" as const,
-      reason,
+      failureCode,
+      diagnostics: ctx.getFailureDiagnostics(),
+    }),
+    timeoutResult: (ms, ctx) => ({
+      kind: "timeout" as const,
+      timeoutMs: ms,
+      diagnostics: ctx.getFailureDiagnostics(),
     }),
-    timeoutResult: (ms) => ({ kind: "timeout" as const, timeoutMs: ms }),
   });
 }

package/src/tool/child-failure-diagnostics.ts

@@ -0,0 +1,145 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type {
+  ChildFailureCode,
+  ChildFailureDiagnostics,
+  ChildStage,
+  ReviewProgress,
+} from "../types.ts";
+import {
+  type ChildLifecycleTrace,
+  ChildLifecycleTraceCollector,
+  formatChildLifecycleTrace,
+  getRegisteredToolNames,
+  toSafeAssistantStopReason,
+} from "./child-lifecycle-trace.ts";
+import { buildProgressTokens } from "./runner-helpers.ts";
+
+/** Inputs used to create one safe non-success child-run diagnostic artifact. */
+export interface BuildChildFailureDiagnosticsInput {
+  progress: ReviewProgress;
+  lifecycleTrace: ChildLifecycleTrace;
+  recentActivity: string[];
+  session?: AgentSession;
+}
+
+/** Build diagnostics from allowlisted control metadata only. */
+export function buildChildFailureDiagnostics(
+  input: BuildChildFailureDiagnosticsInput,
+): ChildFailureDiagnostics {
+  const { session } = input;
+  const tokens = session
+    ? buildProgressTokens(() => session.getSessionStats())
+    : input.progress.tokens;
+  const lastAssistant = session ? extractLastAssistantMetadata(session) : undefined;
+
+  return {
+    lifecycleTrace: input.lifecycleTrace,
+    turns: input.progress.turns,
+    toolUses: input.progress.toolUses,
+    tokens,
+    recentActivity: input.recentActivity.length > 0 ? [...input.recentActivity] : undefined,
+    lastAssistantStopReason: lastAssistant?.stopReason,
+    lastAssistantToolCalls: lastAssistant?.toolCalls,
+  };
+}
+
+/** Create safe diagnostics when a host failure occurred without observed child lifecycle events. */
+export function createUnobservedChildFailureDiagnostics(): ChildFailureDiagnostics {
+  return buildChildFailureDiagnostics({
+    progress: { turns: 0, toolUses: 0 },
+    lifecycleTrace: { entries: [], droppedCount: 0 },
+    recentActivity: [],
+  });
+}
+
+/** Create safe cancellation diagnostics when no child session was started. */
+export function createEarlyCancellationDiagnostics(): ChildFailureDiagnostics {
+  const collector = new ChildLifecycleTraceCollector();
+  collector.recordHostMarker({ type: "abort_requested", reason: "canceled" });
+  return buildChildFailureDiagnostics({
+    progress: { turns: 0, toolUses: 0 },
+    lifecycleTrace: collector.snapshot(),
+    recentActivity: collector.recentActivitySnapshot(),
+  });
+}
+
+/** Generate static parent-facing copy for a host-owned child failure code. */
+export function formatChildFailureCopy(stage: ChildStage, code: ChildFailureCode): string {
+  const label = stage === "brief-synthesis" ? "Brief synthesis" : "Reviewer";
+  switch (code) {
+    case "session-creation-failed":
+      return `${label} session could not be created.`;
+    case "prompt-rejected":
+      return `${label} prompt was rejected before it ran.`;
+    case "missing-structured-output":
+      return `${label} ended without the required structured output.`;
+    case "unexpected-runner-failure":
+      return `${label} ended unexpectedly.`;
+  }
+}
+
+/** Format the complete retained safe diagnostic artifact for parent-facing text. */
+export function formatChildFailureDiagnostics(diagnostics: ChildFailureDiagnostics): string[] {
+  const lines = [
+    `- Turns: ${diagnostics.turns}`,
+    `- Tool uses: ${diagnostics.toolUses}`,
+    diagnostics.tokens
+      ? `- Tokens: ${diagnostics.tokens.input} in / ${diagnostics.tokens.output} out / ${diagnostics.tokens.total} total`
+      : undefined,
+    diagnostics.recentActivity && diagnostics.recentActivity.length > 0
+      ? `- Recent activity: ${diagnostics.recentActivity.join(" → ")}`
+      : undefined,
+    diagnostics.lastAssistantStopReason
+      ? `- Last assistant stop: ${diagnostics.lastAssistantStopReason}`
+      : undefined,
+    diagnostics.lastAssistantToolCalls && diagnostics.lastAssistantToolCalls.length > 0
+      ? `- Last assistant tools: ${diagnostics.lastAssistantToolCalls.join(", ")}`
+      : undefined,
+    `- ${formatChildLifecycleTrace(diagnostics.lifecycleTrace)}`,
+  ];
+  return lines.filter((line): line is string => !!line);
+}
+
+interface LastAssistantMetadata {
+  stopReason?: string;
+  toolCalls?: string[];
+}
+
+function extractLastAssistantMetadata(session: AgentSession): LastAssistantMetadata | undefined {
+  try {
+    const messages = session.messages as unknown;
+    if (!Array.isArray(messages)) return undefined;
+
+    const registeredToolNames = getRegisteredToolNames(session);
+    for (let index = messages.length - 1; index >= 0; index--) {
+      const message = messages[index] as Record<string, unknown> | undefined;
+      if (message?.role !== "assistant") continue;
+
+      const stopReason = toSafeAssistantStopReason(message.stopReason);
+      const toolCalls = extractAssistantToolCalls(message.content, registeredToolNames);
+      return {
+        stopReason,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+      };
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function extractAssistantToolCalls(content: unknown, registeredToolNames: Set<string>): string[] {
+  if (!Array.isArray(content)) return [];
+
+  return content
+    .map((part) => {
+      if (typeof part !== "object" || !part) return undefined;
+      const tool = part as { type?: unknown; name?: unknown };
+      return tool.type === "toolCall" &&
+        typeof tool.name === "string" &&
+        registeredToolNames.has(tool.name)
+        ? tool.name
+        : undefined;
+    })
+    .filter((name): name is string => !!name);
+}