@mrclrchtr/supi-code-intelligence 1.4.0 → 1.6.0

package/node_modules/@mrclrchtr/supi-lsp/src/tool/guidance.ts

@@ -2,15 +2,8 @@
 
 import * as path from "node:path";
 import type { ProjectServerInfo } from "../config/types.ts";
-import {
-  LSP_DIAGNOSTICS_TOOL,
-  LSP_DOCUMENT_SYMBOLS_TOOL,
-  LSP_LOOKUP_TOOL,
-  LSP_RECOVER_TOOL,
-  LSP_REFACTOR_TOOL,
-  LSP_WORKSPACE_SYMBOLS_TOOL,
-  type LspToolName,
-} from "./names.ts";
+import { LSP_LOOKUP_TOOL, type LspToolName } from "./names.ts";
+import { LSP_TOOL_DEFINITION_SPECS } from "./tool-specs.ts";
 
 export interface LspToolPromptSurface {
   description: string;
@@ -20,33 +13,6 @@ export interface LspToolPromptSurface {
 
 export type LspToolPromptSurfaceMap = Record<LspToolName, LspToolPromptSurface>;
 
-const LOOKUP_GUIDELINES = [
-  'Use lsp_lookup with `kind: "hover"` for semantic type or symbol information at a known `file`, `line`, and `character`.',
-  'Use lsp_lookup with `kind: "definition"`, `"references"`, or `"implementation"` for semantic navigation at a known position.',
-  "Use lsp_lookup after code_intel or tree_sitter has already narrowed the target file and position.",
-];
-
-const DOCUMENT_SYMBOL_GUIDELINES = [
-  "Use lsp_document_symbols(file) for semantic declarations in one supported file.",
-];
-
-const WORKSPACE_SYMBOL_GUIDELINES = [
-  "Use lsp_workspace_symbols(query) for semantic symbol-name lookup across the current project.",
-];
-
-const DIAGNOSTICS_GUIDELINES = [
-  "Use lsp_diagnostics(file?) when you need current diagnostics for one file or a workspace-level summary.",
-];
-
-const REFACTOR_GUIDELINES = [
-  'Use lsp_refactor with `kind: "rename"` for semantic rename planning at a known `file`, `line`, and `character`.',
-  'Use lsp_refactor with `kind: "code_actions"` for semantic fixes or refactors at a known position.',
-];
-
-const RECOVER_GUIDELINES = [
-  "Use lsp_recover() when diagnostics look stale after workspace-level changes or generated-file updates.",
-];
-
 export const defaultLspToolPromptSurfaces = buildLspToolPromptSurfaces([], ".");
 
 export function buildLspToolPromptSurfaces(
@@ -55,45 +21,19 @@ export function buildLspToolPromptSurfaces(
 ): LspToolPromptSurfaceMap {
   const coverageGuidelines = buildCoverageGuidelines(servers, cwd);
 
-  return {
-    [LSP_LOOKUP_TOOL]: {
-      description:
-        "Language Server Protocol lookup tool — semantic hover, definition, references, and implementation for supported files. Use lsp_lookup when you know the file and 1-based line/character position and need semantic drill-down rather than text search.",
-      promptSnippet:
-        "lsp_lookup — semantic hover/definition/references/implementation at a known file position",
-      promptGuidelines: [...LOOKUP_GUIDELINES, ...coverageGuidelines],
-    },
-    [LSP_DOCUMENT_SYMBOLS_TOOL]: {
-      description:
-        "Language Server Protocol document symbols tool — list semantic declarations in one supported file. Use lsp_document_symbols when you need a symbol-aware outline rather than raw text structure.",
-      promptSnippet: "lsp_document_symbols — semantic declarations for one supported file",
-      promptGuidelines: DOCUMENT_SYMBOL_GUIDELINES,
-    },
-    [LSP_WORKSPACE_SYMBOLS_TOOL]: {
-      description:
-        "Language Server Protocol workspace symbols tool — semantic symbol-name lookup across the current project. Use lsp_workspace_symbols to find declarations by name before opening a specific file.",
-      promptSnippet: "lsp_workspace_symbols — semantic symbol-name lookup across the project",
-      promptGuidelines: WORKSPACE_SYMBOL_GUIDELINES,
-    },
-    [LSP_DIAGNOSTICS_TOOL]: {
-      description:
-        "Language Server Protocol diagnostics tool — current diagnostics for one file or a workspace summary. Use lsp_diagnostics for semantic compiler or language-server issues instead of guessing from text alone.",
-      promptSnippet: "lsp_diagnostics — current diagnostics for one file or the workspace",
-      promptGuidelines: DIAGNOSTICS_GUIDELINES,
-    },
-    [LSP_REFACTOR_TOOL]: {
-      description:
-        "Language Server Protocol refactor tool — semantic rename planning and code actions at a known file position. Use lsp_refactor when you need language-server-backed edits or quick-fix suggestions.",
-      promptSnippet: "lsp_refactor — semantic rename planning and code actions at a known position",
-      promptGuidelines: REFACTOR_GUIDELINES,
-    },
-    [LSP_RECOVER_TOOL]: {
-      description:
-        "Language Server Protocol recover tool — refresh diagnostics after workspace changes and stale language-server state. Use lsp_recover when new files, generated types, or config updates leave diagnostics out of sync.",
-      promptSnippet: "lsp_recover — refresh stale diagnostics after workspace changes",
-      promptGuidelines: RECOVER_GUIDELINES,
-    },
-  };
+  return Object.fromEntries(
+    LSP_TOOL_DEFINITION_SPECS.map((spec) => [
+      spec.name,
+      {
+        description: spec.description,
+        promptSnippet: spec.promptSnippet,
+        promptGuidelines:
+          "includeCoverageGuidelines" in spec && spec.includeCoverageGuidelines
+            ? [...spec.basePromptGuidelines, ...coverageGuidelines]
+            : [...spec.basePromptGuidelines],
+      } satisfies LspToolPromptSurface,
+    ]),
+  ) as LspToolPromptSurfaceMap;
 }
 
 function buildCoverageGuidelines(servers: ProjectServerInfo[], cwd: string): string[] {

package/node_modules/@mrclrchtr/supi-lsp/src/tool/register-tools.ts

@@ -1,160 +1,22 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import { getSessionLspService } from "../session/service-registry.ts";
 import type { LspToolPromptSurfaceMap } from "./guidance.ts";
-import {
-  LSP_DIAGNOSTICS_TOOL,
-  LSP_DOCUMENT_SYMBOLS_TOOL,
-  LSP_LOOKUP_TOOL,
-  LSP_RECOVER_TOOL,
-  LSP_REFACTOR_TOOL,
-  LSP_WORKSPACE_SYMBOLS_TOOL,
-} from "./names.ts";
-import {
-  executeDiagnostics,
-  executeDocumentSymbols,
-  executeLookup,
-  executeRecover,
-  executeRefactor,
-  executeWorkspaceSymbols,
-} from "./service-actions.ts";
-
-const FileParam = Type.String({ description: "File path (relative or absolute)" });
-const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
-const CharacterParam = Type.Number({ description: "1-based column number", minimum: 1 });
-const QueryParam = Type.String({ description: "Symbol query string" });
-const NewNameParam = Type.String({ description: "New name for rename" });
-
-const LookupKindEnum = StringEnum(["hover", "definition", "references", "implementation"] as const);
-
-const RefactorKindEnum = StringEnum(["rename", "code_actions"] as const);
-
-const LookupParameters = Type.Object(
-  {
-    kind: LookupKindEnum,
-    file: FileParam,
-    line: LineParam,
-    character: CharacterParam,
-  },
-  { additionalProperties: false },
-);
-
-const DocumentSymbolsParameters = Type.Object(
-  {
-    file: FileParam,
-  },
-  { additionalProperties: false },
-);
-
-const WorkspaceSymbolsParameters = Type.Object(
-  {
-    query: QueryParam,
-  },
-  { additionalProperties: false },
-);
-
-const DiagnosticsParameters = Type.Object(
-  {
-    file: Type.Optional(FileParam),
-  },
-  { additionalProperties: false },
-);
-
-const RefactorParameters = Type.Object(
-  {
-    kind: RefactorKindEnum,
-    file: FileParam,
-    line: LineParam,
-    character: CharacterParam,
-    newName: Type.Optional(NewNameParam),
-  },
-  { additionalProperties: false },
-);
-
-const RecoverParameters = Type.Object({}, { additionalProperties: false });
+import { LSP_TOOL_DEFINITION_SPECS } from "./tool-specs.ts";
 
 /** Register the expert LSP toolset. Tools are re-registered on session_start to refresh guidance. */
 export function registerLspTools(pi: ExtensionAPI, promptSurfaces: LspToolPromptSurfaceMap): void {
-  const lookupSurface = promptSurfaces[LSP_LOOKUP_TOOL];
-  pi.registerTool({
-    name: LSP_LOOKUP_TOOL,
-    label: "LSP Lookup",
-    description: lookupSurface.description,
-    promptSnippet: lookupSurface.promptSnippet,
-    promptGuidelines: lookupSurface.promptGuidelines,
-    parameters: LookupParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeLookup(service, cwd, params as Parameters<typeof executeLookup>[2]),
-    ),
-  });
-
-  const documentSymbolsSurface = promptSurfaces[LSP_DOCUMENT_SYMBOLS_TOOL];
-  pi.registerTool({
-    name: LSP_DOCUMENT_SYMBOLS_TOOL,
-    label: "LSP Document Symbols",
-    description: documentSymbolsSurface.description,
-    promptSnippet: documentSymbolsSurface.promptSnippet,
-    promptGuidelines: documentSymbolsSurface.promptGuidelines,
-    parameters: DocumentSymbolsParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeDocumentSymbols(service, cwd, params as Parameters<typeof executeDocumentSymbols>[2]),
-    ),
-  });
-
-  const workspaceSymbolsSurface = promptSurfaces[LSP_WORKSPACE_SYMBOLS_TOOL];
-  pi.registerTool({
-    name: LSP_WORKSPACE_SYMBOLS_TOOL,
-    label: "LSP Workspace Symbols",
-    description: workspaceSymbolsSurface.description,
-    promptSnippet: workspaceSymbolsSurface.promptSnippet,
-    promptGuidelines: workspaceSymbolsSurface.promptGuidelines,
-    parameters: WorkspaceSymbolsParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeWorkspaceSymbols(
-        service,
-        cwd,
-        params as Parameters<typeof executeWorkspaceSymbols>[2],
-      ),
-    ),
-  });
-
-  const diagnosticsSurface = promptSurfaces[LSP_DIAGNOSTICS_TOOL];
-  pi.registerTool({
-    name: LSP_DIAGNOSTICS_TOOL,
-    label: "LSP Diagnostics",
-    description: diagnosticsSurface.description,
-    promptSnippet: diagnosticsSurface.promptSnippet,
-    promptGuidelines: diagnosticsSurface.promptGuidelines,
-    parameters: DiagnosticsParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeDiagnostics(service, cwd, params as Parameters<typeof executeDiagnostics>[2]),
-    ),
-  });
-
-  const refactorSurface = promptSurfaces[LSP_REFACTOR_TOOL];
-  pi.registerTool({
-    name: LSP_REFACTOR_TOOL,
-    label: "LSP Refactor",
-    description: refactorSurface.description,
-    promptSnippet: refactorSurface.promptSnippet,
-    promptGuidelines: refactorSurface.promptGuidelines,
-    parameters: RefactorParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeRefactor(service, cwd, params as Parameters<typeof executeRefactor>[2]),
-    ),
-  });
-
-  const recoverSurface = promptSurfaces[LSP_RECOVER_TOOL];
-  pi.registerTool({
-    name: LSP_RECOVER_TOOL,
-    label: "LSP Recover",
-    description: recoverSurface.description,
-    promptSnippet: recoverSurface.promptSnippet,
-    promptGuidelines: recoverSurface.promptGuidelines,
-    parameters: RecoverParameters,
-    execute: createRecoverToolExecutor(),
-  });
+  for (const spec of LSP_TOOL_DEFINITION_SPECS) {
+    const surface = promptSurfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface.description,
+      promptSnippet: surface.promptSnippet,
+      promptGuidelines: surface.promptGuidelines,
+      parameters: spec.parameters,
+      execute: createToolExecutor(spec.run),
+    });
+  }
 }
 
 function getReadyService(cwd: string) {
@@ -201,21 +63,6 @@ function createToolExecutor(
   };
 }
 
