@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/tool/schemas.ts

@@ -1,22 +1,19 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type TSchema, Type } from "typebox";
 import { TARGET_SYMBOL_KINDS } from "../session/target-input.ts";
-import type { CodeIntelligenceToolName } from "../types/index.ts";
-import { CODE_FIND_AST_KINDS } from "./find/ast-kinds.ts";
-import { CODE_FIND_MODES } from "./find/modes.ts";
 
-const ScopeParam = Type.String({
+export const ScopeParam = Type.String({
   description: "Workspace-relative file or directory scope.",
 });
-const FindScopeParam = Type.Array(
+export const FindScopeParam = Type.Array(
   Type.String({ description: "Workspace-relative search scope." }),
   {
     description: "One or more workspace-relative search scopes.",
     minItems: 1,
   },
 );
-const FileParam = Type.String({ description: "Target file path." });
-const QueryParam = Type.String({
+const FileParam = Type.String({ description: "File path." });
+export const QueryParam = Type.String({
   description: "Human or code reference to resolve or search for.",
   minLength: 1,
 });
@@ -25,14 +22,14 @@ const CharacterParam = Type.Integer({
   description: "1-based UTF-16 column.",
   minimum: 1,
 });
-const MaxResultsParam = Type.Integer({
+export const MaxResultsParam = Type.Integer({
   description: "Maximum displayed results.",
   minimum: 1,
 });
 
-const SourcePointParam = Type.Object(
+export const SourcePointParam = Type.Object(
   { file: FileParam, line: LineParam, character: CharacterParam },
-  { description: "A precise 1-based source point.", additionalProperties: false },
+  { additionalProperties: false },
 );
 
 const SymbolTargetParam = Type.Object(
@@ -41,12 +38,12 @@ const SymbolTargetParam = Type.Object(
     scope: Type.Optional(ScopeParam),
     symbolKind: Type.Optional(
       StringEnum(TARGET_SYMBOL_KINDS, {
-        description: "Exact provider-reported LSP SymbolKind filter; omit when uncertain.",
+        description: "LSP SymbolKind filter; omit when uncertain.",
       }),
     ),
   },
   {
-    description: "Semantic symbol query and optional workspace-relative scope.",
+    description: "Semantic symbol query.",
     additionalProperties: false,
   },
 );
@@ -68,22 +65,22 @@ function exactOneSelector(properties: Record<string, TSchema>, description: stri
   });
 }
 
-const ResolveTargetParam = exactOneSelector(
+export const ResolveTargetParam = exactOneSelector(
   {
     anchor: SourcePointParam,
     symbol: SymbolTargetParam,
     file: FileParam,
   },
-  "Exactly one target source: provider-backed anchor, semantic symbol query, or file declaration group.",
+  "Exactly one: anchor, symbol query, or file declaration group.",
 );
 
-const GraphTargetParam = exactOneSelector(
+export const GraphTargetParam = exactOneSelector(
   {
     handle: Type.String({ description: "Target handle returned by code_resolve." }),
     anchor: SourcePointParam,
     symbol: SymbolTargetParam,
   },
-  "Exactly one graph target: handle, provider-backed anchor, or semantic symbol query.",
+  "Exactly one graph target.",
 );
 
 const OrientationTargetParam = exactOneSelector(
@@ -92,10 +89,10 @@ const OrientationTargetParam = exactOneSelector(
     anchor: SourcePointParam,
     symbol: SymbolTargetParam,
   },
-  "Exactly one precise Orientation target: handle, provider-backed anchor, or semantic symbol query.",
+  "Exactly one Orientation target.",
 );
 
-const OrientationFocusParam = exactOneSelector(
+export const OrientationFocusParam = exactOneSelector(
   {
     path: Type.String({
       description: "Workspace-relative project, package, directory, or file path.",
@@ -103,15 +100,15 @@ const OrientationFocusParam = exactOneSelector(
     module: Type.String({ description: "Discovered module name." }),
     target: OrientationTargetParam,
   },
-  "Exactly one Orientation focus: path, discovered module, or precise target.",
+  "Exactly one Orientation focus.",
 );
 
-const RefactorTargetParam = exactOneSelector(
+export const RefactorTargetParam = exactOneSelector(
   {
     handle: Type.String({ description: "Target handle returned by code_resolve." }),
     anchor: SourcePointParam,
   },
-  "Exactly one refactor target: handle or provider-backed anchor.",
+  "Exactly one refactor target.",
 );
 
 const RangeParam = Type.Object(
@@ -125,153 +122,25 @@ const RangeParam = Type.Object(
       { additionalProperties: false },
     ),
   },
-  { description: "1-based selected source range.", additionalProperties: false },
+  { additionalProperties: false },
 );
 
 const NewNameParam = Type.String({ description: "New symbol name.", minLength: 1 });
 
-const RefactorOperationParam = exactOneSelector(
+export const RefactorOperationParam = exactOneSelector(
   {
-    rename_symbol: Type.Object(
-      { newName: NewNameParam },
-      { description: "Rename a semantic symbol.", additionalProperties: false },
-    ),
+    rename_symbol: Type.Object({ newName: NewNameParam }, { additionalProperties: false }),
     extract_function: Type.Object(
       { newName: NewNameParam, range: RangeParam },
-      { description: "Extract the selected range into a function.", additionalProperties: false },
+      { additionalProperties: false },
     ),
     extract_variable: Type.Object(
       { newName: NewNameParam, range: RangeParam },
-      { description: "Extract the selected range into a variable.", additionalProperties: false },
-    ),
-  },
-  "Exactly one precise refactor operation.",
-);
-
-/** Resolve one target or enumerate a file declaration group as session-scoped handles. */
-export const CodeResolveParameters = Type.Object(
-  {
-    target: ResolveTargetParam,
-    maxResults: Type.Optional(MaxResultsParam),
-  },
-  { additionalProperties: false },
-);
-
-/** Inspect one precise point. */
-export const CodeInspectParameters = Type.Object(
-  {
-    point: SourcePointParam,
-    maxResults: Type.Optional(MaxResultsParam),
-  },
-  { additionalProperties: false },
-);
-
-/** Orient around the workspace or one exact focus. */
-export const CodeOrientationParameters = Type.Object(
-  {
-    focus: Type.Optional(OrientationFocusParam),
-    maxResults: Type.Optional(MaxResultsParam),
-  },
-  { additionalProperties: false },
-);
-
-/** Unified structural and semantic code search. */
-export const CodeFindParameters = Type.Object(
-  {
-    query: QueryParam,
-    scope: Type.Optional(FindScopeParam),
-    mode: StringEnum(CODE_FIND_MODES, {
-      description: 'Required code-aware search mode. mode:"ast" requires `kind`.',
-    }),
-    kind: Type.Optional(
-      StringEnum(CODE_FIND_AST_KINDS, {
-        description: 'AST kind; only valid with mode:"ast".',
-      }),
-    ),
-    maxResults: Type.Optional(MaxResultsParam),
-  },
-  { additionalProperties: false },
-);
-
-/** Provider-backed and explicitly structural relations for one target. */
-export const CodeGraphParameters = Type.Object(
-  {
-    target: GraphTargetParam,
-    relations: Type.Optional(
-      Type.Array(StringEnum(["all", "references", "callees", "implements"]), {
-        description:
-          'Requested relations; defaults to ["references"]. "all" must be the only item.',
-        minItems: 1,
-        uniqueItems: true,
-      }),
-    ),
-    maxResults: Type.Optional(MaxResultsParam),
-    calleeDepth: Type.Optional(
-      StringEnum(["direct", "deep"], {
-        description: '`"direct"` excludes nested scopes; `"deep"` includes them.',
-      }),
-    ),
-  },
-  { additionalProperties: false },
-);
-
-/** Preview one precise semantic refactor without mutating files. */
-export const CodeRefactorParameters = Type.Object(
-  {
-    target: RefactorTargetParam,
-    operation: RefactorOperationParam,
-  },
-  { additionalProperties: false },
-);
-
-/** Apply a stored plan after freshness and fingerprint validation. */
-export const CodeApplyParameters = Type.Object(
-  {
-    planId: Type.String({
-      description: "Stored plan identifier returned by code_refactor_plan.",
-      minLength: 1,
-    }),
-  },
-  { additionalProperties: false },
-);
-
-/** Report evidence-backed workspace health signals. */
-export const CodeHealthParameters = Type.Object(
-  {
-    scope: Type.Optional(ScopeParam),
-    refresh: Type.Optional(
-      Type.Boolean({
-        description:
-          "Attempt workspace-runtime diagnostic recovery before collecting health data; the result reports the established attempt outcome.",
-      }),
-    ),
-    include: Type.Optional(
-      Type.Array(
-        StringEnum(["diagnostics", "servers"], {
-          description: "Live health signals to include.",
-        }),
-        { description: "Requested health-signal sections.", uniqueItems: true },
-      ),
-    ),
-    level: Type.Optional(
-      StringEnum(["summary", "detailed"], {
-        description: "Detail level for the health report.",
-      }),
+      { additionalProperties: false },
     ),
   },
-  { additionalProperties: false },
+  "Exactly one refactor operation.",
 );
 
-export type WorkflowCodeToolSchemaKey = CodeIntelligenceToolName;
-
-/** Code intelligence tool schemas keyed by public tool name. */
-export const CODE_INTELLIGENCE_TOOL_SCHEMAS = {
-  code_resolve: CodeResolveParameters,
-  code_inspect: CodeInspectParameters,
-  code_orientation: CodeOrientationParameters,
-  code_find: CodeFindParameters,
-  code_graph: CodeGraphParameters,
-  code_refactor_plan: CodeRefactorParameters,
-  code_refactor_apply: CodeApplyParameters,
-  code_health: CodeHealthParameters,
-} as const satisfies Record<CodeIntelligenceToolName, TSchema>;
+// Per-tool parameter objects live in each tool's spec.ts; this module keeps the
+// shared parameter vocabulary for the eight-tool family.

package/src/tool/specs.ts

@@ -1,36 +1,29 @@
+import type { Component } from "@earendil-works/pi-tui";
 import type { TSchema } from "typebox";
-import {
-  DEFAULT_AST_SCAN_MAX_FILES,
-  DEFAULT_AST_SCAN_TIMEOUT_MS,
-} from "../analysis/search/ast-scan.ts";
 import type {
   CodeIntelligenceToolName,
   CodeIntelResult,
   CodeIntelToolExecCtx,
 } from "../types/index.ts";
-import { executeFindTool } from "./find/execute.ts";
-import { executeGraphTool } from "./graph/execute.ts";
-import { executeHealthTool } from "./health/execute.ts";
-import { executeInspectTool } from "./inspect/execute.ts";
-import { executeOrientationTool } from "./orientation/execute.ts";
-import { executeRefactorApplyTool } from "./refactor-apply/execute.ts";
-import { executeRefactorPlanTool } from "./refactor-plan/execute.ts";
-import { executeResolveTool } from "./resolve/execute.ts";
-import {
-  CodeApplyParameters,
-  CodeFindParameters,
-  CodeGraphParameters,
-  CodeHealthParameters,
-  CodeInspectParameters,
-  CodeOrientationParameters,
-  CodeRefactorParameters,
-  CodeResolveParameters,
-} from "./schemas.ts";
+import { codeFindSpec } from "./code_find/spec.ts";
+import { codeGraphSpec } from "./code_graph/spec.ts";
+import { codeHealthSpec } from "./code_health/spec.ts";
+import { codeInspectSpec } from "./code_inspect/spec.ts";
+import { codeOrientationSpec } from "./code_orientation/spec.ts";
+import { codeRefactorApplySpec } from "./code_refactor_apply/spec.ts";
+import { codeRefactorPlanSpec } from "./code_refactor_plan/spec.ts";
+import { codeResolveSpec } from "./code_resolve/spec.ts";
 
-/** Substrate families that power a tool's implementation. */
-export type ToolSubstrate = "semantic" | "structural" | "search" | "diagnostics";
+/**
+ * Canonical registration spec for one public code-intelligence tool.
+ *
+ * Model-facing prose is not part of the spec: descriptions, snippets, and
+ * guidelines live in each tool's `guidance.ts`, parameter mechanics live in
+ * each tool's `spec.ts` over the shared vocabulary in `schemas.ts`.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: pi render call/result signatures vary per tool
+export type CodeToolRendererFn = (...args: any[]) => Component;
 
-/** Canonical registration spec for one public code-intelligence tool. */
 export interface CodeIntelligenceToolDefinitionSpec {
   name: CodeIntelligenceToolName;
   label: string;
@@ -38,109 +31,30 @@ export interface CodeIntelligenceToolDefinitionSpec {
   maxLines?: number;
   maxBytes?: number;
   run: (params: unknown, ctx: CodeIntelToolExecCtx) => Promise<CodeIntelResult> | CodeIntelResult;
-  purpose: string;
-  schemaDocs: string;
-  substrates: ToolSubstrate[];
-  nonGoals: string[];
+  renderCall?: CodeToolRendererFn;
+  renderResult?: CodeToolRendererFn;
 }
 
 /** Single source of truth for the surviving eight-tool family. */
 export const CODE_INTELLIGENCE_TOOL_SPECS = [
-  {
-    name: "code_resolve",
-    label: "Code Resolve",
-    parameters: CodeResolveParameters,
-    run: (params, ctx) =>
-      executeResolveTool(params as Parameters<typeof executeResolveTool>[0], ctx),
-    purpose:
-      "Resolve an anchor/symbol into handles or enumerate a file's declarations as a Target group.",
-    schemaDocs: "Requires one exact target selector: anchor, symbol, or file.",
-    substrates: ["semantic", "structural"],
-    nonGoals: [
-      "Handles do not persist across sessions.",
-      "No text-search or structural-only target creation fallback.",
-    ],
-  },
-  {
-    name: "code_inspect",
-    label: "Code Inspect",
-    parameters: CodeInspectParameters,
-    run: (params, ctx) =>
-      executeInspectTool(params as Parameters<typeof executeInspectTool>[0], ctx),
-    purpose: "Inspect one exact source point with semantic, structural, and diagnostic facts.",
-    schemaDocs: "Requires point.file, point.line, and point.character.",
-    substrates: ["semantic", "structural", "diagnostics"],
-    nonGoals: ["Does not apply code actions."],
-  },
-  {
-    name: "code_orientation",
-    label: "Code Orientation",
-    parameters: CodeOrientationParameters,
-    run: (params, ctx) =>
-      executeOrientationTool(params as Parameters<typeof executeOrientationTool>[0], ctx),
-    purpose: "Orient around the workspace or one exact path, module, or target focus.",
-    schemaDocs: "Omitted focus means workspace; otherwise focus is an exact-one selector.",
-    substrates: ["semantic", "structural", "diagnostics"],
-    nonGoals: ["Relation evidence belongs to code_graph.", "Health belongs to code_health."],
-  },
-  {
-    name: "code_graph",
-    label: "Code Graph",
-    parameters: CodeGraphParameters,
-    run: (params, ctx) => executeGraphTool(params as Parameters<typeof executeGraphTool>[0], ctx),
-    purpose: "Collect references, structural callees, and implementations for one exact target.",
-    schemaDocs:
-      "Target is handle, anchor, or symbol; all expands to the three surviving relations.",
-    substrates: ["semantic", "structural"],
-    nonGoals: ["No inferred tests.", "No file-level import/export inventories."],
-  },
-  {
-    name: "code_find",
-    label: "Code Find",
-    parameters: CodeFindParameters,
-    run: (params, ctx) => executeFindTool(params as Parameters<typeof executeFindTool>[0], ctx),
-    purpose: "Search structural source shape or semantic workspace symbols explicitly.",
-    schemaDocs: `Requires query and ast/semantic mode; scope is optional and AST mode requires kind. AST enumeration uses a shared ${DEFAULT_AST_SCAN_TIMEOUT_MS / 1_000}-second deadline, a ${DEFAULT_AST_SCAN_MAX_FILES}-file cap, and canonical scope deduplication.`,
-    substrates: ["semantic", "structural"],
-    nonGoals: [
-      "No literal or regex text search; use PI grep when active.",
-      "No natural-language retrieval.",
-      "No silent mode fallback.",
-    ],
-  },
-  {
-    name: "code_health",
-    label: "Code Health",
-    parameters: CodeHealthParameters,
-    run: (params, ctx) => executeHealthTool(params as Parameters<typeof executeHealthTool>[0], ctx),
-    purpose: "Report live diagnostic, runtime, and structural health observations.",
-    schemaDocs: "Optional scope, refresh, include, and level; diagnostics and servers are default.",
-    substrates: ["semantic", "structural", "diagnostics"],
-    nonGoals: [
-      "Does not run tests or verification commands.",
-      "Does not load precomputed coverage or unused-code reports.",
-    ],
-  },
-  {
-    name: "code_refactor_plan",
-    label: "Code Refactor Plan",
-    parameters: CodeRefactorParameters,
-    run: (params, ctx) =>
-      executeRefactorPlanTool(params as Parameters<typeof executeRefactorPlanTool>[0], ctx),
-    purpose: "Create a precise, non-mutating semantic refactor plan.",
-    schemaDocs: "Requires one handle/anchor target and one exact operation payload.",
-    substrates: ["semantic"],
-    nonGoals: ["Never mutates files.", "No heuristic text edits."],
-  },
-  {
-    name: "code_refactor_apply",
-    label: "Code Refactor Apply",
-    parameters: CodeApplyParameters,
-    run: (params, ctx) =>
-      executeRefactorApplyTool(params as Parameters<typeof executeRefactorApplyTool>[0], ctx),
-    purpose: "Apply one stored, fingerprint-checked refactor plan.",
-    schemaDocs: "Requires the planId returned by code_refactor_plan.",
-    substrates: ["structural"],
-    nonGoals: ["Does not compose plans.", "Does not bypass freshness checks."],
-  },
+  codeResolveSpec,
+  codeInspectSpec,
+  codeOrientationSpec,
+  codeGraphSpec,
+  codeFindSpec,
+  codeHealthSpec,
+  codeRefactorPlanSpec,
+  codeRefactorApplySpec,
 ] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];
+
+/** Code intelligence tool schemas keyed by public tool name. */
+export const CODE_INTELLIGENCE_TOOL_SCHEMAS = {
+  code_resolve: codeResolveSpec.parameters,
+  code_inspect: codeInspectSpec.parameters,
+  code_orientation: codeOrientationSpec.parameters,
+  code_find: codeFindSpec.parameters,
+  code_graph: codeGraphSpec.parameters,
+  code_refactor_plan: codeRefactorPlanSpec.parameters,
+  code_refactor_apply: codeRefactorApplySpec.parameters,
+  code_health: codeHealthSpec.parameters,
+} as const satisfies Record<CodeIntelligenceToolName, TSchema>;

package/src/types/execution.ts

@@ -6,6 +6,9 @@ import type {
   InspectDetails,
   ResolveDetails,
   SearchDetails,
+  ToolDisplaySection,
+  ToolOutputTruncationDetails,
+  ToolResultStatus,
 } from "../tool/result/types.ts";
 
 /**
@@ -26,6 +29,8 @@ import type {
  */
 export interface CodeIntelToolExecCtx {
   cwd: string;
+  /** Opaque identity for Debug Events directly owned by this public Tool call. */
+  operationId?: string;
   /** Abort signal from the agent runtime; forward to long-running subprocesses. */
   signal?: AbortSignal;
   /** Progress callback; long-running executors emit coarse beats, not chatty ones. */
@@ -39,13 +44,21 @@ export interface CodeIntelToolExecCtx {
   session: WorkspaceCodeIntelligenceSession;
 }
 
+/** Shared metadata attached to one persisted Code Intelligence result. */
+export interface CodeIntelResultDetails {
+  status?: ToolResultStatus;
+  message?: string;
+  displaySections?: readonly ToolDisplaySection[];
+  truncation?: ToolOutputTruncationDetails;
+}
+
 /** Tool result shape returned by executeAction. */
 export interface CodeIntelResult {
   content: string;
   details?:
-    | { type: "context"; data: ContextDetails }
-    | { type: "inspect"; data: InspectDetails }
-    | { type: "search"; data: SearchDetails }
-    | { type: "resolve"; data: ResolveDetails }
-    | { type: "health"; data: HealthDetails };
+    | (CodeIntelResultDetails & { type: "context"; data: ContextDetails })
+    | (CodeIntelResultDetails & { type: "inspect"; data: InspectDetails })
+    | (CodeIntelResultDetails & { type: "search"; data: SearchDetails })
+    | (CodeIntelResultDetails & { type: "resolve"; data: ResolveDetails })
+    | (CodeIntelResultDetails & { type: "health"; data: HealthDetails });
 }

package/src/types/index.ts

@@ -8,7 +8,11 @@ export {
 
 // ── Execution context and result ────────────────────────────────────────
 
-export type { CodeIntelResult, CodeIntelToolExecCtx } from "./execution.ts";
+export type {
+  CodeIntelResult,
+  CodeIntelResultDetails,
+  CodeIntelToolExecCtx,
+} from "./execution.ts";
 
 // ── Detail types ────────────────────────────────────────────────────────
 
@@ -23,4 +27,7 @@ export type {
   OrientationSectionDetails,
   ResolveDetails,
   SearchDetails,
+  ToolDisplaySection,
+  ToolOutputTruncationDetails,
+  ToolResultStatus,
 } from "../tool/result/types.ts";

package/src/ui/status-command.ts

@@ -52,7 +52,7 @@ export function registerCiStatusCommand(pi: ExtensionAPI): void {
               fetchDetailedDiagnostics: async (maxSeverity) => {
                 const lspState = getWorkspaceLspRuntime(ctx.cwd);
                 if (lspState.kind !== "ready") return [];
-                return lspState.runtime.getOutstandingDiagnostics(maxSeverity);
+                return lspState.runtime.getOutstandingDiagnostics(maxSeverity).entries;
               },
               onRefresh: async () => {
                 const fresh = await gatherCiStatusData(ctx.cwd, pi);
@@ -95,10 +95,11 @@ async function gatherCiStatusData(cwd: string, pi: ExtensionAPI): Promise<CiStat
   const semanticAvailable = servers.some(
     (server) => server.status === "running" && server.ready === true,
   );
-  const diagnostics =
+  const diagnosticSnapshot =
     lspState.kind === "ready" && semanticAvailable
       ? lspState.runtime.getOutstandingDiagnosticSummary(1)
-      : [];
+      : { entries: [], current: false };
+  const diagnostics = diagnosticSnapshot.entries;
   const semanticState = deriveSemanticCapabilityState(workspace, lspState, semanticAvailable);
 
   // Sort: errors desc, warnings desc, info desc, hints desc
@@ -123,6 +124,7 @@ async function gatherCiStatusData(cwd: string, pi: ExtensionAPI): Promise<CiStat
     diagnostics,
     serverInventoryAvailable,
     semanticAvailable,
+    diagnosticSnapshotCurrent: diagnosticSnapshot.current,
     capabilities: {
       semantic: semanticState,
       structural: {

package/src/ui/status-overlay.ts

@@ -37,6 +37,8 @@ export interface CiStatusData {
   serverInventoryAvailable: boolean;
   /** Whether diagnostics and semantic absence claims are currently supported. */
   semanticAvailable: boolean;
+  /** Whether tracked-file diagnostic counts prove the current document and workspace state. */
+  diagnosticSnapshotCurrent: boolean;
   /** Sorted: errors desc, then warnings desc, then info desc, then hints desc. */
   diagnostics: OutstandingDiagnosticSummaryEntry[];
   capabilities: {
@@ -373,6 +375,8 @@ export class CiStatusDialog {
     const t = this.theme;
     if (!this.data.semanticAvailable) {
       container.addChild(new Text(t.fg("dim", "  (diagnostics unavailable)"), 1, 0));
+    } else if (!this.data.diagnosticSnapshotCurrent) {
+      container.addChild(new Text(t.fg("warning", "  diagnostic snapshot is stale"), 1, 0));
     } else {
       container.addChild(new Text(t.fg("success", "  ✓ no issues"), 1, 0));
     }