@mrclrchtr/supi-insights 6.4.0 → 7.0.0

package/README.md

@@ -44,6 +44,8 @@ The command pipeline is:
 4. aggregate the results across sessions
 5. generate an HTML report and post a short in-chat summary with the saved file path
 
+All direct model requests use `@mrclrchtr/supi-core/llm`. Requests use separate stable scopes for facet extraction, chunk summaries, report sections, and the overview. PI resolves request auth and endpoints.
+
 ## What the report covers
 
 The generated report can include:

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.4.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 },
   );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-insights",
-  "version": "6.4.0",
+  "version": "7.0.0",
   "description": "Historical Pi-session reports and shareable HTML",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "6.4.0"
+    "@mrclrchtr/supi-core": "7.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/extractor.ts

@@ -1,8 +1,7 @@
 // LLM facet extraction — analyze session transcripts and extract structured facets.
 
-import { complete } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { callWithJsonResponse } from "@mrclrchtr/supi-core/llm";
+import { callWithJsonResponse, completeModelRequest } from "@mrclrchtr/supi-core/llm";
 import { Type } from "typebox";
 import type { SessionFacets } from "./types.ts";
 
@@ -91,6 +90,7 @@ export async function extractFacets(
     ctx,
     {
       prompt: `${FACET_EXTRACTION_PROMPT}${processedTranscript}`,
+      affinityScope: "insights:extraction",
       maxTokens: 4096,
       retries: 2,
     },
@@ -108,9 +108,6 @@ async function summarizeTranscript(transcript: string, ctx: ExtensionContext): P
   const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0];
   if (!model) return transcript.slice(0, 30000);
 
-  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-  if (!auth.ok || !auth.apiKey) return transcript.slice(0, 30000);
-
   const CHUNK_SIZE = 25000;
   const chunks: string[] = [];
   for (let i = 0; i < transcript.length; i += CHUNK_SIZE) {
@@ -120,7 +117,8 @@ async function summarizeTranscript(transcript: string, ctx: ExtensionContext): P
   const summaries = await Promise.all(
     chunks.map(async (chunk) => {
       try {
-        const response = await complete(
+        const response = await completeModelRequest(
+          ctx,
           model,
           {
             systemPrompt: "",
@@ -133,12 +131,14 @@ async function summarizeTranscript(transcript: string, ctx: ExtensionContext): P
             ],
           },
           {
-            apiKey: auth.apiKey,
-            headers: auth.headers,
+            affinityScope: "insights:chunk-summary",
             signal: ctx.signal,
             maxTokens: 500,
           },
         );
+        if (response.stopReason === "error" || response.stopReason === "aborted") {
+          return chunk.slice(0, 2000);
+        }
         return response.content
           .filter((c): c is { type: "text"; text: string } => c.type === "text")
           .map((c) => c.text)

package/src/generator.ts

@@ -176,6 +176,7 @@ async function generateSectionInsight<Name extends ParallelInsightSectionName>(
     ctx,
     {
       prompt: section.prompt,
+      affinityScope: `insights:report-section:${section.name}`,
       dataContext,
       maxTokens: section.maxTokens,
       retries: 2,
@@ -259,6 +260,7 @@ ${horizonText}`;
     ctx,
     {
       prompt,
+      affinityScope: "insights:overview",
       maxTokens: 4096,
       retries: 2,
     },