@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/tool/register.ts

@@ -1,73 +1,15 @@
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { createHmac, randomBytes } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Component } from "@earendil-works/pi-tui";
+import { recordDebugEvent, startDebugTimer } from "@mrclrchtr/supi-core/debug";
+import { truncateIdentity } from "@mrclrchtr/supi-lsp/debug-telemetry";
 import type { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
-import { renderFindCall, renderFindResult } from "./find/tui.ts";
-import { renderGraphCall, renderGraphResult } from "./graph/tui.ts";
 import {
   CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
   type CodeIntelligenceToolPromptSurfaceMap,
 } from "./guidance.ts";
-import { renderHealthCall, renderHealthResult } from "./health/tui.ts";
-import { truncateToolContent } from "./infra/truncate.ts";
-import { renderInspectCall, renderInspectResult } from "./inspect/tui.ts";
-import { renderOrientationCall, renderOrientationResult } from "./orientation/tui.ts";
-import { renderRefactorApplyCall, renderRefactorApplyResult } from "./refactor-apply/tui.ts";
-import { renderRefactorPlanCall, renderRefactorPlanResult } from "./refactor-plan/tui.ts";
-import { renderResolveCall, renderResolveResult } from "./resolve/tui.ts";
+import { boundCodeToolResult } from "./infra/truncate.ts";
 import { CODE_INTELLIGENCE_TOOL_SPECS, type CodeIntelligenceToolDefinitionSpec } from "./specs.ts";
 
-const TOOL_OUTPUT_CONTRACT =
-  " Output over 2000 lines or 50KB is truncated, with full Markdown saved to a temporary file.";
-
-interface ToolRenderer {
-  // biome-ignore lint/suspicious/noExplicitAny: pi render call/result signatures vary per tool; spread into pi.registerTool where concrete typing handles variance
-  renderCall?: (...args: any[]) => Component;
-  // biome-ignore lint/suspicious/noExplicitAny: same variance reason as renderCall
-  renderResult?: (...args: any[]) => Component;
-  renderShell?: "self";
-}
-
-function getToolRenderer(name: string): ToolRenderer {
-  switch (name) {
-    case "code_graph":
-      return {
-        renderCall: renderGraphCall,
-        renderResult: renderGraphResult,
-      };
-    case "code_health":
-      return {
-        renderCall: renderHealthCall,
-        renderResult: renderHealthResult,
-      };
-    case "code_orientation":
-      return {
-        renderCall: renderOrientationCall,
-        renderResult: renderOrientationResult,
-      };
-    case "code_resolve":
-      return { renderCall: renderResolveCall, renderResult: renderResolveResult };
-    case "code_inspect":
-      return { renderCall: renderInspectCall, renderResult: renderInspectResult };
-    case "code_find":
-      return { renderCall: renderFindCall, renderResult: renderFindResult };
-    case "code_refactor_plan":
-      return {
-        renderCall: renderRefactorPlanCall,
-        renderResult: renderRefactorPlanResult,
-      };
-    case "code_refactor_apply":
-      return {
-        renderCall: renderRefactorApplyCall,
-        renderResult: renderRefactorApplyResult,
-      };
-    default:
-      return {};
-  }
-}
-
 /**
  * Register the focused code-intelligence tool surface from shared specs.
  *
@@ -76,6 +18,65 @@ function getToolRenderer(name: string): ToolRenderer {
  */
 const registeredPis = new WeakSet<object>();
 
+type CodeOperationOutcome = "completed" | "failed" | "canceled";
+
+function createDebugOperationId(secret: Buffer, toolCallId: string): string {
+  const digest = createHmac("sha256", secret).update(toolCallId).digest().subarray(0, 16);
+  return `op-${digest.toString("base64url")}`;
+}
+
+function recordCodeOperationBoundary(
+  category: "code-operation.start" | "code-operation.finish",
+  operationId: string,
+  tool: string,
+  options: { cwd: string; outcome?: CodeOperationOutcome },
+): void {
+  recordDebugEvent({
+    operationId,
+    source: "code-intelligence",
+    level: "debug",
+    category,
+    message:
+      category === "code-operation.start" ? "Code operation started" : "Code operation finished",
+    cwd: truncateIdentity(options.cwd),
+    data: options.outcome ? { tool, outcome: options.outcome } : { tool },
+  });
+}
+
+function recordCodeWorkflowTiming(
+  timer: ReturnType<typeof startDebugTimer>,
+  operationId: string,
+  tool: string,
+  options: { cwd: string; outcome: CodeOperationOutcome },
+): void {
+  timer.finish(
+    {
+      operationId,
+      source: "code-intelligence",
+      level: "debug",
+      category: "workflow.timing",
+      message: "Code workflow finished",
+      cwd: truncateIdentity(options.cwd),
+      data: { tool, outcome: options.outcome },
+    },
+    "workflow",
+  );
+}
+
+function terminalCodeOperationOutcome(
+  error: unknown,
+  signal: AbortSignal | undefined,
+): CodeOperationOutcome {
+  if (signal?.aborted) return "canceled";
+  if (
+    error instanceof Error &&
+    (error.name === "AbortError" || error.name === "CodeRequestDeadlineError")
+  ) {
+    return "canceled";
+  }
+  return "failed";
+}
+
 export function registerCodeIntelligenceTools(
   pi: ExtensionAPI,
   getOrCreateSession: (cwd: string) => WorkspaceCodeIntelligenceSession,
@@ -89,46 +90,62 @@ export function registerCodeIntelligenceTools(
   // ponytail: WeakSet on pi identity; getAllTools() is not callable during load.
   if (registeredPis.has(pi)) return;
   registeredPis.add(pi);
+  const operationSecret = randomBytes(32);
 
   for (const spec of specs) {
     const surface = promptSurfaces[spec.name];
     pi.registerTool({
       name: spec.name,
       label: spec.label,
-      description: surface.description + TOOL_OUTPUT_CONTRACT,
+      description: surface.description,
       promptSnippet: surface.promptSnippet,
       promptGuidelines: surface.promptGuidelines,
       parameters: spec.parameters,
       // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-      execute: async (_toolCallId, params, signal, onUpdate, ctx: ExtensionContext) => {
-        const session = getOrCreateSession(ctx.cwd);
-        session.setProjectTrusted(ctx.isProjectTrusted());
-        const { content, details } = await spec.run(params, {
+      execute: async (toolCallId, params, signal, onUpdate, ctx: ExtensionContext) => {
+        const operationId = createDebugOperationId(operationSecret, toolCallId);
+        const workflowTimer = startDebugTimer();
+        recordCodeOperationBoundary("code-operation.start", operationId, spec.name, {
           cwd: ctx.cwd,
-          signal,
-          onUpdate,
-          session,
-        });
-        const { text, truncated } = truncateToolContent(content, {
-          maxLines: spec.maxLines,
-          maxBytes: spec.maxBytes,
         });
-        if (truncated && content.length > 0) {
-          const dir = mkdtempSync(join(tmpdir(), "supi-ci-"));
-          const spillPath = join(dir, `${spec.name}-output.md`);
-          writeFileSync(spillPath, content, "utf-8");
-          const notice = `\n_Full output saved to: \`${spillPath}\`_`;
-          return {
-            content: [{ type: "text" as const, text: text + notice }],
-            details,
-          };
+        try {
+          const session = getOrCreateSession(ctx.cwd);
+          session.setProjectTrusted(ctx.isProjectTrusted());
+          const { content, details } = await spec.run(params, {
+            cwd: ctx.cwd,
+            operationId,
+            signal,
+            onUpdate,
+            session,
+          });
+          recordCodeWorkflowTiming(workflowTimer, operationId, spec.name, {
+            cwd: ctx.cwd,
+            outcome: "completed",
+          });
+          recordCodeOperationBoundary("code-operation.finish", operationId, spec.name, {
+            cwd: ctx.cwd,
+            outcome: "completed",
+          });
+          return boundCodeToolResult(content, details, {
+            toolName: spec.name,
+            maxLines: spec.maxLines,
+            maxBytes: spec.maxBytes,
+          });
+        } catch (error) {
+          const outcome = terminalCodeOperationOutcome(error, signal);
+          recordCodeWorkflowTiming(workflowTimer, operationId, spec.name, {
+            cwd: ctx.cwd,
+            outcome,
+          });
+          recordCodeOperationBoundary("code-operation.finish", operationId, spec.name, {
+            cwd: ctx.cwd,
+            outcome,
+          });
+          throw error;
         }
-        return {
-          content: [{ type: "text" as const, text }],
-          details,
-        };
       },
-      ...getToolRenderer(spec.name),
+      renderCall: spec.renderCall,
+      renderResult: spec.renderResult,
     });
   }
 }

package/src/tool/result/display.ts

@@ -0,0 +1,107 @@
+import type { ToolDisplaySection } from "./types.ts";
+
+/** Maximum number of rows shown for one expanded TUI section. */
+export const MAX_TUI_DISPLAY_ITEMS = 20;
+
+/** Maximum visible characters kept in one structured TUI row. */
+export const MAX_TUI_DISPLAY_LINE_LENGTH = 240;
+
+/** Inputs for one bounded structured TUI section. */
+export interface ToolDisplaySectionInput<T> {
+  key: string;
+  title: string;
+  items: readonly T[];
+  format: (item: T) => string;
+  totalCount?: number | null;
+  omittedCount?: number | null;
+  partialReason?: string | null;
+  maxItems?: number;
+}
+
+/** Build a bounded, serializable TUI section from collected facts. */
+export function createToolDisplaySection<T>(input: ToolDisplaySectionInput<T>): ToolDisplaySection {
+  const maxItems = Math.max(0, input.maxItems ?? MAX_TUI_DISPLAY_ITEMS);
+  const items = input.items.slice(0, maxItems);
+  const lines = items.map((item) => truncateDisplayText(input.format(item)));
+  const displayOmittedCount = Math.max(0, input.items.length - items.length);
+  let totalCount: number | null;
+  if (input.totalCount === undefined) totalCount = input.items.length;
+  else totalCount = input.totalCount;
+  const omittedCount =
+    totalCount === null
+      ? input.omittedCount === null || input.omittedCount === undefined
+        ? displayOmittedCount || null
+        : input.omittedCount + displayOmittedCount
+      : Math.max(0, totalCount - lines.length);
+
+  return {
+    key: input.key,
+    title: input.title,
+    lines,
+    shownCount: lines.length,
+    totalCount,
+    omittedCount,
+    partialReason: input.partialReason ?? null,
+  };
+}
+
+/** Keep structured TUI rows readable without parsing or emitting Markdown. */
+export function truncateDisplayText(
+  value: string,
+  maxLength = MAX_TUI_DISPLAY_LINE_LENGTH,
+): string {
+  const limit = Math.max(1, maxLength);
+  return value
+    .split("\n")
+    .map((line) => {
+      if (line.length <= limit) return line;
+      return `${line.slice(0, Math.max(0, limit - 1))}…`;
+    })
+    .join("\n");
+}
+
+/** Read valid structured TUI sections from persisted tool details. */
+export function readToolDisplaySections(value: unknown): ToolDisplaySection[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return [];
+    const record = entry as Record<string, unknown>;
+    if (
+      typeof record.key !== "string" ||
+      typeof record.title !== "string" ||
+      !Array.isArray(record.lines) ||
+      !record.lines.every((line) => typeof line === "string") ||
+      !isCount(record.shownCount) ||
+      !isNullableCount(record.totalCount) ||
+      !isNullableCount(record.omittedCount) ||
+      !isNullableString(record.partialReason)
+    ) {
+      return [];
+    }
+    return [
+      {
+        key: record.key,
+        title: record.title,
+        lines: record.lines
+          .slice(0, MAX_TUI_DISPLAY_ITEMS)
+          .map((line) => truncateDisplayText(line)),
+        shownCount: record.shownCount,
+        totalCount: record.totalCount,
+        omittedCount: record.omittedCount,
+        partialReason: record.partialReason,
+      },
+    ];
+  });
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isNullableCount(value: unknown): value is number | null {
+  return value === null || isCount(value);
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}

package/src/tool/result/errors.ts

@@ -1,20 +1,14 @@
-/**
- * Tool-result error assembly factories for code-intelligence tool executors.
- *
- * Every factory returns a complete {@link CodeIntelResult} (content + typed
- * details) so executors never need to inline the `{ content, details }`
- * wrapper. Returned tool errors are result assembly concerns; whole-tool
- * capability failures may still throw so PI marks the tool call as failed.
- */
+import type { CodeIntelResult, ToolDisplaySection } from "../../types/index.ts";
 
-import type { CodeIntelResult } from "../../types/index.ts";
-
-// ── Error-result factories ──────────────────────────────────────────
-
-/** Full error result for search-family tools (code_find, code_graph, code_refactor_plan). */
+/** Full error result for search-family tools. */
 export function searchErrorResult(
   content: string,
-  opts?: { scope?: string | null; nextQueries?: string[] },
+  opts?: {
+    scope?: string | null;
+    nextQueries?: string[];
+    message?: string;
+    displaySections?: readonly ToolDisplaySection[];
+  },
 ): CodeIntelResult {
   return {
     content,
@@ -27,14 +21,17 @@ export function searchErrorResult(
         omittedCount: 0,
         nextQueries: opts?.nextQueries ?? [],
       },
+      status: "invalid-input",
+      ...(opts?.message ? { message: opts.message } : {}),
+      ...(opts?.displaySections ? { displaySections: opts.displaySections } : {}),
     },
   };
 }
 
-/** Full error result for code_orientation (context-type details). */
+/** Full error result for code_orientation. */
 export function contextErrorResult(
   content: string,
-  opts?: { nextQueries?: string[] },
+  opts?: { nextQueries?: string[]; message?: string },
 ): CodeIntelResult {
   return {
     content,
@@ -49,6 +46,8 @@ export function contextErrorResult(
         omittedCount: 0,
         nextQueries: opts?.nextQueries ?? [],
       },
+      status: "invalid-input",
+      ...(opts?.message ? { message: opts.message } : {}),
     },
   };
 }
@@ -56,7 +55,7 @@ export function contextErrorResult(
 /** Full error result for code_inspect. */
 export function inspectErrorResult(
   content: string,
-  opts?: { focusTarget?: string; nextQueries?: string[] },
+  opts?: { focusTarget?: string; nextQueries?: string[]; message?: string },
 ): CodeIntelResult {
   return {
     content,
@@ -69,6 +68,8 @@ export function inspectErrorResult(
         sections: [],
         nextQueries: opts?.nextQueries ?? [],
       },
+      status: "invalid-input",
+      ...(opts?.message ? { message: opts.message } : {}),
     },
   };
 }
@@ -100,6 +101,8 @@ export function healthErrorResult(content: string, reason?: string): CodeIntelRe
         diagnosticFileCount: 0,
         serverCount: 0,
       },
+      status: "invalid-input",
+      message: reason ?? content,
     },
   };
 }