-function createRecoverToolExecutor() {
-  // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-  return async (
-    _toolCallId: string,
-    _params: unknown,
-    _signal: AbortSignal | undefined,
-    _onUpdate: unknown,
-    ctx: ExtensionContext,
-  ) => {
-    const service = getReadyService(ctx.cwd);
-    const text = service ? await executeRecover(service) : describeUnavailableService(ctx.cwd);
-    return makeTextResult(text);
-  };
-}
-
 function makeTextResult(text: string) {
   return {
     content: [{ type: "text" as const, text }],

package/node_modules/@mrclrchtr/supi-lsp/src/tool/tool-specs.ts

@@ -0,0 +1,248 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+import type { ServerCapabilities } from "../config/types.ts";
+import type { SessionLspService } from "../session/service-registry.ts";
+import {
+  LSP_DIAGNOSTICS_TOOL,
+  LSP_DOCUMENT_SYMBOLS_TOOL,
+  LSP_LOOKUP_TOOL,
+  LSP_RECOVER_TOOL,
+  LSP_REFACTOR_TOOL,
+  LSP_WORKSPACE_SYMBOLS_TOOL,
+  type LspToolName,
+} from "./names.ts";
+import {
+  executeDiagnostics,
+  executeDocumentSymbols,
+  executeLookup,
+  executeRecover,
+  executeRefactor,
+  executeWorkspaceSymbols,
+} from "./service-actions.ts";
+
+const FileParam = Type.String({ description: "File path (relative or absolute)" });
+const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+const CharacterParam = Type.Number({ description: "1-based column number", minimum: 1 });
+const QueryParam = Type.String({ description: "Symbol query string" });
+const NewNameParam = Type.String({ description: "New name for rename" });
+
+export const LSP_LOOKUP_KIND_NAMES = [
+  "hover",
+  "definition",
+  "references",
+  "implementation",
+] as const;
+export const LSP_REFACTOR_KIND_NAMES = ["rename", "code_actions"] as const;
+
+const LookupKindEnum = StringEnum(LSP_LOOKUP_KIND_NAMES);
+const RefactorKindEnum = StringEnum(LSP_REFACTOR_KIND_NAMES);
+
+const LookupParameters = Type.Object(
+  {
+    kind: LookupKindEnum,
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+  },
+  { additionalProperties: false },
+);
+
+const DocumentSymbolsParameters = Type.Object(
+  {
+    file: FileParam,
+  },
+  { additionalProperties: false },
+);
+
+const WorkspaceSymbolsParameters = Type.Object(
+  {
+    query: QueryParam,
+  },
+  { additionalProperties: false },
+);
+
+const DiagnosticsParameters = Type.Object(
+  {
+    file: Type.Optional(FileParam),
+  },
+  { additionalProperties: false },
+);
+
+const RefactorParameters = Type.Object(
+  {
+    kind: RefactorKindEnum,
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+    newName: Type.Optional(NewNameParam),
+  },
+  { additionalProperties: false },
+);
+
+const RecoverParameters = Type.Object({}, { additionalProperties: false });
+
+export interface LspToolDefinitionSpec {
+  name: LspToolName;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  basePromptGuidelines: string[];
+  parameters: TSchema;
+  run: (service: SessionLspService, cwd: string, params: unknown) => Promise<string>;
+  includeCoverageGuidelines?: boolean;
+}
+
+export const LSP_TOOL_DEFINITION_SPECS = [
+  {
+    name: LSP_LOOKUP_TOOL,
+    label: "LSP Lookup",
+    description:
+      "Language Server Protocol lookup tool — semantic hover, definition, references, and implementation for supported files. Use lsp_lookup when you know the file and 1-based line/character position and need semantic drill-down rather than text search.",
+    promptSnippet:
+      "lsp_lookup — semantic hover/definition/references/implementation at a known file position",
+    basePromptGuidelines: [
+      'Use lsp_lookup with `kind: "hover"` for semantic type or symbol information at a known `file`, `line`, and `character`.',
+      'Use lsp_lookup with `kind: "definition"`, `"references"`, or `"implementation"` for semantic navigation at a known position.',
+      "Use lsp_lookup after code_intel or tree_sitter has already narrowed the target file and position.",
+    ],
+    parameters: LookupParameters,
+    run: (service, cwd, params) =>
+      executeLookup(service, cwd, params as Parameters<typeof executeLookup>[2]),
+    includeCoverageGuidelines: true,
+  },
+  {
+    name: LSP_DOCUMENT_SYMBOLS_TOOL,
+    label: "LSP Document Symbols",
+    description:
+      "Language Server Protocol document symbols tool — list semantic declarations in one supported file. Use lsp_document_symbols when you need a symbol-aware outline rather than raw text structure.",
+    promptSnippet: "lsp_document_symbols — semantic declarations for one supported file",
+    basePromptGuidelines: [
+      "Use lsp_document_symbols(file) for semantic declarations in one supported file.",
+    ],
+    parameters: DocumentSymbolsParameters,
+    run: (service, cwd, params) =>
+      executeDocumentSymbols(service, cwd, params as Parameters<typeof executeDocumentSymbols>[2]),
+  },
+  {
+    name: LSP_WORKSPACE_SYMBOLS_TOOL,
+    label: "LSP Workspace Symbols",
+    description:
+      "Language Server Protocol workspace symbols tool — semantic symbol-name lookup across the current project. Use lsp_workspace_symbols to find declarations by name before opening a specific file.",
+    promptSnippet: "lsp_workspace_symbols — semantic symbol-name lookup across the project",
+    basePromptGuidelines: [
+      "Use lsp_workspace_symbols(query) for semantic symbol-name lookup across the current project.",
+    ],
+    parameters: WorkspaceSymbolsParameters,
+    run: (service, cwd, params) =>
+      executeWorkspaceSymbols(
+        service,
+        cwd,
+        params as Parameters<typeof executeWorkspaceSymbols>[2],
+      ),
+  },
+  {
+    name: LSP_DIAGNOSTICS_TOOL,
+    label: "LSP Diagnostics",
+    description:
+      "Language Server Protocol diagnostics tool — current diagnostics for one file or a workspace summary. Use lsp_diagnostics for semantic compiler or language-server issues instead of guessing from text alone.",
+    promptSnippet: "lsp_diagnostics — current diagnostics for one file or the workspace",
+    basePromptGuidelines: [
+      "Use lsp_diagnostics(file?) when you need current diagnostics for one file or a workspace-level summary.",
+    ],
+    parameters: DiagnosticsParameters,
+    run: (service, cwd, params) =>
+      executeDiagnostics(service, cwd, params as Parameters<typeof executeDiagnostics>[2]),
+  },
+  {
+    name: LSP_REFACTOR_TOOL,
+    label: "LSP Refactor",
+    description:
+      "Language Server Protocol refactor tool — semantic rename planning and code actions at a known file position. Use lsp_refactor when you need language-server-backed edits or quick-fix suggestions.",
+    promptSnippet: "lsp_refactor — semantic rename planning and code actions at a known position",
+    basePromptGuidelines: [
+      'Use lsp_refactor with `kind: "rename"` for semantic rename planning at a known `file`, `line`, and `character`.',
+      'Use lsp_refactor with `kind: "code_actions"` for semantic fixes or refactors at a known position.',
+    ],
+    parameters: RefactorParameters,
+    run: (service, cwd, params) =>
+      executeRefactor(service, cwd, params as Parameters<typeof executeRefactor>[2]),
+  },
+  {
+    name: LSP_RECOVER_TOOL,
+    label: "LSP Recover",
+    description:
+      "Language Server Protocol recover tool — refresh diagnostics after workspace changes and stale language-server state. Use lsp_recover when new files, generated types, or config updates leave diagnostics out of sync.",
+    promptSnippet: "lsp_recover — refresh stale diagnostics after workspace changes",
+    basePromptGuidelines: [
+      "Use lsp_recover() when diagnostics look stale after workspace-level changes or generated-file updates.",
+    ],
+    parameters: RecoverParameters,
+    run: (service) => executeRecover(service),
+  },
+] as const satisfies readonly LspToolDefinitionSpec[];
+
+const LSP_TOOL_SPEC_MAP = new Map<LspToolName, LspToolDefinitionSpec>(
+  LSP_TOOL_DEFINITION_SPECS.map((spec) => [spec.name, spec]),
+);
+
+export function getLspToolDefinitionSpec(toolName: LspToolName): LspToolDefinitionSpec {
+  const spec = LSP_TOOL_SPEC_MAP.get(toolName);
+  if (!spec) {
+    throw new Error(`Unknown LSP tool: ${toolName}`);
+  }
+  return spec;
+}
+
+interface LspServerSupportedActionSpec {
+  label: string;
+  isSupported: (capabilities: ServerCapabilities | null | undefined) => boolean;
+}
+
+const LSP_SERVER_SUPPORTED_ACTION_SPECS: readonly LspServerSupportedActionSpec[] = [
+  {
+    label: "diagnostics [optional file]",
+    isSupported: () => true,
+  },
+  {
+    label: "hover(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.hoverProvider),
+  },
+  {
+    label: "definition(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.definitionProvider),
+  },
+  {
+    label: "references(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.referencesProvider),
+  },
+  {
+    label: "implementation(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.implementationProvider),
+  },
+  {
+    label: "symbols(file)",
+    isSupported: (capabilities) => Boolean(capabilities?.documentSymbolProvider),
+  },
+  {
+    label: "workspace_symbols(query)",
+    isSupported: (capabilities) => Boolean(capabilities?.workspaceSymbolProvider),
+  },
+  {
+    label: "rename(file,line,char,newName)",
+    isSupported: (capabilities) => Boolean(capabilities?.renameProvider),
+  },
+  {
+    label: "code_actions(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.codeActionProvider),
+  },
+] as const;
+
+export function getSupportedLspServerActions(
+  capabilities: ServerCapabilities | null | undefined,
+): string[] {
+  if (!capabilities) return [];
+
+  return LSP_SERVER_SUPPORTED_ACTION_SPECS.filter((spec) => spec.isSupported(capabilities)).map(
+    (spec) => spec.label,
+  );
+}

package/node_modules/@mrclrchtr/supi-lsp/src/utils.ts

@@ -2,41 +2,12 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-// ── URI Handling ──────────────────────────────────────────────────────
 
-/** Convert a file path to a file:// URI. */
-export function fileToUri(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  if (process.platform === "win32") {
-    return `file:///${resolved.replace(/\\/g, "/")}`;
-  }
-  return `file://${resolved}`;
-}
-
-/** Convert a file:// URI to a file path. */
-export function uriToFile(uri: string): string {
-  if (!uri.startsWith("file://")) return uri;
-  let filePath = decodeURIComponent(uri.slice(7));
-  if (
-    process.platform === "win32" &&
-    filePath.startsWith("/") &&
-    /^[A-Za-z]:/.test(filePath.slice(1))
-  ) {
-    filePath = filePath.slice(1);
-  }
-  return filePath;
-}
-
-/**
- * Resolve a tool-style file path against the active session cwd.
- *
- * Built-in pi file tools accept a leading `@` prefix in path arguments, so LSP
- * helpers strip that prefix as well before resolving relative paths.
- */
-export function resolveSessionPath(cwd: string, filePath: string): string {
-  const normalizedPath = filePath.startsWith("@") ? filePath.slice(1) : filePath;
-  return path.resolve(cwd, normalizedPath);
-}
+export {
+  fileToUri,
+  resolveToolPath as resolveSessionPath,
+  uriToFile,
+} from "@mrclrchtr/supi-core/api";
 
 // ── Language ID Detection ─────────────────────────────────────────────
 

package/node_modules/@mrclrchtr/supi-tree-sitter/README.md

@@ -33,7 +33,7 @@ After install, pi gets one tool:
 | `query` | Run a custom Tree-sitter query against a file | Any supported grammar |
 | `callees` | Find outgoing calls from the enclosing function or method at a position | Supported for most grammars, but not all |
 
-Coordinates use **1-based** line and character columns. Character positions use UTF-16 code units.
+Coordinates use **1-based** line and character columns. Character positions use UTF-16 code units. Relative paths resolve from the session cwd, and a leading `@` on file paths is stripped.
 
 ## Supported file families
 
@@ -54,10 +54,10 @@ The current tool description covers:
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory and shared result types
+- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory, shared session-scoped structural service access, and shared result types
 - `@mrclrchtr/supi-tree-sitter/extension` — pi extension entrypoint
 
-Example:
+Owned session example:
 
 ```ts
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
@@ -71,9 +71,21 @@ const callees = await session.calleesAt("src/index.ts", 42, 10);
 session.dispose();
 ```
 
+Shared session-scoped service example:
+
+```ts
+import { getSessionTreeSitterService } from "@mrclrchtr/supi-tree-sitter/api";
+
+const state = getSessionTreeSitterService("/project");
+if (state.kind === "ready") {
+  const outline = await state.service.outline("src/index.ts");
+}
+```
+
 ## Source
 
 - `src/tree-sitter.ts` — tool registration and action handling
-- `src/runtime.ts` — parser and query runtime
-- `src/session.ts` — reusable session API
-- `src/outline.ts`, `src/imports.ts`, `src/exports.ts`, `src/node-at.ts`, `src/callees.ts` — structural analyses
+- `src/session/runtime.ts` — parser and query runtime
+- `src/session/session.ts` — runtime-backed service helpers and owned session API
+- `src/session/service-registry.ts` — shared session-scoped structural service registry
+- `src/tool/outline.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts` — structural analyses