@mrclrchtr/supi-code-intelligence 4.0.0 → 4.2.0

package/src/session/orientation-types.ts

@@ -16,11 +16,16 @@ export interface OrientationWorkflowInput {
   readonly maxResults?: number;
 }
 
-/** Presentation-neutral block collected for an Orientation result. */
-export type OrientationBlock =
-  | { readonly kind: "heading"; readonly level: 1 | 2 | 3; readonly text: string }
+/**
+ * Presentation-neutral content atom a collector emits for one Orientation
+ * section. Collectors never build headings, section notes, or document
+ * framing — the markdown adapter owns all of that. `subheading` renders as an
+ * h3 within a section (only instruction-file paths use it).
+ */
+export type OrientationItem =
   | { readonly kind: "paragraph"; readonly text: string }
   | { readonly kind: "list-item"; readonly text: string }
+  | { readonly kind: "subheading"; readonly text: string }
   | {
       readonly kind: "code";
       readonly language: string | null;
@@ -51,6 +56,8 @@ export interface OrientationSectionData {
   readonly confidence: ConfidenceMode;
   readonly provenance: readonly OrientationProvenance[];
   readonly evidenceLists: readonly EvidenceListMetadata[];
+  /** Content atoms for this section; the adapter frames them under the title + note. */
+  readonly items: readonly OrientationItem[];
 }
 
 export interface OrientationCandidate {
@@ -67,7 +74,10 @@ export interface OrientationCandidate {
 
 /** Immutable facts returned by the session before markdown or TUI rendering. */
 export interface OrientationResultData {
-  readonly blocks: readonly OrientationBlock[];
+  /** Document title rendered as the leading h1 (e.g. "Workspace Orientation", "Code Orientation"). */
+  readonly title: string;
+  /** Leading paragraphs rendered before the title (target summary / resolution notes). */
+  readonly notes: readonly string[];
   readonly sections: readonly OrientationSectionData[];
   readonly confidence: ConfidenceMode;
   readonly focusTarget: string | null;

package/src/session/orientation-workflow.ts

@@ -14,10 +14,9 @@ import { loadCodeIntelligenceConfig } from "../config.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
 import { parseOrientationWorkflowInput } from "./input/workflows.ts";
 import { executeOrientation } from "./orientation/collect.ts";
-import { formatSectionNote } from "./orientation/context-sections.ts";
 import type {
-  OrientationBlock,
   OrientationFocusInput,
+  OrientationItem,
   OrientationResultData,
   OrientationSectionData,
   OrientationWorkflowInput,
@@ -217,6 +216,20 @@ function addInstructionFiles(
   const collected = collectInstructionFiles(matches);
   if (!collected) return result;
   deps.markInstructionDirsSurfaced(collected.metadata.files.map((file) => file.directory));
+  const items: OrientationItem[] = [];
+  for (const file of collected.files) {
+    items.push(
+      { kind: "subheading", text: file.path },
+      { kind: "code", language: null, lines: file.content.split("\n") },
+    );
+    if (file.truncated) {
+      items.push({
+        kind: "paragraph",
+        text: `Instruction file truncated to ${file.shownLines} of ${file.totalLines} lines. Read ${file.path} for the full file.`,
+      });
+    }
+    items.push({ kind: "blank" });
+  }
   const section: OrientationSectionData = {
     key: "instructions",
     title: "Instructions",
@@ -233,10 +246,10 @@ function addInstructionFiles(
         partialReason: null,
       },
     ],
+    items,
   };
   return {
     ...result,
-    blocks: insertInstructionBlocks(result.blocks, collected.files, section),
     sections: [section, ...result.sections],
     renderedSections: ["instructions", ...result.renderedSections],
     instructions: collected.metadata,
@@ -258,50 +271,9 @@ function addTargetSummary(
   cwd: string,
 ): OrientationResultData {
   const name = entry.name ? ` ${entry.name}` : "";
-  const summary: OrientationBlock[] = [
-    ...notes.map((note): OrientationBlock => ({ kind: "paragraph", text: `Note: ${note}` })),
-    {
-      kind: "paragraph",
-      text: `Resolved target${name}: ${relative(cwd, entry.file) || entry.file}:${entry.displayLine}:${entry.displayCharacter} — Target ID: ${entry.targetId}`,
-    },
-    { kind: "blank" },
+  const summaryNotes = [
+    ...notes.map((note) => `Note: ${note}`),
+    `Resolved target${name}: ${relative(cwd, entry.file) || entry.file}:${entry.displayLine}:${entry.displayCharacter} — Target ID: ${entry.targetId}`,
   ];
-  return { ...result, blocks: [...summary, ...result.blocks], target: { ...entry } };
-}
-
-function insertInstructionBlocks(
-  existing: readonly OrientationBlock[],
-  files: readonly {
-    path: string;
-    content: string;
-    truncated: boolean;
-    shownLines: number;
-    totalLines: number;
-  }[],
-  section: OrientationSectionData,
-): OrientationBlock[] {
-  const blocks: OrientationBlock[] = [
-    { kind: "heading", level: 2, text: "Instructions" },
-    { kind: "paragraph", text: formatSectionNote(section) },
-    { kind: "blank" },
-  ];
-  for (const file of files) {
-    blocks.push(
-      { kind: "heading", level: 3, text: file.path },
-      { kind: "code", language: null, lines: file.content.split("\n") },
-    );
-    if (file.truncated) {
-      blocks.push({
-        kind: "paragraph",
-        text: `Instruction file truncated to ${file.shownLines} of ${file.totalLines} lines. Read ${file.path} for the full file.`,
-      });
-    }
-    blocks.push({ kind: "blank" });
-  }
-
-  const insertion = existing.findIndex(
-    (block, index) => index > 0 && block.kind === "heading" && block.level === 2,
-  );
-  if (insertion < 0) return [...existing, ...blocks];
-  return [...existing.slice(0, insertion), ...blocks, ...existing.slice(insertion)];
+  return { ...result, notes: [...summaryNotes, ...result.notes], target: { ...entry } };
 }

package/src/substrate/lsp/lifecycle.ts

@@ -1,53 +1,39 @@
-// LSP session lifecycle — uses LspRuntimeController from @mrclrchtr/supi-lsp/api.
-//
-// Registers session_start and session_shutdown handlers that manage
-// the LspRuntimeController lifecycle.
+// LSP lifecycle backed by the process-shared Workspace provider host.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
-import { LspRuntimeController, scanWorkspaceSentinels } from "@mrclrchtr/supi-lsp/api";
 import { unregisterLspFooterContribution } from "../../ui/footer.ts";
+import { acquireWorkspaceProviderHost } from "../workspace-provider-host.ts";
 import type { LspAdapterState } from "./state.ts";
 
-export function registerLspSessionLifecycle(pi: ExtensionAPI, state: LspAdapterState): void {
+/** Acquire providers once per workspace and release them after the final Pi session ends. */
+export function registerLspSessionLifecycle(
+  pi: ExtensionAPI,
+  state: LspAdapterState,
+  onStarted?: (ctx: ExtensionContext) => void | Promise<void>,
+): void {
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
-    const cwd = ctx.cwd;
-    const runtime = getDefaultWorkspaceRuntime();
-
-    if (state.controller) {
-      await state.controller.shutdown();
-      state.controller = null;
-    }
+    await state.providerLease?.release();
+    state.providerLease = null;
+    state.controller = null;
     state.lspActive = false;
+    state.sentinelSnapshot = new Map();
 
-    // Project-local LSP configuration may define custom commands; defer
-    // until the project is trusted so an untrusted repository cannot control
-    // spawned processes.
-    if (!ctx.isProjectTrusted()) {
-      state.controller = null;
-      state.lspActive = false;
-      return;
-    }
-
-    const controller = new LspRuntimeController(cwd, runtime);
-    const result = await controller.start();
-
-    if (result.kind === "ready") {
-      state.controller = controller;
-      state.lspActive = true;
-      state.sentinelSnapshot = scanWorkspaceSentinels(cwd);
-    } else {
-      state.controller = null;
-      state.lspActive = false;
-    }
+    const lease = await acquireWorkspaceProviderHost(ctx.cwd, {
+      projectTrusted: ctx.isProjectTrusted(),
+    });
+    state.providerLease = lease;
+    state.controller = lease.lspController;
+    state.lspActive = lease.lspController?.kind === "ready";
+    state.sentinelSnapshot = lease.sentinelSnapshot;
+    await onStarted?.(ctx);
   });
 
-  pi.on("session_shutdown", async (_event, _ctx: ExtensionContext) => {
-    if (state.controller) {
-      await state.controller.shutdown();
-      state.controller = null;
-    }
+  pi.on("session_shutdown", async () => {
+    await state.providerLease?.release();
+    state.providerLease = null;
+    state.controller = null;
     state.lspActive = false;
+    state.sentinelSnapshot = new Map();
     unregisterLspFooterContribution();
   });
 }

package/src/substrate/lsp/state.ts

@@ -4,6 +4,7 @@
 // through LspRuntimeController from @mrclrchtr/supi-lsp/api.
 
 import type { LspRuntimeController } from "@mrclrchtr/supi-lsp/api";
+import type { WorkspaceProviderHostLease } from "../workspace-provider-host.ts";
 
 /** LSP status overlay UI state (handle + close). */
 export interface LspInspectorState {
@@ -19,6 +20,7 @@ export interface LspInspectorState {
  */
 export interface LspAdapterState {
   controller: LspRuntimeController | null;
+  providerLease: WorkspaceProviderHostLease | null;
   inspector: LspInspectorState;
   lspActive: boolean;
   /** Snapshot of workspace sentinel files (package.json, tsconfig, lockfiles) for change detection. */
@@ -28,6 +30,7 @@ export interface LspAdapterState {
 export function createLspAdapterState(): LspAdapterState {
   return {
     controller: null,
+    providerLease: null,
     inspector: { handle: null, close: null },
     lspActive: false,
     sentinelSnapshot: new Map(),

package/src/substrate/workspace-provider-host.ts

@@ -0,0 +1,129 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import { LspRuntimeController, scanWorkspaceSentinels } from "@mrclrchtr/supi-lsp/api";
+import { TreeSitterRuntimeController } from "@mrclrchtr/supi-tree-sitter/api";
+
+const HOSTS = Symbol.for("supi-code-intelligence/workspace-provider-hosts");
+const SHUTDOWN_GRACE_MS = 2_000;
+
+type HostRegistry = Map<string, WorkspaceProviderHost>;
+
+/** One acquired reference to a process-shared Workspace provider host. */
+export interface WorkspaceProviderHostLease {
+  cwd: string;
+  lspController: LspRuntimeController | null;
+  sentinelSnapshot: Map<string, number>;
+  release(): Promise<void>;
+}
+
+function registry(): HostRegistry {
+  const global = globalThis as typeof globalThis & { [HOSTS]?: HostRegistry };
+  global[HOSTS] ??= new Map();
+  return global[HOSTS];
+}
+
+function canonicalWorkspace(cwd: string): string {
+  try {
+    return realpathSync(cwd);
+  } catch {
+    return resolve(cwd);
+  }
+}
+
+function settleWithin(operation: Promise<void>): Promise<void> {
+  return Promise.race([
+    operation.catch(() => undefined),
+    new Promise<void>((resolveGrace) => {
+      const timeout = setTimeout(resolveGrace, SHUTDOWN_GRACE_MS);
+      timeout.unref?.();
+    }),
+  ]);
+}
+
+class WorkspaceProviderHost {
+  readonly cwd: string;
+  #leases = 0;
+  #lsp: LspRuntimeController | null = null;
+  #tree: TreeSitterRuntimeController | null = null;
+  #treeStarted = false;
+  #lspStarted = false;
+  #settledStart = Promise.resolve();
+  #closed = false;
+
+  constructor(cwd: string) {
+    this.cwd = cwd;
+  }
+
+  async acquire(projectTrusted: boolean): Promise<WorkspaceProviderHostLease> {
+    if (this.#closed) throw new Error("Workspace provider host is closed.");
+    // Count this pending acquirer before awaiting startup so the final active lease cannot shut it down.
+    this.#leases++;
+    this.#settledStart = this.#settledStart
+      .then(() => this.#startMissing(projectTrusted))
+      .catch(() => undefined);
+    await this.#settledStart;
+    let released = false;
+    return {
+      cwd: this.cwd,
+      lspController: projectTrusted ? this.#lsp : null,
+      sentinelSnapshot:
+        projectTrusted && this.#lsp?.kind === "ready"
+          ? scanWorkspaceSentinels(this.cwd)
+          : new Map(),
+      release: async () => {
+        if (released) return;
+        released = true;
+        this.#leases--;
+        if (this.#leases === 0) {
+          registry().delete(this.cwd);
+          await this.#shutdown();
+        }
+      },
+    };
+  }
+
+  async #startMissing(projectTrusted: boolean): Promise<void> {
+    const runtime = getDefaultWorkspaceRuntime();
+    if (!this.#treeStarted) {
+      this.#treeStarted = true;
+      this.#tree = new TreeSitterRuntimeController(this.cwd, runtime);
+      await this.#tree.start().catch(() => undefined);
+    }
+    if (!projectTrusted || this.#lspStarted) return;
+    this.#lspStarted = true;
+    this.#lsp = new LspRuntimeController(this.cwd, runtime);
+    await this.#lsp.start().catch(() => undefined);
+  }
+
+  async #shutdown(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    await Promise.all([
+      ...(this.#lsp ? [settleWithin(this.#lsp.shutdown())] : []),
+      ...(this.#tree ? [settleWithin(this.#tree.shutdown())] : []),
+    ]);
+    this.#lsp = null;
+    this.#tree = null;
+  }
+}
+
+/** Acquire shared semantic and structural providers for one canonical workspace. */
+export async function acquireWorkspaceProviderHost(
+  cwd: string,
+  options: { projectTrusted: boolean },
+): Promise<WorkspaceProviderHostLease> {
+  const workspace = canonicalWorkspace(cwd);
+  const hosts = registry();
+  let host = hosts.get(workspace);
+  if (!host) {
+    host = new WorkspaceProviderHost(workspace);
+    hosts.set(workspace, host);
+  }
+  return host.acquire(options.projectTrusted);
+}
+
+/** Clear process-shared hosts between isolated tests. */
+export function resetWorkspaceProviderHostsForTests(): void {
+  registry().clear();
+}

package/src/tool/graph/execute.ts

@@ -6,7 +6,7 @@ import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts
 import { searchErrorResult } from "../infra/error-results.ts";
 import { toWorkflowControl } from "../infra/workflow-control.ts";
 import { assembleGraphResult } from "../result/graph.ts";
-import { renderGraphResult } from "./markdown-base.ts";
+import { renderGraphResult } from "./markdown.ts";
 
 export type GraphRelation = RequestedGraphRelation;
 

package/src/tool/graph/markdown.ts

@@ -0,0 +1,222 @@
+/** Markdown adapter for assembled code_graph evidence. */
+
+import {
+  type EvidenceList,
+  type EvidenceListMetadata,
+  renderEvidenceListMetadataDisclosure,
+} from "../../analysis/evidence.ts";
+import { renderReadNextSection } from "../../analysis/read-next.ts";
+import {
+  compactLineRanges,
+  formatAssembledReferenceList,
+} from "../../analysis/references/semantic-refs.ts";
+import type {
+  CallEntry,
+  CalleeScope,
+  ImplementationEntry,
+  ReferenceEntry,
+} from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
+import type { GraphResultAssembly } from "../result/graph.ts";
+
+/** Render an assembled graph result. */
+export function renderGraphResult(assembly: GraphResultAssembly): string {
+  const lines = [
+    `# Graph of \`${assembly.displayName}\``,
+    "",
+    `_File: \`${assembly.resolvedDisplayFile}\`_`,
+    "",
+  ];
+
+  const available = assembly.sections.filter((section) => section.kind === "ok");
+  if (available.length > 0) {
+    lines.push(
+      available
+        .map(
+          (section) =>
+            `**${section.rel}**: ${sectionCount(section)} result${sectionCount(section) === 1 ? "" : "s"}`,
+        )
+        .join(" | "),
+      "",
+    );
+  }
+
+  const unavailable = assembly.sections.filter((section) => section.kind === "unavailable");
+  if (unavailable.length > 0) {
+    lines.push(
+      `_Unavailable: ${unavailable.map((section) => `\`${section.rel}\``).join(", ")}_`,
+      "",
+    );
+  }
+
+  for (const section of assembly.sections) {
+    if (section.kind === "unavailable") {
+      lines.push(`**${section.rel}**: ${section.message}`, "");
+      continue;
+    }
+
+    switch (section.rel) {
+      case "references": {
+        const rendered = renderReferencesResult({
+          symbolName: assembly.displayName,
+          references: section.evidence,
+          externalCount: section.data.externalCount,
+          confidence: section.data.confidence,
+          cwd: assembly.cwd,
+        });
+        lines.push(rendered.content, "");
+        break;
+      }
+      case "callees": {
+        const rendered = renderCallsResult(
+          section.data.enclosingScope,
+          section.evidence,
+          assembly.resolvedDisplayFile,
+          section.data.depth,
+        );
+        lines.push(rendered.content, "");
+        break;
+      }
+      case "implements": {
+        const rendered = renderImplementationsResult({
+          implementations: section.evidence,
+          externalCount: section.data.externalCount,
+          cwd: assembly.cwd,
+          targetName: assembly.displayName,
+        });
+        lines.push(rendered.content, "");
+        break;
+      }
+    }
+  }
+
+  lines.push(...renderReadNextSection(available.flatMap((section) => section.readNext)));
+  return lines.join("\n");
+}
+
+function sectionCount(
+  section: Extract<GraphResultAssembly["sections"][number], { kind: "ok" }>,
+): number {
+  return section.evidence.metadata.totalCount ?? section.evidence.metadata.shownCount;
+}
+
+function renderReferencesResult(options: {
+  symbolName: string;
+  references: EvidenceList<ReferenceEntry>;
+  externalCount: number;
+  confidence: string;
+  cwd: string;
+}): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const total = options.references.metadata.totalCount ?? options.references.metadata.shownCount;
+  const lines = [
+    `# References of \`${options.symbolName}\``,
+    "",
+    `**${total} reference${total === 1 ? "" : "s"}** (${options.confidence})`,
+  ];
+  if (options.externalCount > 0) {
+    lines.push(
+      `_+${options.externalCount} external reference${options.externalCount === 1 ? "" : "s"}_`,
+    );
+  }
+  const invalidDisclosure = renderInvalidProviderLocations(options.references.metadata);
+  if (invalidDisclosure) lines.push(invalidDisclosure);
+  lines.push("");
+
+  const displayEvidence = {
+    key: options.references.key,
+    items: options.references.items.map((reference) => ({
+      file: toDisplayPath(options.cwd, reference.file),
+      line: reference.line,
+    })),
+    metadata: options.references.metadata,
+  };
+  const evidenceList = formatAssembledReferenceList(lines, displayEvidence);
+  return { content: lines.join("\n"), evidenceList };
+}
+
+function renderCallsResult(
+  enclosingScope: CalleeScope,
+  calls: EvidenceList<CallEntry>,
+  relPath: string,
+  depth: "direct" | "deep" = "direct",
+): { content: string; evidenceList: EvidenceListMetadata } {
+  const lines: string[] = [];
+  const depthLabel = depth === "deep" ? "Deep structural calls" : "Direct structural calls";
+  const depthNote =
+    depth === "deep"
+      ? "_Deep: includes calls from nested function/method/callback scopes within the enclosing scope._"
+      : "_Structural only: call expressions are reported by source shape, not symbol identity; calls inside nested function/method/callback scopes are excluded from this enclosing scope._";
+  const total = calls.metadata.totalCount ?? calls.metadata.shownCount;
+
+  lines.push(`# ${depthLabel} from \`${enclosingScope.name}\``, "");
+  lines.push(
+    `**${total} ${depth === "deep" ? "" : "direct "}structural call${total === 1 ? "" : "s"}** from enclosing scope \`${enclosingScope.name}\` (${formatScopeRange(enclosingScope)}) in \`${relPath}\``,
+    "",
+    depthNote,
+    "",
+  );
+
+  for (const call of calls.items) lines.push(`- \`${call.name}\` (L${call.line})`);
+  const disclosure = renderEvidenceListMetadataDisclosure(calls.metadata);
+  if (disclosure) lines.push(disclosure);
+  return { content: lines.join("\n"), evidenceList: calls.metadata };
+}
+
+function renderImplementationsResult(options: {
+  implementations: EvidenceList<ImplementationEntry>;
+  externalCount: number;
+  cwd: string;
+  targetName?: string;
+}): { content: string; evidenceList: EvidenceListMetadata } {
+  const lines: string[] = [
+    options.targetName
+      ? `# Implementations of \`${options.targetName}\` (semantic)`
+      : "# Implementations (semantic)",
+    "",
+  ];
+  const total =
+    options.implementations.metadata.totalCount ?? options.implementations.metadata.shownCount;
+  if (total > 0) {
+    lines.push(`**${total} implementation${total === 1 ? "" : "s"}** in the project`, "");
+    for (const [file, locations] of groupByFile(options.implementations.items, options.cwd)) {
+      lines.push(`### ${file}`, `- ${compactLineRanges(locations)}`, "");
+    }
+    const disclosure = renderEvidenceListMetadataDisclosure(options.implementations.metadata);
+    if (disclosure) lines.push(disclosure);
+  }
+
+  if (options.externalCount > 0) {
+    lines.push(
+      `_+${options.externalCount} external location${options.externalCount === 1 ? "" : "s"} (outside this project)_`,
+      "",
+    );
+  }
+  const invalidDisclosure = renderInvalidProviderLocations(options.implementations.metadata);
+  if (invalidDisclosure) lines.push(invalidDisclosure, "");
+
+  return { content: lines.join("\n"), evidenceList: options.implementations.metadata };
+}
+
+function formatScopeRange(scope: CalleeScope): string {
+  if (scope.startLine === scope.endLine) return `L${scope.startLine}`;
+  return `L${scope.startLine}–L${scope.endLine}`;
+}
+
+function groupByFile(impls: readonly ImplementationEntry[], cwd: string): Map<string, number[]> {
+  const byFile = new Map<string, number[]>();
+  for (const impl of impls) {
+    const displayPath = toDisplayPath(cwd, impl.file);
+    const group = byFile.get(displayPath) ?? [];
+    group.push(impl.line);
+    byFile.set(displayPath, group);
+  }
+  return byFile;
+}
+
+/** Render an explicit disclosure for unusable semantic-provider locations. */
+function renderInvalidProviderLocations(metadata: EvidenceListMetadata): string | null {
+  const count = metadata.invalidLocationCount ?? 0;
+  if (count <= 0 || metadata.partialReason === null) return null;
+  const noun = count === 1 ? "location" : "locations";
+  return `_${count} invalid provider ${noun} omitted (${metadata.partialReason})_`;
+}