@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

package/README.md

@@ -4,134 +4,216 @@
   </a>
 </div>
 
-# @mrclrchtr/supi-code-intelligence — LSP and Tree-sitter AST Code Intelligence for Pi
+# @mrclrchtr/supi-code-intelligence
 
 [![GitHub stars](https://img.shields.io/github/stars/mrclrchtr/supi)](https://github.com/mrclrchtr/supi/stargazers) [![npm downloads](https://img.shields.io/npm/dm/@mrclrchtr/supi-code-intelligence)](https://www.npmjs.com/package/@mrclrchtr/supi-code-intelligence)
 
-Gives the [Pi coding agent](https://github.com/earendil-works/pi) direct, model-callable LSP semantic navigation and Tree-sitter AST structural code analysis.
+A [Pi coding agent](https://github.com/earendil-works/pi) extension to navigate symbols, search code structure, check diagnostics, and preview and apply semantic refactors.
 
-## LSP + AST, directly available to the agent
+## Install
 
-Instead of relying on file reads and text search alone, Pi can call focused `code_*` tools backed by:
+```bash
+pi install npm:@mrclrchtr/supi-code-intelligence
+```
 
-- **Language servers (LSP)** for types, definitions, references, implementations, diagnostics, workspace symbols, and semantic refactoring.
-- **Tree-sitter ASTs** for syntax, outlines, source structure, structural search, and outgoing calls.
+Add `-l` for a project-local install. To try the package for one run:
 
-The two sources complement each other without silently pretending one is the other. Results say which capability supplied the evidence and when semantic or structural analysis is unavailable.
+```bash
+pi -e npm:@mrclrchtr/supi-code-intelligence
+```
 
-## What your agent gets
+For local development, run `pi install ./packages/supi-code-intelligence` from the SuPi repository root. Run `/reload` after changes.
 
-After installation, keep asking Pi normal coding questions. The agent can:
+This package is included in the SuPi release installer. SuPi remains pre-release. The package bundles its LSP and Tree-sitter runtime dependencies, but not language-server binaries.
 
-- **Map an unfamiliar repository** — understand workspaces, packages, entry points, dependencies, and local `CLAUDE.md` or `AGENTS.md` instructions before editing.
-- **Navigate precisely with LSP** — identify the exact symbol at a source location and inspect its type, definition, enclosing declaration, and nearby diagnostics.
-- **Follow relationships across LSP and AST evidence** — find references, implementations, and outgoing calls without guessing from matching text.
-- **Search parsed code structure** — query AST definitions, types, interfaces, classes, methods, enums, imports, exports, and call sites. One owned Structural Worker keeps Pi responsive. Tool cancellation and the shared AST deadline propagate through an atomic cancellation flag into Worker reads, parser progress, and query progress.
-- **Correlate diagnostics** — each public `code_*` call gets one session-local opaque Debug Operation ID. Directly owned workflow, LSP, AST Scan, and Structural Worker events share it without changing normal Tool results.
-- **Check live project health** — inspect language-server status and current errors or warnings, with an option to refresh stale diagnostics.
-- **Refactor safely** — preview language-aware renames and extractions before applying them. Plans are rejected if the files changed in the meantime.
-- **See uncertainty clearly** — results distinguish “nothing found” from incomplete or unavailable analysis and disclose omitted matches.
+## What it adds
 
-When Pi recognizes a workspace, the agent also receives a compact architecture overview near the start of the session, so it can orient before spending turns opening files. The overview contains manifest facts (module names, one-line descriptions, declared topology, declared entrypoints, and detected languages), is labeled as untrusted repository evidence, and is controlled by the `code-intelligence.overviewEnabled` setting in `/supi-settings`.
+- **Language Server Protocol (LSP) tools** for types, definitions, references, implementations, diagnostics, workspace symbols, and semantic refactoring.
+- **Tree-sitter tools** for syntax, declarations, structural search, and calls as written in source code. These calls are not a semantic call graph.
+- **Workspace orientation** from files, manifests, and declared package relationships. Directory orientation can also show local instruction files.
+- **Visible evidence limits** that distinguish no matches from incomplete or unavailable analysis. Search modes do not silently switch to each other or to text search.
+- **An optional first-turn overview** with discovered modules, manifest descriptions, declared entrypoints, dependencies, and detected languages. It is enabled by default and labeled as untrusted repository evidence, not instructions.
 
-## Example requests
+The overview is a hidden Pi message, not a live architecture graph. It is not repeated when the active session branch already contains it. All discovered modules are included: 1,000 estimated tokens is a warning threshold, not a size cap.
 
-You do not need to learn the tool-call syntax. Try asking Pi:
+## Usage
 
-- “Map this repository and explain where authentication lives.”
-- “Find every use and implementation of `PaymentProvider`.”
-- “What does `executeAskUser` call, and where is it referenced?”
-- “Find all exported interfaces under `packages/api`.”
-- “Check this project for current language-server diagnostics.”
-- “Rename `oldName` to `newName`, but show me the refactor plan before applying it.”
+Ask Pi normal coding questions. For example:
 
-## See it in action
+- “Map this repository and find the authentication package.”
+- “Find references and implementations of `PaymentProvider`.”
+- “Show the calls written inside `executeAskUser`.”
+- “Find interface declarations under `packages/api`.”
+- “Refresh the language-server diagnostics for this file.”
+- “Preview a rename from `oldName` to `newName`. Do not apply it yet.”
 
-Select any screenshot to open it at full resolution.
+### Agent tools
 
-### Understand the workspace
+The full extension registers all eight tools at startup; it does not load them on demand.
 
-[![Workspace orientation showing package files, manifest details, and relationships][workspace-orientation]][workspace-orientation]
+| Tool | Purpose |
+|---|---|
+| `code_orientation` | Show workspace facts, or focus on a path, module, or symbol target |
+| `code_resolve` | Resolve a real symbol anchor or semantic query to target handles, or list a file's declarations |
+| `code_inspect` | Inspect syntax, the enclosing declaration, hover information, definitions, and nearby diagnostics at one point |
+| `code_graph` | Find semantic references and implementations, or structural calls from the enclosing scope |
+| `code_find` | Search with an explicit `ast` or `semantic` mode |
+| `code_health` | Report diagnostic observations and language-server health |
+| `code_refactor_plan` | Store a semantic refactor preview without changing files |
+| `code_refactor_apply` | Apply a fresh stored plan after file and edit checks |
+
+Use Pi's `grep` for literal or regular-expression search. Source points use 1-based lines and 1-based UTF-16 columns. A target or focus selector must contain exactly one choice.
+
+Example tool calls:
+
+```javascript
+code_orientation({ focus: { path: "packages/api" } })
+code_find({ query: "PaymentProvider", mode: "semantic", scope: ["packages/api"] })
+code_health({ scope: "packages/api/src/index.ts", refresh: true })
+```
 
-### Inspect an exact symbol
+Important tool rules:
 
-[![Symbol inspection showing syntax, hover information, definition, and diagnostics][symbol-inspection]][symbol-inspection]
+- **Resolve:** new target handles require semantic readiness. A comment or whitespace point is not a symbol; use `code_inspect` there. Handles are session-local and become stale when file contents change. Resolve the symbol again rather than reuse a stale handle.
+- **Graph:** relations are `references` (default), `callees`, and `implements`. Use `["all"]` for all three. Callee depth is `direct` by default; `deep` includes nested scopes, not transitive calls. Callees match source shape, not symbol identity. Counts include each distinct call site; repeated expressions share one agent-output row with all shown line/column coordinates. Each relation reports its counts and limits once. Provider-limited results have unknown totals; invalid locations are disclosed separately. Callee previews shorten receiver argument lists from syntax without changing grouping by the full expression. Matching previews get local expression numbers so distinct source expressions remain clear. Unavailable references retain the provider reason, including an exhausted enrollment retry. Unavailable callees retain the provider reason and a source-inspection next step. Ambiguous targets ask for candidate selection, not input correction. Candidate limits retain exact totals, or unknown totals when the provider returns partial data. Agent output and both transcript views disclose omissions. Only shown candidates receive target handles. The human transcript shows the resolved target and per-relation evidence types and status. The expanded view groups up to 20 sites per relation by file, without a duplicate Markdown body. If this display limit hides returned sites, the transcript links to a temporary file with all returned evidence. This file does not include evidence beyond `maxResults`, and its path does not add text to an otherwise complete agent result. Merged read ranges use neutral guidance.
+- **Find:** AST mode requires `kind`: `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, or `enum`. Semantic mode does not accept `kind`. A supplied `scope` is a non-empty array.
+- **Health:** `include` accepts `diagnostics` and `servers` (both by default); `level` is `summary` (default) or `detailed`. Server inventory and route counts remain workspace-wide, even with a diagnostic scope. A diagnostic snapshot does not prove that the whole workspace is clean. Tsconfig and jsconfig coverage applies only to TypeScript and JavaScript-family files; other-language files have no `Tsconfig` label.
 
-### Follow references and calls
+`code_health({ refresh: true })` retries failed startup and exhausted process-crash routes in scope, with at most one attempt per route per call. It collects fresh diagnostic evidence and reports recovery separately from diagnostic confirmation. A broad maintenance attempt can include active tracked files outside a requested directory, but the diagnostic result keeps the requested directory and tracked-file boundary. The report labels maintenance evidence separately from result coverage. A later refresh can retry a failed route. Reports show up to 16 route entries per recovery list and disclose omitted entries. Use an exact file scope when a route reports `use-exact-file`.
 
-[![Relationship graph showing references and direct calls][relationship-graph]][relationship-graph]
+### Transcript failures
 
-### Check live health
+All Code Intelligence tools show PI execution failures with the tool name and the available reason. Structured failure text takes priority; a failure without details uses PI's plain error text. The transcript removes terminal controls and keeps up to 4096 characters. Collapsed output keeps two wrapped rows; expanded output keeps 20. A notice discloses further display limits. These limits do not change agent output or saved results.
 
-[![Code health showing diagnostics and running language servers][code-health]][code-health]
+Candidate selection for Graph, Resolve, and Orientation uses one structured transcript view. The collapsed view shows `Choose a target` and one count summary. The expanded view shows one candidate section and selection guidance; it does not repeat raw Markdown when candidate rows are available. Older results use structured evidence when available. When candidate rows are unavailable, or structured reason or guidance is missing, the renderer uses a bounded raw detail view with up to 4096 source characters and 40 wrapped body rows. It shows a truncation notice and keeps any existing full-output link.
 
-### Preview a safe refactor
+### Refactor checks
 
-[![Refactor plan previewing a semantic rename without changing files][refactor-plan]][refactor-plan]
+The planner accepts one target handle or anchor and one operation: `rename_symbol`, `extract_function`, `extract_variable`, `update_imports`, or `delete_dead_code`. Availability depends on the language server. Unsupported operations do not fall back to text edits.
 
-## Agent tools
+Plans are held in memory for the current session. Apply accepts only the returned `planId`; it does not create or regenerate a plan. It checks SHA-256 file fingerprints, provider-authorized roots, document versions when available, edit ranges, and overlaps before writing. Changed files require a new plan. A successful apply removes the plan.
 
-The package adds eight tools that Pi selects as needed:
+Refactors can change several files. If a later write fails, the tool attempts to restore earlier files and reports restoration failures. It does not create a Git commit. The plan/apply split is not a user confirmation dialog: the agent can call apply. Review the diff and run tests.
 
-| Tool | What it lets the agent do |
-|---|---|
-| `code_orientation` | Understand a workspace, package, directory, file, or symbol before reading broadly |
-| `code_resolve` | Resolve an exact symbol, disambiguate matches, or list declarations in a file |
-| `code_inspect` | Combine AST syntax with LSP type, definition, symbol, and diagnostic facts at one source location |
-| `code_graph` | Follow LSP references and implementations plus AST calls made by a symbol |
-| `code_find` | Search LSP workspace symbols or parsed AST source structure rather than raw text |
-| `code_health` | Check live diagnostics, language servers, and code-intelligence availability |
-| `code_refactor_plan` | Preview a precise rename, extraction, import cleanup, or dead-code deletion without changing files |
-| `code_refactor_apply` | Apply a fresh refactor plan after safety checks |
+## Language support
 
-Pi's built-in `grep` remains the right tool for literal or regular-expression searches; these tools add symbol and source-structure awareness.
+Install the required language servers yourself. The extension detects project languages and starts available configured commands on `PATH` in trusted projects. It does not download or install servers. Individual semantic features depend on server support and readiness.
 
-`code_health({ refresh: true })` reports process-crash recovery as route-level data. It shows exact recovered, skipped, failed, and exhausted counts. It shows up to 16 server and workspace-relative root entries, plus the exact number of omitted entries. A skipped route gives the `use-exact-file` action. A failed or exhausted route gives the `reload-workspace` action. Markdown and expanded TUI output show route entries and bounded failure details. Compact TUI output shows the counts. Current and retained refresh results use the same outcome format.
+Tree-sitter grammars are bundled and parse locally. Grammar selection uses the file extension, not a shebang.
 
-## Install
+| Language | Default LSP binary | Tree-sitter file extensions |
+|---|---|---|
+| TypeScript / JavaScript | `typescript-language-server` | `.ts`, `.mts`, `.cts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` |
+| Python | `pyright-langserver` | `.py`, `.pyi` |
+| Rust | `rust-analyzer` | `.rs` |
+| Go | `gopls` | `.go` |
+| C / C++ | `clangd` | `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++` |
+| Bash | `bash-language-server` | `.sh`, `.bash`, `.zsh`, `.ksh` (Bash grammar) |
+| HTML | `vscode-html-language-server` | `.html`, `.htm`, `.xhtml` |
+| SQL | `sql-language-server` | `.sql` |
+| Ruby | `ruby-lsp` | `.rb`, `.gemspec` |
+| Java | `jdtls` | `.java` |
+| Kotlin | `kotlin-lsp` | `.kt`, `.kts` |
+| R | `R` with the `languageserver` package | `.r` |
 
-```bash
-pi install npm:@mrclrchtr/supi-code-intelligence
+Operation support is narrower than grammar support. AST import and export search supports only JavaScript, TypeScript, and TSX. Other AST operations depend on the grammar's extractors. A missing LSP server does not prevent available workspace or structural queries, but it prevents new semantic targets and related operations.
+
+### Search and output limits
+
+- An AST search has a 5,000 eligible-file limit and a 10-second deadline shared by file enumeration and analysis. These are not tool-call settings.
+- Below directory roots, AST search excludes hidden entries, dependency/build/cache directories, symlinks, non-regular files, and files unsupported by the requested operation. It does **not** read `.gitignore`. Explicit roots are resolved and honored, including symlink roots. See the [scan policy](src/analysis/search/ast-scan.ts) for the exact directory list.
+- An exact file that does not support the requested AST operation is invalid. Results disclose policy exclusions, interrupted scans, provider limits, and omitted matches. No matches do not mean that unsupported files were searched.
+- Tool text is truncated at Pi's default 2,000 lines or 50 KB. When this occurs, the full text is written to a temporary file and its path is returned. Result-list limits still apply to that full text.
+
+## Status and settings
+
+In interactive Pi, open the status overlay:
+
+```text
+/supi-ci-status
 ```
 
-To try it for one run without installing:
+It shows server routes and roots, missing or running servers, diagnostics, and capability warnings. The terminal must be at least 60 columns wide. Use Up/Down to select a diagnostic file, Enter or Space to expand it, `r` to reload the displayed snapshot, `a` to collapse it, and Escape to close. The extension also adds LSP status to the footer. Use `code_health` for health reports outside the interactive terminal.
 
-```bash
-pi -e npm:@mrclrchtr/supi-code-intelligence
+The package registers **Code Intelligence** and **LSP** settings. If `@mrclrchtr/supi-settings` is installed, use `/supi-settings` to edit them. A standalone Code Intelligence install does not include that settings UI.
+
+Configuration files:
+
+- Global: `~/.pi/agent/supi/config.json`
+- Project: `.pi/supi/config.json`
+
+Project values override global values, which override defaults. Project configuration and instruction discovery require project trust. For an untrusted project, the overview setting uses global values and defaults only; no LSP controller is started for that session.
+
+| Setting | Default | Effect |
+|---|---|---|
+| `code-intelligence.overviewEnabled` | `true` | Add the hidden overview; the choice is fixed for the session |
+| `code-intelligence.instructionFileNames` | `["CLAUDE.md", "AGENTS.md"]` | Ordered plain filenames for directory instruction discovery |
+| `lsp.exclude` | `[]` | Gitignore-style patterns for automatic LSP work, not exact-file requests |
+| `lsp.servers.<language>.enabled` | Enabled unless `false` | Disable a language server |
+
+Example `.pi/supi/config.json`:
+
+```json
+{
+  "code-intelligence": {
+    "overviewEnabled": false,
+    "instructionFileNames": ["AGENTS.md", "CLAUDE.md"]
+  },
+  "lsp": {
+    "exclude": ["generated/**"],
+    "servers": {
+      "python": { "enabled": false }
+    }
+  }
+}
 ```
 
-## Language support
+Use `typescript`, `python`, `rust`, `go`, `c`, `ruby`, `java`, `kotlin`, `bash`, `html`, `sql`, or `r` for built-in server keys (`cpp` aliases `c`). Server command and routing overrides are defined in the [LSP configuration reference](../supi-lsp/README.md#custom-server-configuration). `.pi-lsp.json` is not read. Restart Pi after server configuration changes. Only the boolean `true` enables the overview; non-boolean values do not enable it.
+
+Directory orientation checks the path from the workspace root to the focused directory. It selects the first valid configured instruction file per directory, skips files already loaded by Pi or shown on the active branch, and shows at most 200 lines per file. Resolved instruction paths must stay inside the workspace. These snippets are tool output, not additions to Pi's system prompt.
+
+## Privacy and security
 
-Structural code search is bundled with the package. Full symbol navigation, references, diagnostics, and semantic refactoring require the matching language server on `PATH`.
+Pi extensions run with your system permissions; this package is not a sandbox. Language servers run as local processes and receive source files. Review server commands and project configuration before trusting a project. `lsp.exclude` and AST scan exclusions are not access controls.
 
-The extension detects project languages and starts installed servers automatically:
+Tool results and the hidden overview enter Pi's model context and can be saved in session history. They can contain source text, paths, manifest data, diagnostics, and instruction-file contents. Truncated tool results and graph display overflow also leave full returned text in local temporary files. These files are not durable session storage and can be removed by system cleanup. “Hidden” means not displayed in the transcript, not hidden from the model.
 
-| Language | Required binary |
+## Public entrypoints
+
+| Export | Surface |
 |---|---|
-| TypeScript / JavaScript | `typescript-language-server` |
-| Python | `pyright-langserver` |
-| Rust | `rust-analyzer` |
-| Go | `gopls` |
-| C / C++ | `clangd` |
-| Bash | `bash-language-server` |
-| HTML | `vscode-html-language-server` |
-| SQL | `sql-language-server` |
-| Ruby | `ruby-lsp` |
-| Java | `jdtls` |
-| Kotlin | `kotlin-lsp` |
-| R | `R` with the `languageserver` package |
-
-If a server is missing, the agent can still use available workspace and structural evidence. Semantic features report that they are unavailable rather than silently guessing.
+| `@mrclrchtr/supi-code-intelligence/api` | Type-only provider contracts, architecture models, targets, health observations, and tool results; no runtime functions |
+| `@mrclrchtr/supi-code-intelligence/extension` | Default full Pi extension factory |
+| `@mrclrchtr/supi-code-intelligence/headless` | Default inspection-only extension factory and `HEADLESS_INSPECTION_TOOL_NAMES` |
+| `@mrclrchtr/supi-code-intelligence/package.json` | Package manifest |
 
-## Status and settings
+The package-root export also re-exports types; prefer `/api`. See [the type exports](src/api.ts) for the complete list.
 
-Open the status view to see each LSP route with its workspace-relative root, running or missing servers, typed route issue counts, and capability warnings:
+The headless factory registers only `code_resolve`, `code_inspect`, `code_orientation`, `code_graph`, `code_find`, and `code_health` for managed child sessions. It adds no refactor tools, settings, commands, UI, or overview. It is a tool profile, not a filesystem sandbox.
 
-```text
-/supi-ci-status
-```
+## See it in action
+
+Select any screenshot to open it at full resolution.
 
-Use `/supi-settings` to disable language servers you do not need, change the instruction filenames surfaced during directory orientation (defaults `CLAUDE.md` and `AGENTS.md`), or disable the first-turn architecture overview with `overviewEnabled`.
+### Understand the workspace
+
+[![Workspace orientation showing package files, manifest details, and relationships][workspace-orientation]][workspace-orientation]
+
+### Inspect an exact symbol
+
+[![Symbol inspection showing syntax, hover information, definition, and diagnostics][symbol-inspection]][symbol-inspection]
+
+### Follow references and calls
+
+[![Relationship graph showing references and direct calls][relationship-graph]][relationship-graph]
+
+### Check live health
+
+[![Code health showing diagnostics and running language servers][code-health]][code-health]
+
+### Preview a refactor
+
+[![Refactor plan previewing a semantic rename without changing files][refactor-plan]][refactor-plan]
 
 [workspace-orientation]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/workspace-orientation.png
 [symbol-inspection]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/symbol-inspection.png

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts

@@ -234,7 +234,14 @@ export type CalleeDepth = "direct" | "deep";
  */
 export interface CalleesData {
   enclosingScope: { name: string; startLine: number; endLine: number };
-  callees: Array<{ name: string; startLine: number }>;
+  /** Distinct call sites with 1-based UTF-16 start coordinates. */
+  callees: Array<{
+    name: string;
+    /** Optional syntax-shortened label for presentation; does not replace `name`. */
+    displayName?: string;
+    startLine: number;
+    startCharacter: number;
+  }>;
   depth: CalleeDepth;
 }
 

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/llm` — PI-owned direct model requests and JSON helpers
 - `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
 
 ## What you get from the API
@@ -48,6 +49,13 @@ Config file locations:
 
 - `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 
+### Model requests
+
+- `completeModelRequest(ctx, model, context, options)` — complete through PI's model registry with stable feature affinity. PI owns auth and endpoint resolution.
+- `callWithJsonResponse()` — retry a registry request, extract JSON, and validate it with TypeBox.
+
+`completeModelRequest()` requires a stable `affinityScope`. It keeps cache retention defaults, does not include prompt content in the affinity ID, and adds OpenCode headers only when the provider or exact model endpoint matches OpenCode. Pass `maxTokens: model.maxTokens` when a caller needs the model's declared output cap without using PI private modules.
+
 ### Shared registries
 
 - context-provider registry for `/supi-context`

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts

@@ -2,17 +2,24 @@
 //
 // Extensions register pre-styled text chunks with a placement hint
 // ("stats" for the metrics line, "status" for the extension status line).
-// The custom footer in supi-extras (or PI's built-in footer) reads these
-// contributions and renders them alongside the built-in metrics.
+// The custom footer in supi-extras reads these contributions and renders them
+// alongside the built-in metrics. Extensions can use PI's status API as a
+// fallback when the custom footer is not installed.
 
 import { createRegistry } from "./registry-utils.ts";
 
+/** Event emitted when a dynamic footer contribution needs a new render. */
+export const FOOTER_INVALIDATE_EVENT = "supi:footer:invalidate";
+
 /** Where the contribution should appear in the footer. */
 export type FooterPlacement = "stats" | "stats-end" | "status";
 
 /** A single footer contribution registered by an extension. */
 export interface FooterContribution {
-  /** Unique key for this contribution. Re-registering with the same key replaces it. */
+  /**
+   * Unique key for this contribution. Re-registering with the same key replaces it.
+   * A same-key Pi status is treated as this contribution's built-in-footer fallback.
+   */
   key: string;
   /** Which footer line this belongs on. */
   placement: FooterPlacement;

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -15,6 +15,8 @@ export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./llm.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./model-selection.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";

package/node_modules/@mrclrchtr/supi-core/src/llm.ts

@@ -1,12 +1,131 @@
-import { complete } from "@earendil-works/pi-ai/compat";
+import { createHash } from "node:crypto";
+import type {
+  Api,
+  AssistantMessage,
+  Context,
+  Model,
+  ModelsApiStreamOptions,
+  ProviderHeaders,
+} from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TSchema } from "typebox";
 import { Value } from "typebox/value";
 
 // Shared LLM utilities for SuPi extensions.
 //
-// Provides retry logic, structured LLM call helpers, and other
-// common patterns for extensions that interact with AI models.
+// Provides PI-owned model requests, retry logic, structured LLM call helpers,
+// and other common patterns for extensions that interact with AI models.
+
+const MODEL_REQUEST_NAMESPACE = "supi-direct-model-request-v1";
+
+/**
+ * Options for {@link completeModelRequest}.
+ *
+ * Authentication, provider environment, and session identity stay under PI
+ * control. The feature supplies a stable scope for its prompt stream.
+ */
+export type CompleteModelRequestOptions<TApi extends Api = Api> = Omit<
+  ModelsApiStreamOptions<TApi>,
+  "apiKey" | "env" | "sessionId"
+> & {
+  /** Stable feature scope. Do not include prompt, turn, or retry data. */
+  affinityScope: string;
+  /** PI owns these fields, including for APIs with open-ended option types. */
+  apiKey?: never;
+  env?: never;
+  sessionId?: never;
+};
+
+function createModelRequestAffinityId(
+  sessionId: string,
+  affinityScope: string,
+  model: Model<Api>,
+): string {
+  const material = JSON.stringify([
+    MODEL_REQUEST_NAMESPACE,
+    sessionId,
+    affinityScope,
+    model.provider,
+    model.id,
+  ]);
+  const digest = createHash("sha256").update(material, "utf8").digest("hex");
+  return `supi-${digest.slice(0, 56)}`;
+}
+
+function isOpenCodeModel(model: Model<Api>): boolean {
+  if (model.provider === "opencode" || model.provider === "opencode-go") return true;
+
+  try {
+    return new URL(model.baseUrl).hostname === "opencode.ai";
+  } catch {
+    return false;
+  }
+}
+
+function hasHeader(headers: ProviderHeaders, name: string): boolean {
+  const lowerName = name.toLowerCase();
+  return Object.keys(headers).some((headerName) => headerName.toLowerCase() === lowerName);
+}
+
+function addOpenCodeDefaultHeaders(
+  model: Model<Api>,
+  affinityId: string,
+  headers: ProviderHeaders,
+): ProviderHeaders {
+  if (!isOpenCodeModel(model)) return headers;
+
+  const result = { ...headers };
+  if (!hasHeader(result, "x-opencode-session")) {
+    result["x-opencode-session"] = affinityId;
+  }
+  if (!hasHeader(result, "x-opencode-client")) {
+    result["x-opencode-client"] = "pi";
+  }
+  return result;
+}
+
+/**
+ * Complete a direct request through PI's model registry.
+ *
+ * PI resolves authentication, provider headers, environment, and the
+ * effective endpoint. This helper adds one stable opaque session identity for
+ * the feature prompt stream and applies the OpenCode compatibility defaults.
+ * It does not retry, validate output, or present errors.
+ *
+ * When `maxTokens` is omitted, the underlying registry receives no explicit
+ * output cap. A caller that needs the selected model's declared cap can pass
+ * `maxTokens: model.maxTokens` without importing PI internals.
+ */
+export async function completeModelRequest<TApi extends Api>(
+  ctx: ExtensionContext,
+  model: Model<TApi>,
+  context: Context,
+  options: CompleteModelRequestOptions<TApi>,
+): Promise<AssistantMessage> {
+  const { affinityScope, transformHeaders: callerTransformHeaders, ...requestOptions } = options;
+  const safeRequestOptions = { ...requestOptions };
+  delete safeRequestOptions.apiKey;
+  delete safeRequestOptions.env;
+  delete safeRequestOptions.sessionId;
+
+  const affinityId = createModelRequestAffinityId(
+    ctx.sessionManager.getSessionId(),
+    affinityScope,
+    model,
+  );
+  const transformHeaders = async (headers: ProviderHeaders): Promise<ProviderHeaders> => {
+    const transformed = callerTransformHeaders ? await callerTransformHeaders(headers) : headers;
+    return addOpenCodeDefaultHeaders(model, affinityId, transformed);
+  };
+
+  // Restore PI's conditional provider-option type after removing owned fields.
+  return ctx.modelRegistry.complete(model, context, {
+    ...safeRequestOptions,
+    signal: safeRequestOptions.signal ?? ctx.signal,
+    sessionId: affinityId,
+    transformHeaders,
+  } as unknown as ModelsApiStreamOptions<TApi>);
+}
 
 /**
  * Options for {@link withRetry}.
@@ -122,6 +241,8 @@ export function extractJsonFromResponse<T extends TSchema>(
 export interface CallWithJsonResponseOptions {
   /** The prompt to send to the LLM. */
   prompt: string;
+  /** Stable feature scope for request affinity. Do not include prompt or retry data. */
+  affinityScope: string;
   /** Optional data context appended to the prompt. */
   dataContext?: string;
   /** Maximum tokens for the response. Default: 4096 */
@@ -135,8 +256,9 @@ export interface CallWithJsonResponseOptions {
 /**
  * Call the LLM with a prompt and validate the JSON response against a TypeBox schema.
  *
- * Handles model resolution, auth, retry via `withRetry`, text extraction,
- * JSON regex matching, and TypeBox validation.
+ * Handles model resolution, retry via `withRetry`, text extraction, JSON
+ * matching, and TypeBox validation. The request itself stays under PI
+ * registry authority through {@link completeModelRequest}.
  *
  * Returns `null` when:
  * - No model is available
@@ -145,7 +267,7 @@ export interface CallWithJsonResponseOptions {
  * - JSON doesn't match the schema
  * - The request is aborted
  *
- * @param ctx - The extension context for model resolution and auth.
+ * @param ctx - The extension context for model selection and PI registry access.
  * @param options - Call options including prompt, schema, and retry config.
  * @param schema - TypeBox schema to validate the JSON response against.
  * @returns The parsed and validated result, or `null`.
@@ -155,14 +277,18 @@ export async function callWithJsonResponse<T extends TSchema>(
   options: CallWithJsonResponseOptions,
   schema: T,
 ): Promise<{ parsed: import("typebox").Static<T> } | null> {
-  const { prompt, dataContext, maxTokens = 4096, systemPrompt = "", retries = 2 } = options;
+  const {
+    prompt,
+    affinityScope,
+    dataContext,
+    maxTokens = 4096,
+    systemPrompt = "",
+    retries = 2,
+  } = options;
 
   const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0] ?? null;
   if (!model) return null;
 
-  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-  if (!auth.ok || !auth.apiKey) return null;
-
   const fullPrompt = dataContext
     ? `${prompt}
 
@@ -171,8 +297,9 @@ ${dataContext}`
     : prompt;
 
   const response = await withRetry(
-    async () => {
-      return complete(
+    async () =>
+      completeModelRequest(
+        ctx,
         model,
         {
           systemPrompt,
@@ -185,13 +312,11 @@ ${dataContext}`
           ],
         },
         {
-          apiKey: auth.apiKey,
-          headers: auth.headers,
+          affinityScope,
           signal: ctx.signal,
           maxTokens,
         },
-      );
-    },
+      ),
     { retries, baseDelayMs: 1000, signal: ctx.signal },
   );