package/src/tool/result/refactor.ts

@@ -3,7 +3,8 @@ import { createEvidenceList, type EvidenceList } from "../../analysis/evidence.t
 import type { ApplyResult } from "../../analysis/refactor/apply.ts";
 import type { RefactorPlan } from "../../session/refactor-plans.ts";
 import { assembledNextQueries, assembleToolResult, type ToolResultAssembly } from "./assembly.ts";
-import type { SearchDetails } from "./types.ts";
+import { createToolDisplaySection } from "./display.ts";
+import type { SearchDetails, ToolDisplaySection } from "./types.ts";
 
 export interface RefactorPlanAssemblyData {
   readonly plan: Readonly<RefactorPlan>;
@@ -14,6 +15,7 @@ export interface RefactorPlanAssemblyData {
 export interface RefactorPlanResultAssembly {
   readonly assembled: ToolResultAssembly<RefactorPlanAssemblyData>;
   readonly details: SearchDetails;
+  readonly displaySections: readonly ToolDisplaySection[];
 }
 
 export interface RefactorApplyAssemblyData {
@@ -24,6 +26,13 @@ export interface RefactorApplyAssemblyData {
 export interface RefactorApplyResultAssembly {
   readonly assembled: ToolResultAssembly<RefactorApplyAssemblyData>;
   readonly details: SearchDetails;
+  readonly displaySections: readonly ToolDisplaySection[];
+}
+
+function formatEdit(edit: FileEdit): string {
+  const range = edit.range;
+  const replacement = edit.newText.replace(/\n/g, " ↵ ");
+  return `${edit.file} L${range.start.line + 1}:${range.start.character + 1} → L${range.end.line + 1}:${range.end.character + 1}: ${replacement}`;
 }
 
 /** Assemble a bounded refactor plan and all facts needed by its renderers. */
@@ -59,6 +68,17 @@ export function assembleRefactorPlanDetails(
 
   return {
     assembled,
+    displaySections: [
+      createToolDisplaySection({
+        key: "refactor.edits",
+        title: "Proposed edits",
+        items: edits.items,
+        totalCount: edits.metadata.totalCount,
+        omittedCount: edits.metadata.omittedCount,
+        partialReason: edits.metadata.partialReason,
+        format: formatEdit,
+      }),
+    ],
     details: {
       confidence: assembled.confidence,
       scope: null,
@@ -89,17 +109,28 @@ export function assembleRefactorApplyDetails(
         provenance,
       },
     ],
-    nextQueries:
-      applyResult.kind === "applied"
-        ? ["Use code_health to check for new issues after the refactor"]
-        : [],
+    nextQueries: [],
     candidateCount,
     confidence: applyResult.kind === "applied" ? "semantic" : "unavailable",
     provenance,
   });
 
+  const changedFiles = [...new Set(plan.edits.edits.map((edit) => edit.file))];
+
   return {
     assembled,
+    displaySections:
+      applyResult.kind === "applied"
+        ? [
+            createToolDisplaySection({
+              key: "refactor.changedFiles",
+              title: "Changed files",
+              items: changedFiles,
+              totalCount: changedFiles.length,
+              format: (file) => file,
+            }),
+          ]
+        : [],
     details: {
       confidence: assembled.confidence,
       scope: null,
@@ -107,9 +138,7 @@ export function assembleRefactorApplyDetails(
       omittedCount: assembled.totals.omittedCount,
       evidenceLists: [...assembled.evidenceLists],
       nextQueries: assembledNextQueries(assembled),
-      ...(applyResult.kind === "applied"
-        ? { changedFiles: [...new Set(plan.edits.edits.map((edit) => edit.file))] }
-        : {}),
+      ...(applyResult.kind === "applied" ? { changedFiles } : {}),
     },
   };
 }

package/src/tool/result/types.ts

@@ -19,6 +19,26 @@ import type {
 } from "../../session/target-store.ts";
 import type { ResultProvenance } from "./assembly.ts";
 
+/** Final state for a public tool result. */
+export type ToolResultStatus = "completed" | "invalid-input" | "disambiguation" | "unavailable";
+
+/** Truncation state for model-facing tool content. */
+export interface ToolOutputTruncationDetails {
+  truncated: boolean;
+  fullOutputPath?: string;
+}
+
+/** Bounded, structured rows for the expanded TUI body. */
+export interface ToolDisplaySection {
+  key: string;
+  title: string;
+  lines: readonly string[];
+  shownCount: number;
+  totalCount: number | null;
+  omittedCount: number | null;
+  partialReason: string | null;
+}
+
 // ── Anchored coordinate resolution metadata ───────────────────────────
 
 /**