@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

package/src/tool/code_orientation/tui.ts

@@ -1,6 +1,7 @@
 /** TUI renderer for code_orientation. */
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { type Component, Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { renderCandidateSelection } from "../../ui/tui/candidate-selection.ts";
 import {
   type EvidenceEntry,
   formatCallPath,
@@ -50,15 +51,35 @@ export function renderOrientationResult(
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Orienting…", theme);
 
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_orientation failed" },
+    theme,
+  );
+  if (executionError) return executionError;
+
+  const candidateSelection = renderCandidateSelection(
+    result,
+    options,
+    theme,
+    "orientation.candidates",
+  );
+  if (candidateSelection) return candidateSelection;
+
+  return renderOrientationDetails(result, options, theme);
+}
+
+function renderOrientationDetails(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+): Component {
   const data =
     result.details?.type === "context" ? (result.details.data as Record<string, unknown>) : null;
   const markdownText = result.content.find((c) => c.type === "text")?.text ?? "";
-
-  const executionError = renderExecutionError(context, "code_orientation failed", theme);
-  if (executionError) return executionError;
   const domainError = renderDomainError(result, theme);
   if (domainError) return renderDomainResult(result, options, theme, domainError);
 

package/src/tool/code_refactor_apply/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Apply one fresh stored refactor plan by planId after safety checks; mutates its files.";
+  "Apply a stored refactor plan by its returned planId after freshness and edit-safety checks. Changed files reject the apply and require a new plan; this tool does not regenerate one.";
 
 export const promptSnippet = "apply a stored refactor plan";
 

package/src/tool/code_refactor_apply/tui.ts

@@ -1,6 +1,6 @@
 /** TUI renderer for code_refactor_apply. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { type Component, Container, Spacer, Text } from "@earendil-works/pi-tui";
 import {
   formatCallValue,
   type ResultOptios,
@@ -33,10 +33,14 @@ export function renderRefactorApplyResult(
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Applying…", theme);
 
-  const executionError = renderExecutionError(context, "code_refactor_apply failed", theme);
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_refactor_apply failed" },
+    theme,
+  );
   if (executionError) return executionError;
   const domainError = renderDomainError(result, theme);
   if (domainError) return renderDomainResult(result, options, theme, domainError);

package/src/tool/code_refactor_plan/guidance.ts

@@ -1,8 +1,6 @@
 export const toolDescription =
-  "Preview one semantic rename, extraction, import cleanup, or dead-code deletion and return a planId without mutating files.";
+  "Create and store a semantic refactor preview without changing files. Unsupported operations do not fall back to text edits.";
 
-export const promptSnippet = "preview a precise semantic refactor";
+export const promptSnippet = "preview a semantic refactor";
 
-export const promptGuidelines = [
-  "Use code_refactor_plan for preview only, then call code_refactor_apply with its planId.",
-];
+export const promptGuidelines: string[] = [];

package/src/tool/code_refactor_plan/tui.ts

@@ -50,5 +50,11 @@ export function renderRefactorPlanResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Planning…", context);
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Planning…", failure: "code_refactor_plan failed" },
+    context,
+  );
 }

package/src/tool/code_resolve/guidance.ts

@@ -1,8 +1,6 @@
 export const toolDescription =
-  "Resolve one provider-backed anchor or semantic symbol query to session handles, or enumerate a file's declarations as a bounded Target group. Anchors must identify real symbols";
+  "Resolve a real symbol anchor or semantic query to target handles for later code tools, or list a file's declarations as a target group. This tool does not search file text.";
 
-export const promptSnippet = "resolve a precise target or enumerate a file’s target group";
+export const promptSnippet = "resolve symbols or file declarations";
 
-export const promptGuidelines = [
-  "Use code_resolve when a symbol query may be ambiguous, when later calls should share a stable target handle, or when a known file’s declarations should be enumerated.",
-];
+export const promptGuidelines: string[] = [];

package/src/tool/code_resolve/result.ts

@@ -10,6 +10,7 @@ import {
   type ResultProvenance,
   type ToolResultAssembly,
 } from "../result/assembly.ts";
+import { formatCandidateRow } from "../result/candidate-row.ts";
 import { createToolDisplaySection } from "../result/display.ts";
 import type { ResolveDetails, ToolDisplaySection } from "../result/types.ts";
 
@@ -25,7 +26,7 @@ export interface ResolveResultAssembly {
 interface ResolveProjection {
   readonly key: string;
   readonly title: string;
-  readonly status: "complete" | "unavailable";
+  readonly status: "complete" | "partial" | "unavailable";
   readonly items: readonly unknown[];
   readonly confidence: ConfidenceMode;
   readonly evidence: EvidenceListMetadata | null;
@@ -153,19 +154,19 @@ function projectTargetGroup(
 function projectCandidateOutcome(
   outcome: Extract<TargetWorkflowOutcome, { kind: "disambiguation" | "kind-mismatch" }>,
 ): ResolveProjection {
-  const totalCount = outcome.candidates.length + outcome.omittedCount;
   const evidence: EvidenceListMetadata = {
     key: "resolve.candidates",
-    totalCount,
+    totalCount: outcome.totalCount,
     shownCount: outcome.candidates.length,
     omittedCount: outcome.omittedCount,
-    partialReason: null,
+    partialReason: outcome.partialReason,
   };
+  const collectedCount = evidence.shownCount + (evidence.omittedCount ?? 0);
   const mismatch = outcome.kind === "kind-mismatch";
   return {
     key: "resolve.candidates",
     title: mismatch ? "Near matches" : "Candidates",
-    status: "complete",
+    status: outcome.partialReason ? "partial" : "complete",
     items: outcome.candidates,
     confidence: "semantic",
     evidence,
@@ -173,7 +174,7 @@ function projectCandidateOutcome(
       resultKind: outcome.kind,
       ...(mismatch ? { requestedKind: outcome.requestedKind } : {}),
       confidence: "semantic",
-      targetCount: totalCount,
+      targetCount: evidence.totalCount ?? collectedCount,
       omittedCount: outcome.omittedCount,
       evidenceLists: [evidence],
       targets: [],
@@ -254,15 +255,17 @@ function resolveDisplaySections(details: ResolveDetails): ToolDisplaySection[] {
   }
 
   if (details.candidates && details.candidates.length > 0) {
+    const evidence = details.evidenceLists?.find((entry) => entry.key === "resolve.candidates");
+    if (!evidence) return [];
     return [
       createToolDisplaySection({
         key: "resolve.candidates",
         title: "Candidates",
         items: details.candidates,
-        totalCount: details.targetCount,
-        omittedCount: details.omittedCount,
-        format: (candidate) =>
-          `${candidate.rank}. ${candidate.name} (${candidate.kind ?? "unknown"}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`,
+        totalCount: evidence.totalCount,
+        omittedCount: evidence.omittedCount,
+        partialReason: evidence.partialReason,
+        format: (candidate) => formatCandidateRow(candidate, "rank-first"),
       }),
     ];
   }

package/src/tool/code_resolve/tui.ts

@@ -1,6 +1,7 @@
 /** TUI renderer for code_resolve. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { renderCandidateSelection } from "../../ui/tui/candidate-selection.ts";
 import {
   formatCallPath,
   formatCallValue,
@@ -56,5 +57,21 @@ export function renderResolveResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Resolving…", context);
+  if (!options.isPartial && !context?.isError) {
+    const candidateSelection = renderCandidateSelection(
+      result,
+      options,
+      theme,
+      "resolve.candidates",
+    );
+    if (candidateSelection) return candidateSelection;
+  }
+
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Resolving…", failure: "code_resolve failed" },
+    context,
+  );
 }

package/src/tool/guidance.ts

@@ -1,10 +1,8 @@
-// Model-facing prompt surfaces for the eight public code-intelligence tools.
-//
-// Ownership map (docs/pi/tool-guidance.md): each model-facing fact lives in
-// exactly one home — the per-tool guidance module. This aggregator assembles
-// the canonical surface map consumed by registration.
-// Parameter mechanics (formats, enum semantics, cross-field rules) live in
-// schemas.ts / per-tool spec.ts and are not repeated here.
+/**
+ * Each tool owns its model-facing text. This module assembles the canonical
+ * surface map used by registration. Parameter mechanics stay in specs and
+ * shared schemas.
+ */
 
 import type { CodeIntelligenceToolName } from "../types/index.ts";
 import {
@@ -48,9 +46,13 @@ import {
   promptSnippet as resolveSnippet,
 } from "./code_resolve/guidance.ts";
 
+/** Model-facing fields registered for one public code-intelligence tool. */
 export interface CodeIntelligenceToolPromptSurface {
+  /** Selection contract in the active provider tool definition. */
   description: string;
+  /** One-line capability phrase in the default tool list. */
   promptSnippet: string;
+  /** Optional active-tool routing or ordering reminders. */
   promptGuidelines: string[];
 }
 
@@ -59,7 +61,7 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
   CodeIntelligenceToolPromptSurface
 >;
 
-export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptSurfaceMap = {
+export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES = {
   code_resolve: {
     description: resolveDescription,
     promptSnippet: resolveSnippet,
@@ -100,4 +102,4 @@ export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptS
     promptSnippet: applySnippet,
     promptGuidelines: applyGuidelines,
   },
-};
+} satisfies CodeIntelligenceToolPromptSurfaceMap;

package/src/tool/infra/truncate.ts

@@ -48,7 +48,7 @@ export function truncateToolContent(
   return { text: `${result.content}${notice}`, truncated: true };
 }
 
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CodeIntelResult } from "../../types/index.ts";
@@ -57,7 +57,9 @@ import type { ToolOutputTruncationDetails } from "../result/types.ts";
 /**
  * Apply the canonical output bound to one assembled code-tool result:
  * truncate at PI limits, spill the full content to a temp file when it
- * overflowed, and record truncation details.
+ * overflowed or the human display omits returned evidence. A display-only
+ * continuation does not add text to model content. File failure is fatal only
+ * when model content would otherwise be lost.
  */
 export function boundCodeToolResult(
   content: string,
@@ -71,19 +73,43 @@ export function boundCodeToolResult(
     maxLines: options.maxLines,
     maxBytes: options.maxBytes,
   });
-  if (truncated && content.length > 0) {
-    const dir = mkdtempSync(join(tmpdir(), "supi-ci-"));
-    const spillPath = join(dir, `${options.toolName}-output.md`);
-    writeFileSync(spillPath, content, "utf-8");
-    return {
-      content: [
-        { type: "text" as const, text: `${text}\n_Full output saved to: \`${spillPath}\`_` },
-      ],
-      details: withTruncation({ truncated: true, fullOutputPath: spillPath }),
-    };
+  const displayTruncated = details?.truncation?.displayTruncated === true;
+  const truncation = { truncated, ...(displayTruncated ? { displayTruncated } : {}) };
+  if ((truncated || displayTruncated) && content.length > 0) {
+    try {
+      const spillPath = saveFullContent(content, options.toolName);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: truncated ? `${text}\n_Full output saved to: \`${spillPath}\`_` : text,
+          },
+        ],
+        details: withTruncation({ ...truncation, fullOutputPath: spillPath }),
+      };
+    } catch (error) {
+      if (truncated) throw error;
+      // Keep valid evidence when only its optional human continuation failed.
+    }
   }
   return {
     content: [{ type: "text" as const, text }],
-    details: withTruncation({ truncated: false }),
+    details: withTruncation(truncation),
   };
 }
