@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

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/find.ts

@@ -11,13 +11,15 @@ import {
   type ResultProvenance,
   type ToolResultAssembly,
 } from "./assembly.ts";
-import type { SearchDetails } from "./types.ts";
+import { createToolDisplaySection } from "./display.ts";
+import type { SearchDetails, ToolDisplaySection } from "./types.ts";
 
 /** Presentation-neutral assembled find result. */
 export interface FindResultAssembly {
   outcome: Extract<FindWorkflowOutcome, { kind: "completed" }>;
   assembled: ToolResultAssembly<Extract<FindWorkflowOutcome, { kind: "completed" }>["data"]>;
   details: SearchDetails;
+  displaySections: readonly ToolDisplaySection[];
 }
 
 /** Assemble one completed code-aware search outcome before presentation. */
@@ -26,13 +28,7 @@ export function assembleFindWorkflowResult(
 ): FindResultAssembly {
   const evidence = createFindEvidence(outcome);
   const confidence: ConfidenceMode = outcome.data.kind === "semantic" ? "semantic" : "structural";
-  const nextQueries =
-    outcome.data.kind === "ast" && outcome.data.astKind === "call"
-      ? [
-          "Use code_graph references on a resolved target for symbol-identity relationships",
-          "Use PI grep for literal or regex source matches when it is active",
-        ]
-      : ["Change mode only when you need a different code-aware evidence substrate"];
+  const nextQueries = findNextQueries(outcome);
   const provenance = findProvenance(outcome.data.kind);
   const assembled = assembleToolResult({
     data: outcome.data,
@@ -53,9 +49,22 @@ export function assembleFindWorkflowResult(
     provenance,
   });
 
+  const displaySections = [
+    createToolDisplaySection({
+      key: `find.${outcome.data.kind}`,
+      title: outcome.data.kind === "semantic" ? "Symbols" : "Matches",
+      items: findItems(outcome.data),
+      totalCount: evidence.metadata.totalCount,
+      omittedCount: evidence.metadata.omittedCount,
+      partialReason: evidence.metadata.partialReason,
+      format: (item) => formatFindDisplayItem(outcome.data.kind, item),
+    }),
+  ];
+
   return {
     outcome,
     assembled,
+    displaySections,
     details: {
       confidence,
       scope: outcome.scopeLabel === "." ? null : outcome.scopeLabel,
@@ -68,6 +77,22 @@ export function assembleFindWorkflowResult(
   };
 }
 
+function findNextQueries(outcome: Extract<FindWorkflowOutcome, { kind: "completed" }>): string[] {
+  if (outcome.data.kind === "semantic" && outcome.data.symbols.length === 0) {
+    return [
+      "If you know the file, use code_resolve with a file selector to enumerate document declarations",
+      "Change mode only when you need a different code-aware evidence substrate",
+    ];
+  }
+  if (outcome.data.kind === "ast" && outcome.data.astKind === "call") {
+    return [
+      "Use code_graph references on a resolved target for symbol-identity relationships",
+      "Use PI grep for literal or regex source matches when it is active",
+    ];
+  }
+  return ["Change mode only when you need a different code-aware evidence substrate"];
+}
+
 function createFindEvidence(outcome: Extract<FindWorkflowOutcome, { kind: "completed" }>): {
   total: number;
   metadata: EvidenceListMetadata;
@@ -106,6 +131,25 @@ function findItems(
   return data.kind === "semantic" ? data.symbols : data.result.matches;
 }
 
+function formatFindDisplayItem(kind: "semantic" | "ast", item: unknown): string {
+  if (kind === "ast") {
+    const match = item as { name: string; kind: string; file: string; line: number };
+    return `${match.name} (${match.kind}) — ${match.file}:L${match.line}`;
+  }
+
+  const symbol = item as {
+    name: string;
+    kind: string;
+    file: string;
+    container?: string | null;
+    nameAnchor?: { line: number };
+    declarationAnchor: { line: number };
+  };
+  const container = symbol.container ? ` in ${symbol.container}` : "";
+  const anchor = symbol.nameAnchor ?? symbol.declarationAnchor;
+  return `${symbol.name} [${symbol.kind}]${container} — ${symbol.file}:L${anchor.line}`;
+}
+
 function findProvenance(
   kind: Extract<FindWorkflowOutcome, { kind: "completed" }>["data"]["kind"],
 ): ResultProvenance[] {

package/src/tool/result/graph.ts

@@ -6,6 +6,7 @@ import type {
   ImplementationEntry,
   ReferenceEntry,
 } from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
 import type { GraphSection } from "../../session/graph-types.ts";
 import {
   assembledNextQueries,
@@ -13,7 +14,8 @@ import {
   type ResultProvenance,
   type ToolResultAssembly,
 } from "./assembly.ts";
-import type { SearchDetails } from "./types.ts";
+import { createToolDisplaySection } from "./display.ts";
+import type { SearchDetails, ToolDisplaySection } from "./types.ts";
 
 export type { GraphRelationKind, GraphSection } from "../../session/graph-types.ts";
 
@@ -39,6 +41,7 @@ export interface GraphResultAssembly {
   cwd: string;
   assembled: ToolResultAssembly<{ readonly sections: readonly AssembledGraphSection[] }>;
   details: SearchDetails;
+  displaySections: readonly ToolDisplaySection[];
 }
 
 /** Assemble graph evidence once before either presentation adapter consumes it. */
@@ -77,12 +80,15 @@ export function assembleGraphResult(input: {
     provenance,
   });
 
+  const displaySections = sections.map((section) => graphDisplaySection(section, input.cwd));
+
   return {
     displayName: input.displayName,
     sections,
     resolvedDisplayFile: input.resolvedDisplayFile,
     cwd: input.cwd,
     assembled,
+    displaySections,
     details: {
       confidence,
       scope: null,
@@ -94,6 +100,43 @@ export function assembleGraphResult(input: {
   };
 }
 
+function graphDisplaySection(section: AssembledGraphSection, cwd: string): ToolDisplaySection {
+  if (section.kind === "unavailable") {
+    return createToolDisplaySection({
+      key: `graph.${section.rel}`,
+      title: section.rel,
+      items: [section.message],
+      format: (message) => `Unavailable — ${message}`,
+      totalCount: 1,
+    });
+  }
+
+  return createToolDisplaySection({
+    key: `graph.${section.rel}`,
+    title: section.rel,
+    items: section.evidence.items as readonly unknown[],
+    totalCount: section.evidence.metadata.totalCount,
+    omittedCount: section.evidence.metadata.omittedCount,
+    partialReason: section.evidence.metadata.partialReason,
+    format: (item) => formatGraphDisplayItem(section.rel, item, cwd),
+  });
+}
+
+function formatGraphDisplayItem(
+  relation: "references" | "callees" | "implements",
+  item: unknown,
+  cwd: string,
+): string {
+  if (relation === "callees") {
+    const call = item as { name: string; file: string; line: number };
+    return `${call.name} — ${toDisplayPath(cwd, call.file)}:L${call.line}`;
+  }
+
+  const location = item as { name: string | null; file: string; line: number; character: number };
+  const name = location.name ? `${location.name} — ` : "";
+  return `${name}${toDisplayPath(cwd, location.file)}:L${location.line}:${location.character}`;
+}
+
 function assembleGraphSection(section: GraphSection, maxResults: number): AssembledGraphSection {
   if (section.kind === "unavailable") return section;
   switch (section.rel) {

package/src/tool/result/health.ts

@@ -6,7 +6,8 @@ import {
   type ResultSection,
   type ToolResultAssembly,
 } from "./assembly.ts";
-import type { HealthDetails, HealthSectionDetails } from "./types.ts";
+import { createToolDisplaySection, truncateDisplayText } from "./display.ts";
+import type { HealthDetails, HealthSectionDetails, ToolDisplaySection } from "./types.ts";
 
 export type {
   HealthData,
@@ -26,6 +27,7 @@ export interface HealthResultAssembly {
   data: HealthData;
   assembled: ToolResultAssembly<HealthData>;
   details: HealthDetails;
+  displaySections: readonly ToolDisplaySection[];
 }
 
 const SECTION_TITLES: Record<HealthSection, string> = {
@@ -53,9 +55,12 @@ export function assembleHealthResult(data: HealthData): HealthResultAssembly {
     provenance,
   });
 
+  const displaySections = buildHealthDisplaySections(data);
+
   return {
     data,
     assembled,
+    displaySections,
     details: {
       includedSections: [...data.includedSections],
       sections: sectionDetails,
@@ -78,6 +83,53 @@ export function assembleHealthResult(data: HealthData): HealthResultAssembly {
   };
 }
 
+function buildHealthDisplaySections(data: HealthData): ToolDisplaySection[] {
+  const sections: ToolDisplaySection[] = [];
+
+  if (data.includedSections.includes("diagnostics") && data.diagnostics.entries.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "health.diagnostics",
+        title: "Diagnostics",
+        items: data.diagnostics.entries,
+        totalCount: data.diagnostics.kind === "completed" ? data.diagnostics.entries.length : null,
+        omittedCount: data.diagnostics.kind === "completed" ? 0 : null,
+        partialReason: diagnosticPartialReason(data),
+        format: formatDiagnosticEntry,
+      }),
+    );
+  }
+
+  if (data.includedSections.includes("servers") && data.servers.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "health.servers",
+        title: "Servers",
+        items: data.servers,
+        totalCount: data.servers.length,
+        format: (server) => `${server.name} (${server.fileTypes.join(", ")}) — ${server.status}`,
+      }),
+    );
+  }
+
+  return sections;
+}
+
+function diagnosticPartialReason(data: HealthData): string | null {
+  return data.diagnostics.kind === "partial" || data.diagnostics.kind === "unavailable"
+    ? data.diagnostics.reason
+    : null;
+}
+
+function formatDiagnosticEntry(entry: HealthData["diagnostics"]["entries"][number]): string {
+  const summary = `${entry.file} — ${entry.errors} error${entry.errors === 1 ? "" : "s"}, ${entry.warnings} warning${entry.warnings === 1 ? "" : "s"}`;
+  const messages = entry.messages?.map(
+    (message) =>
+      `  ${message.severity} L${message.line}${message.source ? ` [${message.source}]` : ""}: ${truncateDisplayText(message.message, 200)}`,
+  );
+  return messages && messages.length > 0 ? [summary, ...messages].join("\n") : summary;
+}
+
 interface HealthSectionFacts {
   status: "complete" | "partial" | "unavailable";
   available: boolean;

package/src/tool/result/inspect.ts

@@ -17,7 +17,8 @@ import {
   type ResultSection,
   type ToolResultAssembly,
 } from "./assembly.ts";
-import type { InspectDetails, InspectSectionDetails } from "./types.ts";
+import { createToolDisplaySection, truncateDisplayText } from "./display.ts";
+import type { InspectDetails, InspectSectionDetails, ToolDisplaySection } from "./types.ts";
 
 export type { InspectResultData } from "../../session/inspect-types.ts";
 
@@ -30,6 +31,7 @@ export interface InspectResultAssembly {
   diagnosticEvidence: EvidenceList<InspectDiagnostic> | null;
   assembled: ToolResultAssembly<InspectResultData>;
   details: InspectDetails;
+  displaySections: readonly ToolDisplaySection[];
 }
 
 /** Assemble code_inspect evidence/details before presentation adapters render it. */
@@ -62,6 +64,14 @@ export function assembleInspectResult(
     provenance,
   });
 
+  const displaySections = buildInspectDisplaySections({
+    data,
+    displayedDefinitions: definitionEvidence?.items ?? [],
+    displayedDiagnostics: diagnosticEvidence?.items ?? [],
+    definitionEvidence,
+    diagnosticEvidence,
+  });
+
   return {
     data,
     displayedDefinitions: definitionEvidence?.items ?? [],
@@ -69,6 +79,7 @@ export function assembleInspectResult(
     definitionEvidence,
     diagnosticEvidence,
     assembled,
+    displaySections,
     details: {
       confidence: data.confidence,
       focusTarget: `${data.relPath}:${data.line}:${data.character}`,
@@ -80,6 +91,107 @@ export function assembleInspectResult(
   };
 }
 
+function buildInspectDisplaySections(input: {
+  data: InspectResultData;
+  displayedDefinitions: readonly InspectDefinition[];
+  displayedDiagnostics: readonly InspectDiagnostic[];
+  definitionEvidence: EvidenceList<InspectDefinition> | null;
+  diagnosticEvidence: EvidenceList<InspectDiagnostic> | null;
+}): ToolDisplaySection[] {
+  const sections: ToolDisplaySection[] = [];
+  const { data } = input;
+
+  if (data.sections.node.kind !== "unavailable" && data.sections.node.data) {
+    const node = data.sections.node.data;
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.node",
+        title: "Syntax node",
+        items: [node],
+        format: (item) =>
+          `${item.type} at ${data.relPath}:${item.startLine}:${item.startCharacter}–${item.endLine}:${item.endCharacter}${item.text ? ` — ${truncateDisplayText(item.text, 160)}` : ""}`,
+        partialReason: observationReason(data.sections.node),
+      }),
+    );
+  }
+
+  if (data.sections.enclosingSymbol.kind !== "unavailable" && data.sections.enclosingSymbol.data) {
+    const symbol = data.sections.enclosingSymbol.data;
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.enclosingSymbol",
+        title: "Enclosing symbol",
+        items: [symbol],
+        format: (item) =>
+          `${item.name} (${item.kind}) L${item.startLine}:${item.startCharacter}–L${item.endLine}:${item.endCharacter}`,
+        partialReason: observationReason(data.sections.enclosingSymbol),
+      }),
+    );
+  }
+
+  if (data.sections.hover.kind !== "unavailable" && data.sections.hover.data) {
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.hover",
+        title: "Hover",
+        items: [data.sections.hover.data],
+        format: (hover) => truncateDisplayText(hover, 240),
+        partialReason: observationReason(data.sections.hover),
+      }),
+    );
+  }
+
+  if (input.displayedDefinitions.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.definitions",
+        title: "Definitions",
+        items: input.displayedDefinitions,
+        totalCount: input.definitionEvidence?.metadata.totalCount,
+        omittedCount: input.definitionEvidence?.metadata.omittedCount,
+        partialReason: input.definitionEvidence?.metadata.partialReason,
+        format: (definition) => `${definition.file}:${definition.line}:${definition.character}`,
+      }),
+    );
+  }
+
+  if (input.displayedDiagnostics.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.diagnostics",
+        title: "Diagnostics",
+        items: input.displayedDiagnostics,
+        totalCount: input.diagnosticEvidence?.metadata.totalCount,
+        omittedCount: input.diagnosticEvidence?.metadata.omittedCount,
+        partialReason: input.diagnosticEvidence?.metadata.partialReason,
+        format: (diagnostic) =>
+          `L${diagnostic.line}:${diagnostic.character} ${formatDiagnosticSeverity(diagnostic.severity)}: ${truncateDisplayText(diagnostic.message, 200)}`,
+      }),
+    );
+  }
+
+  return sections;
+}
+
+function observationReason<T>(observation: InspectObservation<T>): string | null {
+  return observation.kind === "partial" ? observation.reason : null;
+}
+
+function formatDiagnosticSeverity(severity: number): string {
+  switch (severity) {
+    case 1:
+      return "Error";
+    case 2:
+      return "Warning";
+    case 3:
+      return "Info";
+    case 4:
+      return "Hint";
+    default:
+      return "Diagnostic";
+  }
+}
+
 function listEvidence<T>(
   key: string,
   observation: InspectObservation<readonly T[]>,

package/src/tool/result/orientation.ts

@@ -3,6 +3,7 @@ import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
 import type { ReadNextItem } from "../../analysis/read-next.ts";
 import type {
   OrientationCandidate,
+  OrientationItem,
   OrientationResultData,
   OrientationSectionData,
 } from "../../session/orientation-types.ts";
@@ -14,7 +15,8 @@ import {
   type ResultSection,
   type ToolResultAssembly,
 } from "./assembly.ts";
-import type { ContextDetails, OrientationSectionDetails } from "./types.ts";
+import { createToolDisplaySection } from "./display.ts";
+import type { ContextDetails, OrientationSectionDetails, ToolDisplaySection } from "./types.ts";
 
 export interface OrientationDetailsInput {
   readonly confidence: ConfidenceMode;
@@ -35,6 +37,25 @@ export interface OrientationDetailsInput {
 export interface OrientationResultAssembly {
   readonly assembled: ToolResultAssembly<OrientationResultData>;
   readonly details: ContextDetails;
+  readonly displaySections: readonly ToolDisplaySection[];
+}
+
+/** Build structured candidate rows for an unresolved Orientation target. */
+export function orientationCandidateDisplaySections(
+  candidates: readonly OrientationCandidate[],
+  omittedCount = 0,
+): readonly ToolDisplaySection[] {
+  return [
+    createToolDisplaySection({
+      key: "orientation.candidates",
+      title: "Candidates",
+      items: candidates,
+      totalCount: candidates.length + omittedCount,
+      omittedCount,
+      format: (candidate) =>
+        `${candidate.rank}. ${candidate.name} (${candidate.kind ?? "unknown"}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`,
+    }),
+  ];
 }
 
 /** Assemble Orientation facts and shared result policy before rendering. */
@@ -50,21 +71,24 @@ export function assembleOrientationResult(data: OrientationResultData): Orientat
     confidence: data.confidence,
     provenance: uniqueProvenance(data.sections),
   });
+  const details = assembleOrientationDetails({
+    confidence: assembled.confidence,
+    focusTarget: assembled.data.focusTarget,
+    requestedSections: assembled.data.requestedSections,
+    renderedSections: assembled.data.renderedSections,
+    omittedCount: assembled.totals.omittedCount,
+    evidenceLists: assembled.evidenceLists,
+    sections: assembled.data.sections,
+    nextQueries: assembledNextQueries(assembled),
+    readNext: assembledReadNext(assembled),
+    target: assembled.data.target,
+    instructions: assembled.data.instructions,
+  });
+
   return {
     assembled,
-    details: assembleOrientationDetails({
-      confidence: assembled.confidence,
-      focusTarget: assembled.data.focusTarget,
-      requestedSections: assembled.data.requestedSections,
-      renderedSections: assembled.data.renderedSections,
-      omittedCount: assembled.totals.omittedCount,
-      evidenceLists: assembled.evidenceLists,
-      sections: assembled.data.sections,
-      nextQueries: assembledNextQueries(assembled),
-      readNext: assembledReadNext(assembled),
-      target: assembled.data.target,
-      instructions: assembled.data.instructions,
-    }),
+    details,
+    displaySections: assembled.data.sections.map(orientationDisplaySection),
   };
 }
 
@@ -96,6 +120,34 @@ export function assembleOrientationDetails(input: OrientationDetailsInput): Cont
   };
 }
 
+function orientationDisplaySection(section: OrientationSectionData): ToolDisplaySection {
+  const items = section.items.filter((item) => item.kind !== "blank");
+  return createToolDisplaySection({
+    key: `orientation.${section.key}`,
+    title: section.title,
+    items,
+    totalCount: items.length,
+    omittedCount: 0,
+    partialReason:
+      section.reason ??
+      section.evidenceLists.find((evidence) => evidence.partialReason)?.partialReason,
+    format: formatOrientationItem,
+  });
+}
+
+function formatOrientationItem(item: OrientationItem): string {
+  switch (item.kind) {
+    case "paragraph":
+    case "list-item":
+    case "subheading":
+      return item.text;
+    case "code":
+      return item.lines.join(" ");
+    case "blank":
+      return "";
+  }
+}
+
 function toResultSection(section: OrientationSectionData): ResultSection {
   return {
     key: section.key,