@mrclrchtr/supi-tree-sitter 1.3.1 → 1.5.0

package/src/index.ts

@@ -1,6 +1,7 @@
-// Public session factory and re-exports for @mrclrchtr/supi-tree-sitter.
+// Public session factory, shared session service access, and re-exports for @mrclrchtr/supi-tree-sitter.
 
-export { createTreeSitterSession } from "./session.ts";
+export { getSessionTreeSitterService } from "./session/service-registry.ts";
+export { createTreeSitterSession } from "./session/session.ts";
 export type {
   CalleesAtResult,
   ExportRecord,
@@ -9,8 +10,11 @@ export type {
   NodeAtResult,
   OutlineItem,
   QueryCapture,
+  SessionTreeSitterService,
+  SessionTreeSitterServiceState,
   SourceRange,
   SupportedExtension,
   TreeSitterResult,
+  TreeSitterService,
   TreeSitterSession,
 } from "./types.ts";

package/src/{runtime.ts → session/runtime.ts}

@@ -2,10 +2,11 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { resolveToolPath } from "@mrclrchtr/supi-core/api";
 import type { Language, Parser, Tree } from "web-tree-sitter";
-import { nodeToRange } from "./coordinates.ts";
-import { detectGrammar, resolveGrammarWasmPath } from "./language.ts";
-import type { GrammarId, QueryCapture, TreeSitterResult } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import { detectGrammar, resolveGrammarWasmPath } from "../language.ts";
+import type { GrammarId, QueryCapture, TreeSitterResult } from "../types.ts";
 
 interface ParserEntry {
   parser: Parser;
@@ -113,7 +114,7 @@ export class TreeSitterRuntime {
       grammarId: GrammarId;
     }>
   > {
-    const resolvedPath = path.resolve(this.cwd, filePath);
+    const resolvedPath = resolveToolPath(this.cwd, filePath);
 
     // Check language support first
     const grammarId = detectGrammar(filePath);
@@ -212,7 +213,7 @@ export class TreeSitterRuntime {
 
   /** Resolve a file path from cwd. */
   resolvePath(filePath: string): string {
-    return path.resolve(this.cwd, filePath);
+    return resolveToolPath(this.cwd, filePath);
   }
 
   /** Dispose all held parser resources. */

package/src/session/service-registry.ts

@@ -0,0 +1,30 @@
+// Shared session-scoped Tree-sitter service registry.
+// Peer extensions can import `getSessionTreeSitterService` from the package API
+// to reuse the active structural runtime without creating duplicate sessions.
+
+import { createSessionStateRegistry } from "@mrclrchtr/supi-core/api";
+import type { SessionTreeSitterService, SessionTreeSitterServiceState } from "../types.ts";
+
+const registry = createSessionStateRegistry<SessionTreeSitterServiceState>(
+  "supi-tree-sitter/session-registry",
+);
+
+/** Publish the shared Tree-sitter service for one session cwd. */
+export function setSessionTreeSitterService(cwd: string, service: SessionTreeSitterService): void {
+  registry.set(cwd, { kind: "ready", service });
+}
+
+/** Acquire the shared Tree-sitter service state for one session cwd. */
+export function getSessionTreeSitterService(cwd: string): SessionTreeSitterServiceState {
+  return (
+    registry.get(cwd) ?? {
+      kind: "unavailable",
+      reason: "No Tree-sitter session initialized for this workspace",
+    }
+  );
+}
+
+/** Remove the shared Tree-sitter service for one session cwd. */
+export function clearSessionTreeSitterService(cwd: string): void {
+  registry.clear(cwd);
+}

package/src/{session.ts → session/session.ts}

@@ -1,14 +1,13 @@
-// Session factory — creates a TreeSitterSession bound to a working directory.
+// Session factory — creates runtime-backed Tree-sitter services and owned sessions.
 
-import { detectGrammar, isJsTsGrammar } from "./language.ts";
-import { TreeSitterRuntime } from "./runtime.ts";
+import { detectGrammar, isJsTsGrammar } from "../language.ts";
 import {
   extractExports,
   extractImports,
   extractOutline,
   lookupCalleesAt,
   lookupNodeAt,
-} from "./structure.ts";
+} from "../tool/structure.ts";
 import type {
   CalleesAtResult,
   ExportRecord,
@@ -17,16 +16,13 @@ import type {
   OutlineItem,
   QueryCapture,
   TreeSitterResult,
+  TreeSitterService,
   TreeSitterSession,
-} from "./types.ts";
-
-/**
- * Create a new Tree-sitter session bound to the given working directory.
- * The session owns parser/grammar reuse and must be disposed when done.
- */
-export function createTreeSitterSession(cwd: string): TreeSitterSession {
-  const runtime = new TreeSitterRuntime(cwd);
+} from "../types.ts";
+import { TreeSitterRuntime } from "./runtime.ts";
 
+/** Create a runtime-backed structural service without taking ownership of disposal. */
+export function createTreeSitterService(runtime: TreeSitterRuntime): TreeSitterService {
   return {
     async canParse(file: string) {
       const result = await runtime.parseFile(file);
@@ -104,7 +100,19 @@ export function createTreeSitterSession(cwd: string): TreeSitterSession {
     ): Promise<TreeSitterResult<CalleesAtResult>> {
       return lookupCalleesAt(runtime, file, line, character);
     },
+  };
+}
 
+/**
+ * Create a new Tree-sitter session bound to the given working directory.
+ * The session owns parser/grammar reuse and must be disposed when done.
+ */
+export function createTreeSitterSession(cwd: string): TreeSitterSession {
+  const runtime = new TreeSitterRuntime(cwd);
+  const service = createTreeSitterService(runtime);
+
+  return {
+    ...service,
     dispose() {
       runtime.dispose();
     },

package/src/tool/action-specs.ts

@@ -0,0 +1,92 @@
+/**
+ * Single source of truth for the public `tree_sitter` action surface.
+ *
+ * Tool registration, validation, and prompt guidance should derive from these
+ * specs so the action list and per-action requirements do not drift apart.
+ */
+export const TREE_SITTER_ACTION_SPECS = [
+  {
+    name: "outline",
+    guidanceGroup: "js-ts-structure",
+    languageScope: "js-ts-only",
+    requiresPosition: false,
+    requiresQuery: false,
+  },
+  {
+    name: "imports",
+    guidanceGroup: "js-ts-structure",
+    languageScope: "js-ts-only",
+    requiresPosition: false,
+    requiresQuery: false,
+  },
+  {
+    name: "exports",
+    guidanceGroup: "js-ts-structure",
+    languageScope: "js-ts-only",
+    requiresPosition: false,
+    requiresQuery: false,
+  },
+  {
+    name: "node_at",
+    guidanceGroup: "node-at",
+    languageScope: "all-supported",
+    requiresPosition: true,
+    requiresQuery: false,
+  },
+  {
+    name: "query",
+    guidanceGroup: "query",
+    languageScope: "all-supported",
+    requiresPosition: false,
+    requiresQuery: true,
+  },
+  {
+    name: "callees",
+    guidanceGroup: "callees",
+    languageScope: "many-supported",
+    requiresPosition: true,
+    requiresQuery: false,
+  },
+] as const;
+
+export type TreeSitterAction = (typeof TREE_SITTER_ACTION_SPECS)[number]["name"];
+export type TreeSitterActionSpec = (typeof TREE_SITTER_ACTION_SPECS)[number];
+export type TreeSitterGuidanceGroup = TreeSitterActionSpec["guidanceGroup"];
+
+/** Ordered action names for schemas, validation messages, and docs. */
+export const TREE_SITTER_ACTION_NAMES = TREE_SITTER_ACTION_SPECS.map(
+  (spec) => spec.name,
+) as readonly TreeSitterAction[];
+
+const TREE_SITTER_ACTION_NAME_SET = new Set<string>(TREE_SITTER_ACTION_NAMES);
+const TREE_SITTER_ACTION_SPEC_MAP = new Map<TreeSitterAction, TreeSitterActionSpec>(
+  TREE_SITTER_ACTION_SPECS.map((spec) => [spec.name, spec]),
+);
+
+/** Check whether a runtime string is a supported `tree_sitter` action. */
+export function isTreeSitterAction(action: string): action is TreeSitterAction {
+  return TREE_SITTER_ACTION_NAME_SET.has(action);
+}
+
+/** Look up the spec for one supported `tree_sitter` action. */
+export function getTreeSitterActionSpec(action: TreeSitterAction): TreeSitterActionSpec {
+  const spec = TREE_SITTER_ACTION_SPEC_MAP.get(action);
+  if (!spec) {
+    throw new Error(`Unknown tree_sitter action: ${action}`);
+  }
+  return spec;
+}
+
+/** Get the ordered action names that belong to one prompt-guidance group. */
+export function getTreeSitterActionNamesByGuidanceGroup(
+  group: TreeSitterGuidanceGroup,
+): TreeSitterAction[] {
+  return TREE_SITTER_ACTION_SPECS.filter((spec) => spec.guidanceGroup === group).map(
+    (spec) => spec.name,
+  );
+}
+
+/** Format the public action list for validation messages and docs. */
+export function formatTreeSitterActionList(): string {
+  return TREE_SITTER_ACTION_NAMES.join(", ");
+}

package/src/{callees.ts → tool/callees.ts}

@@ -1,8 +1,8 @@
 // Structural callee extraction — enclosing-scope lookup with per-language queries.
 
-import { detectGrammar } from "./language.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { GrammarId, SourceRange, TreeSitterResult } from "./types.ts";
+import { detectGrammar } from "../language.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { GrammarId, SourceRange, TreeSitterResult } from "../types.ts";
 
 /** Result shape returned by lookupCalleesAt. */
 export interface CalleesAtResult {

package/src/{exports.ts → tool/exports.ts}

@@ -1,9 +1,9 @@
 // Export extraction for supported files.
 
-import { nodeToRange } from "./coordinates.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { SyntaxNodeLike } from "./syntax-node.ts";
-import type { ExportRecord, TreeSitterResult } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { ExportRecord, TreeSitterResult } from "../types.ts";
 
 /** Extract export records from a supported file. */
 export async function extractExports(

package/src/{formatting.ts → tool/formatting.ts}

@@ -1,6 +1,6 @@
 // Formatting helpers for tree_sitter tool output.
 
-import type { OutlineItem, TreeSitterResult } from "./types.ts";
+import type { OutlineItem, TreeSitterResult } from "../types.ts";
 
 export const MAX_ITEMS = 100;
 

package/src/tool/guidance.ts

@@ -0,0 +1,31 @@
+// Prompt guidance and tool description for the tree_sitter tool.
+//
+// Note: We intentionally do NOT include cross-tool routing (e.g., "use lsp for
+// type info") because this package can be installed standalone without supi-lsp.
+
+import {
+  formatTreeSitterActionList,
+  getTreeSitterActionNamesByGuidanceGroup,
+} from "./action-specs.ts";
+
+const jsTsStructureActions = getTreeSitterActionNamesByGuidanceGroup("js-ts-structure")
+  .map((action) => `tree_sitter.${action}(file)`)
+  .join(", ");
+
+export const toolDescription = `Tree-sitter tool — parser-level structure and syntax queries for supported files.
+
+Actions: ${formatTreeSitterActionList()}.
+
+Use tree_sitter for exact syntax nodes, shallow structure, parsed imports/exports, outgoing calls, or custom AST queries within one file. file is required for all actions. line and character are 1-based UTF-16 coordinates for node_at and callees. query is required for query. outline, imports, and exports are JavaScript/TypeScript-only; node_at and query work across supported grammars; callees works for many grammars. Relative paths resolve from the session working directory, and a leading @ on file paths is stripped.`;
+
+export const promptGuidelines = [
+  `Use ${jsTsStructureActions} for shallow JavaScript or TypeScript structure without reading the whole file.`,
+  "Use tree_sitter.node_at(file, line, character) for the exact syntax node and ancestry at a known position.",
+  "Use tree_sitter.callees(file, line, character) for outgoing calls from the enclosing function or method at a known position.",
+  "Use tree_sitter.query(file, query) for custom Tree-sitter patterns when the built-in actions are not specific enough.",
+  "Use tree_sitter for syntax, node types, source ranges, and other parser-backed structure within one supported file.",
+  "Do not use tree_sitter for type information, cross-file references, semantic renames, or codebase-wide orientation.",
+];
+
+export const promptSnippet =
+  "tree_sitter — parser-backed single-file structure, node lookup, callees, and AST queries";

package/src/{imports.ts → tool/imports.ts}

@@ -1,9 +1,9 @@
 // Import extraction for supported files.
 
-import { nodeToRange } from "./coordinates.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { SyntaxNodeLike } from "./syntax-node.ts";
-import type { ImportRecord, TreeSitterResult } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { ImportRecord, TreeSitterResult } from "../types.ts";
 
 /** Extract import records from a supported file. */
 export async function extractImports(

package/src/{node-at.ts → tool/node-at.ts}

@@ -1,8 +1,8 @@
 // Node-at-position lookup.
 
-import { nodeToRange, publicToTreeSitter, splitSourceLines } from "./coordinates.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { NodeAtResult, SourceRange, TreeSitterResult } from "./types.ts";
+import { nodeToRange, publicToTreeSitter, splitSourceLines } from "../coordinates.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { NodeAtResult, SourceRange, TreeSitterResult } from "../types.ts";
 
 const MAX_ANCESTRY = 10;
 

package/src/{outline.ts → tool/outline.ts}

@@ -1,8 +1,8 @@
 // Outline extraction for supported files.
 
-import { nodeToRange } from "./coordinates.ts";
-import type { SyntaxNodeLike } from "./syntax-node.ts";
-import type { OutlineItem } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { OutlineItem } from "../types.ts";
 
 /** Node types that can be extracted directly as outline items. */
 const OUTLINE_DECLARATION_NODE_TYPES = new Set([

package/src/tree-sitter.ts

@@ -3,6 +3,20 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { detectGrammar, isJsTsGrammar } from "./language.ts";
+import { TreeSitterRuntime } from "./session/runtime.ts";
+import {
+  clearSessionTreeSitterService,
+  setSessionTreeSitterService,
+} from "./session/service-registry.ts";
+import { createTreeSitterService } from "./session/session.ts";
+import {
+  formatTreeSitterActionList,
+  getTreeSitterActionSpec,
+  isTreeSitterAction,
+  TREE_SITTER_ACTION_NAMES,
+  type TreeSitterAction,
+} from "./tool/action-specs.ts";
 import {
   formatNonSuccess,
   formatOutlineItemsCapped,
@@ -11,56 +25,35 @@ import {
   truncatedNotice,
   truncateText,
   validationError,
-} from "./formatting.ts";
-import { detectGrammar, isJsTsGrammar } from "./language.ts";
-import { collectOutline } from "./outline.ts";
-import { TreeSitterRuntime } from "./runtime.ts";
-import { extractExports, extractImports, lookupCalleesAt, lookupNodeAt } from "./structure.ts";
-
-const TreeSitterActionEnum = StringEnum([
-  "outline",
-  "imports",
-  "exports",
-  "node_at",
-  "query",
-  "callees",
-] as const);
-
-const toolDescription = `Tree-sitter tool — provides structural AST analysis for supported files.
-
-Actions:
-- outline: Extract structural declarations (functions, classes, interfaces, etc.). JavaScript/TypeScript only.
-- imports: List import statements with module specifiers. JavaScript/TypeScript only.
-- exports: List export declarations, re-exports, and export assignments with names and kinds. JavaScript/TypeScript only.
-- node_at: Find the syntax node at a position. Params: file, line, character
-- query: Run a Tree-sitter query. Params: file, query
-- callees: Find outgoing function/method calls from a position. Params: file, line, character. Supported for most grammars.
-
-Coordinates are 1-based (line, character), compatible with the lsp tool convention.
-Character is a UTF-16 code-unit column.
-Relative file paths resolve from the session working directory.
-
-Supported extensions: .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs, .py, .pyi, .rs, .go, .mod, .c, .h, .cpp, .hpp, .cc, .cxx, .hxx, .c++, .h++, .java, .kt, .kts, .rb, .sh, .bash, .zsh, .html, .htm, .xhtml, .r, .sql`;
-
-const promptGuidelines = [
-  "Use tree_sitter for structural syntax-tree analysis: extracting declarations, imports, exports, node-at-position lookup, and custom queries.",
-  "Prefer tree_sitter when you need AST node types, exact source ranges, or parser-level structure that semantic language-server tooling does not expose.",
-  "tree_sitter is a standalone structural analysis tool; use semantic language-server features separately when they are available for hover, definitions, references, or diagnostics.",
-];
-
-const promptSnippet = `Use the tree_sitter tool for structural code analysis — outline, imports, exports, node-at-position lookup, and custom queries.`;
+} from "./tool/formatting.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
+import { collectOutline } from "./tool/outline.ts";
+import { extractExports, extractImports, lookupCalleesAt, lookupNodeAt } from "./tool/structure.ts";
+
+const TreeSitterActionEnum = StringEnum(TREE_SITTER_ACTION_NAMES);
 
 export default function treeSitterExtension(pi: ExtensionAPI) {
   let runtime: TreeSitterRuntime | undefined;
+  let activeCwd: string | null = null;
 
   pi.on("session_start", (_event, ctx) => {
-    runtime?.dispose();
+    if (runtime && activeCwd) {
+      clearSessionTreeSitterService(activeCwd);
+      runtime.dispose();
+    }
+
+    activeCwd = ctx.cwd;
     runtime = new TreeSitterRuntime(ctx.cwd);
+    setSessionTreeSitterService(ctx.cwd, createTreeSitterService(runtime));
   });
 
   pi.on("session_shutdown", () => {
+    if (activeCwd) {
+      clearSessionTreeSitterService(activeCwd);
+    }
     runtime?.dispose();
     runtime = undefined;
+    activeCwd = null;
   });
 
   pi.registerTool({
@@ -96,8 +89,6 @@ export default function treeSitterExtension(pi: ExtensionAPI) {
   });
 }
 
-type TreeSitterAction = "outline" | "imports" | "exports" | "node_at" | "query" | "callees";
-
 type ToolParams = {
   action?: string;
   file?: string;
@@ -106,17 +97,47 @@ type ToolParams = {
   query?: string;
 };
 
+interface ValidatedToolParams {
+  action: TreeSitterAction;
+  file: string;
+  line?: number;
+  character?: number;
+  query?: string;
+}
+
+const SUPPORTED_ACTIONS_TEXT = formatTreeSitterActionList();
+
+const ACTION_HANDLERS: Record<
+  TreeSitterAction,
+  (runtime: TreeSitterRuntime, params: ValidatedToolParams) => Promise<string>
+> = {
+  outline: (runtime, params) => handleOutline(runtime, params.file),
+  imports: (runtime, params) => handleImports(runtime, params.file),
+  exports: (runtime, params) => handleExports(runtime, params.file),
+  node_at: (runtime, params) =>
+    handleNodeAt(runtime, params.file, params.line as number, params.character as number),
+  query: (runtime, params) => handleQuery(runtime, params.file, params.query as string),
+  callees: (runtime, params) =>
+    handleCallees(runtime, params.file, params.line as number, params.character as number),
+};
+
 async function executeToolAction(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
+  const validated = validateToolParams(params);
+  if (typeof validated === "string") {
+    return validated;
+  }
+
+  return ACTION_HANDLERS[validated.action](runtime, validated);
+}
+
+function validateToolParams(params: ToolParams): ValidatedToolParams | string {
   if (!params.action) {
-    return validationError(
-      "`action` is required. Supported: outline, imports, exports, node_at, query, callees.",
-    );
+    return validationError(`\`action\` is required. Supported: ${SUPPORTED_ACTIONS_TEXT}.`);
   }
 
-  const action = toSupportedAction(params.action);
-  if (!action) {
+  if (!isTreeSitterAction(params.action)) {
     return validationError(
-      `Unknown action: ${params.action}. Supported: outline, imports, exports, node_at, query, callees`,
+      `Unknown action: ${params.action}. Supported: ${SUPPORTED_ACTIONS_TEXT}`,
     );
   }
 
@@ -124,12 +145,37 @@ async function executeToolAction(runtime: TreeSitterRuntime, params: ToolParams)
     return validationError("`file` is required for all actions.");
   }
 
-  if (action === "outline") return handleOutline(runtime, params.file);
-  if (action === "imports") return handleImports(runtime, params.file);
-  if (action === "exports") return handleExports(runtime, params.file);
-  if (action === "node_at") return handleNodeAt(runtime, params);
-  if (action === "callees") return handleCallees(runtime, params);
-  return handleQuery(runtime, params);
+  const spec = getTreeSitterActionSpec(params.action);
+  if (spec.requiresPosition) {
+    const lineError = validatePositiveInteger("line", params.line, params.action);
+    if (lineError) return lineError;
+
+    const characterError = validatePositiveInteger("character", params.character, params.action);
+    if (characterError) return characterError;
+  }
+
+  if (spec.requiresQuery && (!params.query || params.query.trim().length === 0)) {
+    return validationError("`query` is required and must be non-empty.");
+  }
+
+  return {
+    action: params.action,
+    file: params.file,
+    line: params.line,
+    character: params.character,
+    query: params.query,
+  };
+}
+
+function validatePositiveInteger(
+  field: "line" | "character",
+  value: number | undefined,
+  action: TreeSitterAction,
+): string | null {
+  if (value === undefined || !Number.isInteger(value) || value < 1) {
+    return validationError(`\`${field}\` must be a positive 1-based integer for ${action} action.`);
+  }
+  return null;
 }
 
 async function handleOutline(runtime: TreeSitterRuntime, file: string): Promise<string> {
@@ -198,18 +244,13 @@ async function handleExports(runtime: TreeSitterRuntime, file: string): Promise<
   return lines.join("\n");
 }
 
-async function handleNodeAt(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
-  if (!Number.isInteger(params.line) || (params.line as number) < 1) {
-    return validationError("`line` must be a positive 1-based integer for node_at action.");
-  }
-  if (!Number.isInteger(params.character) || (params.character as number) < 1) {
-    return validationError("`character` must be a positive 1-based integer for node_at action.");
-  }
-
-  const file = params.file;
-  const line = params.line as number;
-  const character = params.character as number;
-  const result = await lookupNodeAt(runtime, file as string, line, character);
+async function handleNodeAt(
+  runtime: TreeSitterRuntime,
+  file: string,
+  line: number,
+  character: number,
+): Promise<string> {
+  const result = await lookupNodeAt(runtime, file, line, character);
   if (result.kind !== "success") return formatNonSuccess(result);
 
   const { data } = result;
@@ -235,13 +276,12 @@ async function handleNodeAt(runtime: TreeSitterRuntime, params: ToolParams): Pro
   return lines.join("\n");
 }
 
-async function handleQuery(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
-  if (!params.query || params.query.trim().length === 0) {
-    return validationError("`query` is required and must be non-empty.");
-  }
-
-  const file = params.file as string;
-  const result = await runtime.queryFile(file, params.query);
+async function handleQuery(
+  runtime: TreeSitterRuntime,
+  file: string,
+  query: string,
+): Promise<string> {
+  const result = await runtime.queryFile(file, query);
   if (result.kind !== "success") return formatNonSuccess(result);
 
   const { data: captures } = result;
@@ -260,25 +300,12 @@ async function handleQuery(runtime: TreeSitterRuntime, params: ToolParams): Prom
   return lines.join("\n");
 }
 
-function toSupportedAction(action: string): TreeSitterAction | undefined {
-  if (["outline", "imports", "exports", "node_at", "query", "callees"].includes(action)) {
-    return action as TreeSitterAction;
-  }
-  return undefined;
-}
-
-async function handleCallees(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
-  if (!Number.isInteger(params.line) || (params.line as number) < 1) {
-    return validationError("`line` must be a positive 1-based integer for callees action.");
-  }
-  if (!Number.isInteger(params.character) || (params.character as number) < 1) {
-    return validationError("`character` must be a positive 1-based integer for callees action.");
-  }
-
-  const file = params.file as string;
-  const line = params.line as number;
-  const character = params.character as number;
-
+async function handleCallees(
+  runtime: TreeSitterRuntime,
+  file: string,
+  line: number,
+  character: number,
+): Promise<string> {
   const result = await lookupCalleesAt(runtime, file, line, character);
   if (result.kind !== "success") return formatNonSuccess(result);
 

package/src/types.ts

@@ -66,8 +66,8 @@ export interface QueryCapture {
   text: string;
 }
 
-/** Session-level Tree-sitter service. */
-export interface TreeSitterSession {
+/** Shared Tree-sitter service surface, independent of lifecycle ownership. */
+export interface TreeSitterService {
   /** Validate that a supported file can be read and parsed; does not expose the raw tree. */
   canParse(file: string): Promise<TreeSitterResult<{ file: string; language: string }>>;
   /** Run a Tree-sitter query and return all captures. */
@@ -86,10 +86,21 @@ export interface TreeSitterSession {
     line: number,
     character: number,
   ): Promise<TreeSitterResult<CalleesAtResult>>;
+}
+
+/** Owned Tree-sitter session that must release its runtime resources. */
+export interface TreeSitterSession extends TreeSitterService {
   /** Release parser and grammar resources owned by this session. */
   dispose(): void;
 }
 
+/** Session-scoped shared structural service published by the extension runtime. */
+export type SessionTreeSitterService = TreeSitterService;
+
+export type SessionTreeSitterServiceState =
+  | { kind: "ready"; service: SessionTreeSitterService }
+  | { kind: "unavailable"; reason: string };
+
 /** Supported grammar identifiers. */
 export type GrammarId =
   | "javascript"