+
+function saveFullContent(content: string, toolName: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "supi-ci-"));
+  const spillPath = join(dir, `${toolName}-output.md`);
+  try {
+    writeFileSync(spillPath, content, "utf-8");
+    return spillPath;
+  } catch (error) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* Preserve the write error. */
+    }
+    throw error;
+  }
+}

package/src/tool/result/candidate-row.ts

@@ -0,0 +1,27 @@
+/** Candidate fields used by the three target-selection row formats. */
+export interface CandidateRowData {
+  readonly targetId: string;
+  readonly name: string;
+  readonly kind: string | null;
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+  readonly rank?: number;
+}
+
+/** The order used for the target id and rank in one candidate row. */
+export type CandidateRowOrder = "handle-first" | "rank-first";
+
+/** Format one candidate row for a serialized display section or TUI fallback. */
+export function formatCandidateRow(
+  candidate: CandidateRowData,
+  order: CandidateRowOrder,
+  fallbackRank = 1,
+): string {
+  const kind = candidate.kind ?? "unknown";
+  if (order === "handle-first") {
+    return `${candidate.targetId} — ${candidate.name} (${kind}) at ${candidate.file}:${candidate.line}:${candidate.character}`;
+  }
+  const rank = candidate.rank && candidate.rank > 0 ? candidate.rank : fallbackRank;
+  return `${rank}. ${candidate.name} (${kind}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`;
+}

