@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/api.ts

@@ -7,6 +7,7 @@ export type {
   CapabilityState,
   CodeLocation,
   CodePosition,
+  CodeQueryResult,
   CodeResult,
   CodeSymbol,
   ConfidenceMode,
@@ -24,8 +25,16 @@ export type {
 // Architecture model types.
 export type {
   ArchitectureModel,
+  ArchitectureObservationStatus,
   DependencyEdge,
+  ManifestDependency,
+  ManifestDependencyField,
+  ManifestDependencySection,
+  ManifestField,
   ModuleInfo,
+  PackageManifestObservation,
+  WorkspaceTopology,
+  WorkspaceTopologySource,
 } from "./analysis/architecture/model.ts";
 // Code provider types.
 export type { CodeProvider, CodeProviderState } from "./analysis/provider.ts";
@@ -34,18 +43,26 @@ export type {
   ResolvedTargetData,
   ResolvedTargetGroupData,
   TargetOutcome,
+  TargetProviderProvenance,
 } from "./analysis/target/types.ts";
+export type {
+  HealthDiagnosticObservation,
+  HealthDiagnosticScope,
+  HealthRefreshAttempt,
+  HealthRefreshState,
+  HealthStaleAssessment,
+  SemanticHealthState,
+} from "./session/health-types.ts";
+export type { TargetSymbolKind } from "./session/target-input.ts";
 // Code-intelligence-specific result types.
 export type {
-  AffectedDetails,
-  BriefDetails,
   CodeIntelResult,
   ContextDetails,
   DisambiguationCandidate,
   HealthDetails,
-  ImpactDetails,
+  HealthSectionDetails,
   InspectDetails,
+  OrientationSectionDetails,
   ResolveDetails,
   SearchDetails,
-  TestSurfaceDetails,
 } from "./types/index.ts";

package/src/app/app.ts

@@ -8,7 +8,6 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
-import { WorkspaceManager } from "./manager.ts";
 
 /**
  * The code-intelligence app object.
@@ -34,6 +33,19 @@ export interface CodeIntelligenceApp {
   shutdown(): void;
 }
 
+/** Get or create a session in a Map-based cache. */
+export function getOrCreateSession(
+  sessions: Map<string, WorkspaceCodeIntelligenceSession>,
+  cwd: string,
+): WorkspaceCodeIntelligenceSession {
+  let session = sessions.get(cwd);
+  if (!session) {
+    session = new WorkspaceCodeIntelligenceSession(cwd);
+    sessions.set(cwd, session);
+  }
+  return session;
+}
+
 /**
  * Create a simple session cache for tests and ad-hoc usage.
  *
@@ -48,15 +60,9 @@ export function createSessionCache(): {
 } {
   const sessions = new Map<string, WorkspaceCodeIntelligenceSession>();
   return {
-    getOrCreate(cwd: string): WorkspaceCodeIntelligenceSession {
-      let session = sessions.get(cwd);
-      if (!session) {
-        session = new WorkspaceCodeIntelligenceSession(cwd);
-        sessions.set(cwd, session);
-      }
-      return session;
-    },
-    clear(): void {
+    getOrCreate: (cwd) => getOrCreateSession(sessions, cwd),
+    clear: () => {
+      for (const session of sessions.values()) session.clearStores();
       sessions.clear();
     },
   };
@@ -71,60 +77,64 @@ export function createSessionCache(): {
  * - `session_shutdown` — releases all sessions and clears per-session stores
  */
 export function createCodeIntelligenceApp(pi: ExtensionAPI): CodeIntelligenceApp {
-  const manager = new WorkspaceManager();
+  const sessions = new Map<string, WorkspaceCodeIntelligenceSession>();
   const OVERVIEW_CUSTOM_TYPE = "code-intelligence-overview";
 
   pi.on("session_start", (_event, ctx) => {
-    const session = manager.getOrCreateSession(ctx.cwd);
+    const session = getOrCreateSession(sessions, ctx.cwd);
+    restoreBranchOverviewState(session, ctx.sessionManager.getBranch());
+  });
 
-    // Check if the branch already contains an overview and restore branch-local instruction state.
-    const branch = ctx.sessionManager.getBranch();
-    session.reconstructInstructionState(branch);
-    for (const entry of branch) {
-      if (
-        entry.type === "custom_message" &&
-        (entry as { customType?: string }).customType === OVERVIEW_CUSTOM_TYPE
-      ) {
-        session.hasInjectedOverview = true;
-        break;
-      }
-    }
+  pi.on("session_tree", (_event, ctx) => {
+    const session = sessions.get(ctx.cwd);
+    if (!session) return;
+    restoreBranchOverviewState(session, ctx.sessionManager.getBranch());
   });
 
   pi.on("session_compact", (_event, ctx) => {
-    manager.getSession(ctx.cwd)?.resetSurfacedInstructionDirs();
+    sessions.get(ctx.cwd)?.resetSurfacedInstructionDirs();
   });
 
   pi.on("session_shutdown", () => {
-    // Clear per-session stores before releasing sessions
-    for (const session of manager.allSessions()) {
+    for (const session of sessions.values()) {
       session.clearStores();
     }
-    manager.shutdown();
+    sessions.clear();
   });
 
-  return {
-    getSession(cwd: string): WorkspaceCodeIntelligenceSession | undefined {
-      return manager.getSession(cwd);
-    },
-
-    createSession(cwd: string): WorkspaceCodeIntelligenceSession {
-      return manager.getOrCreateSession(cwd);
-    },
+  /**
+   * Restore overview injection state from a branch.
+   *
+   * Reconstructs instruction-file state and checks whether this branch
+   * already contains a code-intelligence-overview custom message.
+   */
+  function restoreBranchOverviewState(
+    session: WorkspaceCodeIntelligenceSession,
+    branch: unknown[],
+  ): void {
+    session.reconstructInstructionState(
+      branch as Parameters<typeof session.reconstructInstructionState>[0],
+    );
+    for (const entry of branch as Array<{ type?: string; customType?: string }>) {
+      if (entry.type === "custom_message" && entry.customType === OVERVIEW_CUSTOM_TYPE) {
+        session.restoreOverviewInjection();
+        return;
+      }
+    }
+  }
 
+  return {
+    getSession: (cwd) => sessions.get(cwd),
+    createSession: (cwd) => getOrCreateSession(sessions, cwd),
     releaseSession(cwd: string): void {
-      const session = manager.getSession(cwd);
-      if (session) {
-        session.clearStores();
-      }
-      manager.releaseSession(cwd);
+      sessions.get(cwd)?.clearStores();
+      sessions.delete(cwd);
     },
-
     shutdown(): void {
-      for (const session of manager.allSessions()) {
+      for (const session of sessions.values()) {
         session.clearStores();
       }
-      manager.shutdown();
+      sessions.clear();
     },
   };
 }

package/src/extension.ts

@@ -1,126 +1,63 @@
 // Code Intelligence extension entry point — registers the focused code-intelligence tools,
-// the LSP adapter with diagnostics, overrides, and settings, and the unified /supi-ci-status command.
+// shared provider lifecycle, settings, UI, and the unified /supi-ci-status command.
 
 import type { BeforeAgentStartEventResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { buildArchitectureModel } from "./analysis/architecture/discovery.ts";
-import {
-  evaluateCoverageWarnings,
-  gatherCoverageEvalInput,
-} from "./analysis/coverage/coverage-warnings.ts";
 import { createCodeIntelligenceApp } from "./app/app.ts";
 import { registerCodeIntelligenceSettings } from "./config.ts";
 import type { WorkspaceCodeIntelligenceSession } from "./session/session.ts";
-import { registerDiagnosticInjectionHandlers } from "./substrate/lsp/diagnostic-injection.ts";
 import { registerLspSessionLifecycle } from "./substrate/lsp/lifecycle.ts";
-import { registerLspAwareToolOverrides } from "./substrate/lsp/overrides.ts";
 import { registerWorkspaceRecoveryHandler } from "./substrate/lsp/recovery.ts";
 import { registerLspSettings } from "./substrate/lsp/settings.ts";
 import { createLspAdapterState } from "./substrate/lsp/state.ts";
-import {
-  createTsAdapterState,
-  registerTsSessionLifecycle,
-} from "./substrate/tree-sitter/lifecycle.ts";
 import { registerCodeIntelligenceTools } from "./tool/register.ts";
 import { registerLspFooterContribution } from "./ui/footer.ts";
-import { renderOverview } from "./ui/markdown/overview.ts";
+import { estimateTokens, OVERVIEW_TOKEN_BUDGET, renderOverview } from "./ui/markdown/overview.ts";
 import { buildOverviewData } from "./ui/markdown/overview-data.ts";
-import { registerLspMessageRenderer } from "./ui/message-renderer.ts";
 import { registerCiStatusCommand } from "./ui/status-command.ts";
 
 const OVERVIEW_CUSTOM_TYPE = "code-intelligence-overview";
 
+/** Register the full interactive Code Intelligence profile. */
 export default function codeIntelligenceExtension(
   pi: ExtensionAPI,
   getOrCreateSession?: (cwd: string) => WorkspaceCodeIntelligenceSession,
 ) {
   const app = createCodeIntelligenceApp(pi);
-
   const lspState = createLspAdapterState();
-  const tsState = createTsAdapterState();
 
-  // ── Substrate wiring ──────────────────────────────────────────────
   registerCodeIntelligenceSettings(pi);
   registerLspSettings(pi);
-  registerLspSessionLifecycle(pi, lspState);
-  registerLspAwareToolOverrides(pi, lspState);
-  registerDiagnosticInjectionHandlers(pi, lspState);
-  registerWorkspaceRecoveryHandler(pi, lspState);
-  registerTsSessionLifecycle(pi, tsState);
-
-  // ── Attach controller refs to sessions on startup (ADR 0008) ──────
-  pi.on("session_start", (_event, ctx) => {
+  registerLspSessionLifecycle(pi, lspState, (ctx) => {
     const session = app.getSession(ctx.cwd);
     if (!session) return;
-    if (lspState.controller) session.lspController = lspState.controller;
-    if (tsState.controller) session.tsController = tsState.controller;
+    session.attachLspController(lspState.controller);
+    session.seedSentinelSnapshot(lspState.sentinelSnapshot);
+    session.setProjectTrusted(ctx.isProjectTrusted());
   });
+  registerWorkspaceRecoveryHandler(pi, lspState);
 
-  // ── Tool registration ─────────────────────────────────────────────
   registerCodeIntelligenceTools(
     pi,
     getOrCreateSession ?? ((cwd) => app.getSession(cwd) ?? app.createSession(cwd)),
   );
 
-  // ── UI registration ───────────────────────────────────────────────
-  registerLspMessageRenderer(pi);
   registerCiStatusCommand(pi);
   registerLspFooterContribution(lspState);
 
-  // ── Native context path capture for instruction-file dedup ─────────
   pi.on("before_agent_start", (event, ctx) => {
     const session = app.getSession(ctx.cwd) ?? app.createSession(ctx.cwd);
     session.captureNativeInstructionPaths(event.systemPromptOptions.contextFiles ?? []);
   });
 
-  // ── Coverage warning emission ─────────────────────────────────────
   pi.on(
     "before_agent_start",
     async (_event, ctx): Promise<BeforeAgentStartEventResult | undefined> => {
       const session = app.getSession(ctx.cwd);
-      if (!session) return;
-
-      const report = evaluateCoverageWarnings(
-        gatherCoverageEvalInput(ctx.cwd, session.lspController),
-      );
-      const pending = session.coverageWarningState.getPendingWarnings(report);
-      if (pending.length === 0) return;
-
-      const lines = [
-        '<extension-context source="supi-code-intelligence">',
-        "Code intelligence coverage is degraded:",
-      ];
-      for (const w of pending) {
-        const lang = w.language ? `[${w.language}] ` : "";
-        const detail = w.detail ? ` — ${w.detail}` : "";
-        lines.push(`- ${lang}${w.message}${detail}`);
-      }
-      lines.push("</extension-context>");
-      const warningContext = lines.join("\n");
-
-      return {
-        message: {
-          customType: "code-intelligence-coverage",
-          display: true,
-          content: warningContext,
-        },
-        systemPrompt:
-          (await ctx.getSystemPrompt()) +
-          `\n\nThe code intelligence stack has degraded coverage. This means some code-understanding tools (code_* tools) may return limited or structural-only information. The agent should still attempt using them, but be aware that semantic coverage for some languages may be unavailable.`,
-      };
-    },
-  );
-
-  // ── Overview injection — uses the app-managed session state ────────
-  pi.on(
-    "before_agent_start",
-    async (_event, ctx): Promise<BeforeAgentStartEventResult | undefined> => {
-      const session = app.getSession(ctx.cwd);
-      if (!session) return;
-      if (session.hasInjectedOverview) return;
-      session.hasInjectedOverview = true;
+      if (!session?.claimOverviewInjection()) return;
 
       const model = await buildArchitectureModel(ctx.cwd);
-      if (!model || model.modules.length === 0) return;
+      if (model.modules.length === 0) return;
 
       const data = buildOverviewData(model);
       if (!data) return;
@@ -128,32 +65,19 @@ export default function codeIntelligenceExtension(
       const overview = renderOverview(data);
       if (!overview) return;
 
+      const estimatedTokens = estimateTokens(overview);
+      if (estimatedTokens > OVERVIEW_TOKEN_BUDGET) {
+        pi.events.emit("supi:debug", {
+          source: "supi-code-intelligence",
+          level: "warning",
+          category: "overview",
+          message: `Overview exceeds soft token budget: ${estimatedTokens} tokens (budget: ${OVERVIEW_TOKEN_BUDGET})`,
+        });
+      }
+
       return {
-        message: {
-          customType: OVERVIEW_CUSTOM_TYPE,
-          display: false,
-          content: overview,
-        },
+        message: { customType: OVERVIEW_CUSTOM_TYPE, display: false, content: overview },
       };
     },
   );
-
-  // ── Process-exit safety net ─────────────────────────────────────────
-  //
-  // If the Node process exits without `session_shutdown` firing (crash,
-  // unhandled rejection, SIGINT), make a best-effort synchronous attempt
-  // to terminate the LSP and Tree-sitter controller trees.
-  //
-  // `process.on("exit")` handlers are synchronous — we cannot await
-  // controller shutdown, but `process.kill(-pid, "SIGTERM")` fires
-  // synchronously and the SIGKILL escalation in LspClient is handled
-  // by the kernel after process termination.
-  let cleaningUp = false;
-  process.once("exit", () => {
-    if (cleaningUp) return;
-    cleaningUp = true;
-    // Fire and forget — the critical kill calls are synchronous.
-    void lspState.controller?.shutdown();
-    void tsState.controller?.shutdown();
-  });
 }

package/src/headless.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createSessionCache } from "./app/app.ts";
+import { registerLspSessionLifecycle } from "./substrate/lsp/lifecycle.ts";
+import { createLspAdapterState } from "./substrate/lsp/state.ts";
+import { registerCodeIntelligenceTools } from "./tool/register.ts";
+import { CODE_INTELLIGENCE_TOOL_SPECS } from "./tool/specs.ts";
+
+/** Exact Code Intelligence tool surface available to managed Reviewer Sessions. */
+export const HEADLESS_INSPECTION_TOOL_NAMES = [
+  "code_resolve",
+  "code_inspect",
+  "code_orientation",
+  "code_graph",
+  "code_find",
+  "code_health",
+] as const;
+
+const inspectionToolNames = new Set<string>(HEADLESS_INSPECTION_TOOL_NAMES);
+
+/**
+ * Register the managed-child profile: six inspection tools backed by the shared
+ * Workspace provider host, without refactors, settings, UI, or overview state.
+ */
+export default function headlessInspectionProfile(pi: ExtensionAPI): void {
+  const sessions = createSessionCache();
+  const lspState = createLspAdapterState();
+  registerLspSessionLifecycle(pi, lspState, (ctx) => {
+    const session = sessions.getOrCreate(ctx.cwd);
+    session.attachLspController(lspState.controller);
+    session.seedSentinelSnapshot(lspState.sentinelSnapshot);
+    session.setProjectTrusted(ctx.isProjectTrusted());
+  });
+  pi.on("session_shutdown", () => sessions.clear());
+
+  registerCodeIntelligenceTools(
+    pi,
+    sessions.getOrCreate,
+    undefined,
+    CODE_INTELLIGENCE_TOOL_SPECS.filter((spec) => inspectionToolNames.has(spec.name)),
+  );
+}

package/src/session/capability-adapter.ts

@@ -2,15 +2,18 @@
  * Capability adapter — injected dependency for WorkspaceCodeIntelligenceSession.
  *
  * Encapsulates provider access and readiness so the session target
- * workflow can be tested with an in-memory adapter. Two adapters
- * (production and test) justify the seam.
+ * workflow can be tested with an in-memory adapter.
  *
  * @mrclrchtr/supi-code-intelligence — internal, not exported via api.ts
  */
 
-import type { SemanticProvider, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
-import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
-import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import {
+  type CapabilityState,
+  getDefaultWorkspaceRuntime,
+  type SemanticProvider,
+  type StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { getWorkspaceLspRuntime, type WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
 import {
   type CodeProvider,
   type CodeProviderState,
@@ -35,8 +38,7 @@ export type ReadinessOutcome =
 /**
  * Injected capability adapter.
  *
- * Production adapter reads the global workspace runtime. Test adapter
- * provides semantic/structural providers in memory without global state.
+ * Production adapter reads the global workspace runtime.
  */
 export interface CapabilityAdapter {
   /** Get the composite code provider state for a workspace. */
@@ -51,6 +53,15 @@ export interface CapabilityAdapter {
   /** Get the raw structural provider, or null. */
   getStructuralProvider(cwd: string): StructuralProvider | null;
 
+  /** Get the workspace LSP operational state for diagnostics and recovery workflows. */
+  getLspRuntimeState(cwd: string): WorkspaceLspRuntimeState;
+
+  /** Get semantic and structural capability states without exposing providers. */
+  getCapabilityStates(cwd: string): {
+    semantic: CapabilityState;
+    structural: CapabilityState;
+  };
+
   /**
    * Wait for semantic (LSP) readiness. Returns a typed outcome so
    * the target workflow can decide whether to proceed, return a
@@ -101,118 +112,15 @@ export class WorkspaceCapabilityAdapter implements CapabilityAdapter {
     return result;
   }
 
-  /** Convenience: LSP service state for impact/health consumers still using it directly. */
-  getLspService(cwd: string): SessionLspServiceState {
-    const state = this.getProviderState(cwd);
-    return state.kind === "ready"
-      ? state.lspService
-      : { kind: "unavailable" as const, reason: "No provider" };
-  }
-}
-
-// ── Test adapter ──────────────────────────────────────────────────────
-
-/**
- * In-memory capability adapter for tests.
- *
- * Pass explicit providers and readiness outcomes without touching
- * the global workspace runtime.
- */
-export class TestCapabilityAdapter implements CapabilityAdapter {
-  readonly #semantic: SemanticProvider | null;
-  readonly #structural: StructuralProvider | null;
-  readonly #readiness: ReadinessOutcome;
-  readonly #lspService: SessionLspServiceState;
-
-  constructor(options: {
-    semantic?: SemanticProvider | null;
-    structural?: StructuralProvider | null;
-    readiness?: ReadinessOutcome;
-    lspService?: SessionLspServiceState;
-  }) {
-    this.#semantic = options.semantic ?? null;
-    this.#structural = options.structural ?? null;
-    this.#readiness = options.readiness ?? { kind: "ready" };
-    this.#lspService = options.lspService ?? {
-      kind: "unavailable" as const,
-      reason: "no test LSP",
-    };
-  }
-
-  getProviderState(_cwd: string): CodeProviderState {
-    if (!this.#semantic && !this.#structural) {
-      return { kind: "unavailable", reason: "No providers in test adapter" };
-    }
-    return {
-      kind: "ready",
-      provider: this.getProvider(_cwd) as CodeProvider,
-      lspService: this.#lspService,
-    };
-  }
-
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: adapter maps many provider methods; splitting would degrade readability
-  getProvider(_cwd: string): CodeProvider | null {
-    if (!this.#semantic && !this.#structural) return null;
-    return {
-      // Semantic pass-through
-      references: this.#semantic?.references
-        ? (...args: Parameters<SemanticProvider["references"]>) =>
-            this.#semantic?.references?.(...args)
-        : async () => null,
-      implementation: this.#semantic?.implementation
-        ? (...args) => this.#semantic?.implementation?.(...args)
-        : async () => null,
-      documentSymbols: this.#semantic?.documentSymbols
-        ? (...args) => this.#semantic?.documentSymbols?.(...args)
-        : async () => [],
-      workspaceSymbols: this.#semantic?.workspaceSymbols
-        ? (...args) => this.#semantic?.workspaceSymbols?.(...args)
-        : async () => [],
-      hover: this.#semantic?.hover ? (...args) => this.#semantic?.hover?.(...args) : undefined,
-      definition: this.#semantic?.definition
-        ? (...args) => this.#semantic?.definition?.(...args)
-        : undefined,
-      codeActions: this.#semantic?.codeActions
-        ? (...args) => this.#semantic?.codeActions?.(...args)
-        : undefined,
-      codeActionTitles: this.#semantic?.codeActionTitles
-        ? (...args) => this.#semantic?.codeActionTitles?.(...args)
-        : undefined,
-      rename: this.#semantic?.rename ? (...args) => this.#semantic?.rename?.(...args) : undefined,
-      refactor: this.#semantic?.refactor
-        ? (...args) => this.#semantic?.refactor?.(...args)
-        : undefined,
-      // Structural pass-through
-      calleesAt: this.#structural?.calleesAt
-        ? (...args) => this.#structural?.calleesAt?.(...args)
-        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
-      exports: this.#structural?.exports
-        ? (...args) => this.#structural?.exports?.(...args)
-        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
-      outline: this.#structural?.outline
-        ? (...args) => this.#structural?.outline?.(...args)
-        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
-      imports: this.#structural?.imports
-        ? (...args) => this.#structural?.imports?.(...args)
-        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
-      nodeAt: this.#structural?.nodeAt
-        ? (...args) => this.#structural?.nodeAt?.(...args)
-        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
-      callSites: this.#structural?.callSites
-        ? (...args) => this.#structural?.callSites?.(...args)
-        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
-    } as CodeProvider;
-  }
-
-  getSemanticProvider(_cwd: string): SemanticProvider | null {
-    return this.#semantic;
-  }
-
-  getStructuralProvider(_cwd: string): StructuralProvider | null {
-    return this.#structural;
+  getCapabilityStates(cwd: string): {
+    semantic: CapabilityState;
+    structural: CapabilityState;
+  } {
+    const workspace = getDefaultWorkspaceRuntime().getWorkspace(cwd);
+    return { semantic: workspace.semantic.state, structural: workspace.structural.state };
   }
 
-  async ensureSemanticReadiness(_cwd: string, _scope: ReadinessScope): Promise<ReadinessOutcome> {
-    return this.#readiness;
+  getLspRuntimeState(cwd: string): WorkspaceLspRuntimeState {
+    return getWorkspaceLspRuntime(cwd);
   }
 }

package/src/session/find-types.ts

@@ -0,0 +1,38 @@
+import type { CodeSymbol } from "@mrclrchtr/supi-code-runtime/api";
+import type { StructuredPatternResult } from "../analysis/search/pattern.ts";
+import type { CodeFindAstKind } from "../tool/find/ast-kinds.ts";
+import type { CodeFindMode } from "../tool/find/modes.ts";
+
+export type FindMode = CodeFindMode;
+
+export interface FindWorkflowInput {
+  readonly query: string;
+  readonly scope?: readonly string[];
+  readonly mode: FindMode;
+  readonly kind?: CodeFindAstKind;
+  readonly maxResults?: number;
+}
+
+export type FindWorkflowData =
+  | {
+      readonly kind: "ast";
+      readonly astKind: CodeFindAstKind;
+      readonly result: Readonly<StructuredPatternResult>;
+    }
+  | {
+      readonly kind: "semantic";
+      readonly symbols: readonly CodeSymbol[];
+      readonly partialReason: string | null;
+    };
+
+export type FindWorkflowOutcome =
+  | {
+      readonly kind: "completed";
+      readonly query: string;
+      readonly mode: FindMode;
+      readonly scopeLabel: string;
+      readonly maxResults: number;
+      readonly data: FindWorkflowData;
+    }
+  | { readonly kind: "invalid-input"; readonly message: string }
+  | { readonly kind: "unavailable"; readonly reason: string };