package/src/tool/result/errors.ts

@@ -1,27 +1,42 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
 import type { CodeIntelResult, ToolDisplaySection } from "../../types/index.ts";
+import { assembledNextQueries, assembleToolResult } from "./assembly.ts";
 
-/** Full error result for search-family tools. */
+/** Full failure or candidate-selection result for search-family tools. */
 export function searchErrorResult(
   content: string,
   opts?: {
+    /** Candidate selection is not invalid usage. Defaults to invalid-input. */
+    status?: "invalid-input" | "disambiguation";
     scope?: string | null;
     nextQueries?: string[];
     message?: string;
     displaySections?: readonly ToolDisplaySection[];
+    /** Evidence retained when a target still needs selection. */
+    evidenceLists?: readonly EvidenceListMetadata[];
+    confidence?: ConfidenceMode;
   },
 ): CodeIntelResult {
+  const assembled = assembleToolResult({
+    data: null,
+    confidence: opts?.confidence ?? "unavailable",
+    evidenceLists: opts?.evidenceLists,
+    nextQueries: opts?.nextQueries,
+  });
   return {
     content,
     details: {
       type: "search" as const,
       data: {
-        confidence: "unavailable" as const,
+        confidence: assembled.confidence,
         scope: opts?.scope ?? null,
-        candidateCount: 0,
-        omittedCount: 0,
-        nextQueries: opts?.nextQueries ?? [],
+        candidateCount: assembled.totals.candidateCount,
+        omittedCount: assembled.totals.omittedCount,
+        ...(opts?.evidenceLists ? { evidenceLists: [...assembled.evidenceLists] } : {}),
+        nextQueries: assembledNextQueries(assembled),
       },
-      status: "invalid-input",
+      status: opts?.status ?? "invalid-input",
       ...(opts?.message ? { message: opts.message } : {}),
       ...(opts?.displaySections ? { displaySections: opts.displaySections } : {}),
     },

package/src/tool/result/types.ts

@@ -22,9 +22,13 @@ 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. */
+/** Separate model-content and human-display bounds, with one optional continuation file. */
 export interface ToolOutputTruncationDetails {
+  /** Model content exceeded the PI output limit. */
   truncated: boolean;
+  /** The TUI omits evidence that remains in the model content. */
+  displayTruncated?: boolean;
+  /** Full returned content, not evidence beyond the requested result limit. */
   fullOutputPath?: string;
 }
 
@@ -240,9 +244,9 @@ export interface HealthDetails {
   serverInventoryAvailable: boolean;
   /** Server inventory remains workspace-wide even for a scoped diagnostic request. */
   serverInventoryScope: "workspace";
-  /** Exact status and evidence boundary of the diagnostic observation. */
+  /** Diagnostic result scope and exact evidence boundary for this health call. */
   diagnosticObservation: HealthDiagnosticObservation;
-  /** Current or most recent explicit diagnostic refresh attempt. */
+  /** Current or most recent refresh, including typed maintenance scope and evidence. */
   refresh: HealthRefreshState;
   structuralAvailable: boolean;
   /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */

package/src/tool/schemas.ts

@@ -21,6 +21,11 @@ export const QueryParam = Type.String({
   description: "Human or code reference to resolve or search for.",
   minLength: 1,
 });
+export const FindQueryParam = Type.String({
+  description:
+    "AST mode: name or import module-specifier substring. Semantic mode: workspace-symbol query.",
+  minLength: 1,
+});
 const LineParam = Type.Integer({ description: "1-based line.", minimum: 1 });
 const CharacterParam = Type.Integer({
   description: "1-based UTF-16 column.",

package/src/types/execution.ts

@@ -1,5 +1,6 @@
 import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
 import type { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
+import type { GraphDetails } from "../tool/code_graph/details.ts";
 import type {
   ContextDetails,
   HealthDetails,
@@ -59,6 +60,7 @@ export interface CodeIntelResult {
     | (CodeIntelResultDetails & { type: "context"; data: ContextDetails })
     | (CodeIntelResultDetails & { type: "inspect"; data: InspectDetails })
     | (CodeIntelResultDetails & { type: "search"; data: SearchDetails })
+    | (CodeIntelResultDetails & { type: "graph"; data: GraphDetails })
     | (CodeIntelResultDetails & { type: "resolve"; data: ResolveDetails })
     | (CodeIntelResultDetails & { type: "health"; data: HealthDetails });
 }

package/src/types/index.ts

@@ -16,6 +16,8 @@ export type {
 
 // ── Detail types ────────────────────────────────────────────────────────
 
+export type { GraphDetails, GraphSectionDetails } from "../tool/code_graph/details.ts";
+
 export type {
   AnchoredResolutionMetadata,
   AnchoredResolutionSource,

package/src/ui/tui/candidate-legacy-body.ts

@@ -0,0 +1,69 @@
+/** Bounded raw Markdown rendering for legacy target-selection results. */
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Markdown, Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+/** Maximum source characters rendered by the legacy candidate body. */
+const MAX_LEGACY_SOURCE_CHARACTERS = 4096;
+
+/** Maximum physical rows rendered by the legacy candidate body. */
+const MAX_LEGACY_BODY_ROWS = 40;
+
+const LEGACY_TRUNCATION_NOTICE = `Legacy candidate body truncated for display (source limit: ${MAX_LEGACY_SOURCE_CHARACTERS} characters; body limit: ${MAX_LEGACY_BODY_ROWS} rows).`;
+
+/** Read valid Markdown text blocks without trusting persisted content shape. */
+export function readLegacyCandidateText(value: unknown): string {
+  if (!Array.isArray(value)) return "";
+  return value
+    .flatMap((block) => {
+      if (block === null || typeof block !== "object" || Array.isArray(block)) return [];
+      const record = block as Record<string, unknown>;
+      return record.type === "text" && typeof record.text === "string" ? [record.text] : [];
+    })
+    .join("\n");
+}
+
+/** Create a bounded legacy candidate body, or null when no valid text exists. */
+export function createLegacyCandidateBody(markdownText: string, theme: Theme): Component | null {
+  if (!markdownText.trim()) return null;
+  return new BoundedLegacyCandidateBody(markdownText, theme);
+}
+
+class BoundedLegacyCandidateBody implements Component {
+  private readonly markdownText: string;
+  private readonly sourceTruncated: boolean;
+
+  constructor(
+    markdownText: string,
+    private readonly theme: Theme,
+  ) {
+    const sourceCharacters = Array.from(markdownText);
+    this.sourceTruncated = sourceCharacters.length > MAX_LEGACY_SOURCE_CHARACTERS;
+    this.markdownText = this.sourceTruncated
+      ? sourceCharacters.slice(0, MAX_LEGACY_SOURCE_CHARACTERS).join("")
+      : markdownText;
+  }
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(1, width);
+    const markdownRows = new Markdown(this.markdownText, 0, 0, getMarkdownTheme())
+      .render(safeWidth)
+      .map((row) => truncateToWidth(row, safeWidth, ""));
+
+    if (!this.sourceTruncated && markdownRows.length <= MAX_LEGACY_BODY_ROWS) {
+      return markdownRows;
+    }
+
+    const noticeRows = new Text(this.theme.fg("warning", LEGACY_TRUNCATION_NOTICE), 0, 0).render(
+      safeWidth,
+    );
+    const markdownRowBudget = Math.max(0, MAX_LEGACY_BODY_ROWS - noticeRows.length);
+    return [...markdownRows.slice(0, markdownRowBudget), ...noticeRows].slice(
+      0,
+      MAX_LEGACY_BODY_ROWS,
+    );
+  }
+
+  invalidate(): void {
+    // The Markdown and notice components are rebuilt for each render.
+  }
+}