@mrclrchtr/supi-prompt-suggestions 6.3.0 → 7.0.0

package/README.md

@@ -53,6 +53,9 @@ The default is `disabled`. Pick a cheap, fast model if you want lightweight sugg
 
 Settings follow SuPi's normal scoped config behavior: set a global default, then override it per project when needed.
 
+Suggestion requests use PI's model registry. PI owns authentication and provider routing; the
+extension does not resolve or copy credentials.
+
 ## Privacy
 
 When suggestions are enabled, the suggestion model receives only the last assistant message, trimmed to the final 8,000 characters.
@@ -63,7 +66,10 @@ The extension does **not** send:
 - tool outputs
 - file contents
 - project metadata
-- session metadata
+- session metadata in the prompt
+
+The request can include a separate opaque provider-routing identity. It is not part of the prompt and
+is derived from the PI session, provider, model, and prompt-suggestion stream.
 
 ## Troubleshooting
 
@@ -71,6 +77,13 @@ If no suggestion appears:
 
 - confirm **Suggestion model** is not `disabled`
 - confirm the selected model is still enabled in PI for the current scope
-- confirm the selected model has an API key configured
+- if a warning reports authentication failed, check the selected model's authentication in PI
 - make sure the editor is empty after the assistant finishes
 - wait for the suggestion spinner to finish; generation times out after about 20 seconds
+
+Request failures show one warning for the active model and session. The warning contains only the
+provider/model identifier, a safe failure category, and an optional HTTP status. Categories include
+authentication failed, billing failed, quota exceeded, rate limit exceeded, timeout, and provider
+request failed. Repeated failures stay quiet until a request succeeds, settings change, or a new
+session starts. Warning state is held in memory, so `/reload` also starts a new warning cycle. The
+separate routing identity remains stable for the same PI session.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-prompt-suggestions",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Optional model-powered ghost-text prompt suggestions",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "video": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-prompt-suggestions/assets/demo.mp4"
   },
   "dependencies": {
-    "@mrclrchtr/supi-core": "6.3.0"
+    "@mrclrchtr/supi-core": "7.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/config/settings.ts

@@ -8,11 +8,18 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
+import {
+  defineConfigSettings,
+  registerSettings,
+  type SettingsPersistedChange,
+} from "@mrclrchtr/supi-core/settings";
 import { CONFIG_SECTION, DEFAULTS } from "./config.ts";
 
 /** Register the prompt-suggestions settings section. */
-export function registerPromptSuggestionsSettings(pi: ExtensionAPI): void {
+export function registerPromptSuggestionsSettings(
+  pi: ExtensionAPI,
+  afterPersist?: (change: SettingsPersistedChange) => void,
+): void {
   registerSettings(
     pi,
     defineConfigSettings({
@@ -28,6 +35,7 @@ export function registerPromptSuggestionsSettings(pi: ExtensionAPI): void {
           description: "Model used for ghost-text suggestions. Select 'disabled' to turn off.",
         },
       ],
+      afterPersist,
     }),
   );
 }

package/src/editor/editor.ts

@@ -43,7 +43,11 @@ export class GhostTextEditor extends CustomEditor {
     options: GhostTextEditorOptions,
   ) {
     const { callbacks, ...editorOptions } = options;
-    super(tui, theme, keybindings, editorOptions);
+    const customEditorOptions = {
+      ...editorOptions,
+      embedWorkingStatus: true,
+    };
+    super(tui, theme, keybindings, customEditorOptions);
     this.callbacks = callbacks;
   }
 

package/src/extension.ts

@@ -14,13 +14,13 @@ import { SuggestionGenerator } from "./generation/generator.ts";
 import { SessionLifecycle } from "./session.ts";
 
 export default function (pi: ExtensionAPI): void {
-  registerPromptSuggestionsSettings(pi);
-
   const generator = new SuggestionGenerator();
   const session = new SessionLifecycle(generator);
 
+  registerPromptSuggestionsSettings(pi, () => session.onSettingsChanged());
+
   pi.on("session_start", (_event, ctx) => session.onStart(ctx));
-  pi.on("agent_end", (event, ctx) => session.onAgentEnd(event, ctx));
+  pi.on("agent_settled", (_event, ctx) => session.onAgentSettled(ctx));
   pi.on("agent_start", () => session.onAgentStart());
   pi.on("session_shutdown", () => session.onShutdown());
 }

package/src/generation/client.ts

@@ -1,16 +1,16 @@
-/**
- * Low-level suggestion model client.
- *
- * Pure functions for calling the suggestion model — no module-level state,
- * no orchestration, no debug logging.
- *
- * @module
- */
+/** Low-level suggestion model client. */
 
-import type { ProviderHeaders } from "@earendil-works/pi-ai";
-import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { Api, Context, Model } from "@earendil-works/pi-ai";
+import { clampMaxTokensToContext } from "@earendil-works/pi-ai/api/simple-options";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { completeModelRequest } from "@mrclrchtr/supi-core/llm";
+import {
+  classifySuggestionFailure,
+  createSuggestionFailure,
+  type SuggestionFailure,
+} from "./failure.ts";
 
-// ── Constants ──────────────────────────────────────────────────────────
+// ── Constants ──────────────────────────────────────────────────────────────
 
 export const GENERATION_TIMEOUT_MS = 20_000;
 
@@ -32,95 +32,88 @@ const SYSTEM_PROMPT =
   "If there is no useful follow-up, respond with exactly the word NO_SUGGESTION and nothing else. " +
   "Keep suggestions under 240 characters.";
 
-// ── Prompt building ────────────────────────────────────────────────────
+// ── Prompt building ────────────────────────────────────────────────────────
 
-/**
- * Format the tail text as a completion prompt.
- *
- * Instructions live in {@link SYSTEM_PROMPT} — the user message
- * only provides the assistant message content to suggest from.
- */
+/** Format the tail text as a completion prompt. */
 export function buildPrompt(tail: string): string {
   return `<assistant_message>\n${tail}\n</assistant_message>\n\nSuggestion:`;
 }
 
-// ── Types ──────────────────────────────────────────────────────────────
+// ── Types ───────────────────────────────────────────────────────────────────
 
 export interface SuggestionClientResult {
   ok: true;
   text: string;
 }
 
+/** Classified request failure without provider response text. */
+export type SuggestionClientFailure = SuggestionFailure;
+
 export interface SuggestionClientError {
   ok: false;
-  message: string;
+  failure: SuggestionClientFailure;
 }
 
 export type SuggestionClientOutput = SuggestionClientResult | SuggestionClientError;
 
 export interface SuggestionClientOptions {
-  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
-  model: any;
-  auth: { apiKey: string; headers?: ProviderHeaders; env?: Record<string, string> };
+  ctx: ExtensionContext;
+  model: Model<Api>;
   tail: string;
   signal: AbortSignal;
 }
 
-// ── API call ───────────────────────────────────────────────────────────
+// ── API call ────────────────────────────────────────────────────────────────
 
 /**
- * Call the suggestion model with a simple completion prompt.
+ * Call the suggestion model through PI's model registry.
  *
- * Pure function — all side effects (HTTP, abort) are scoped to the call.
- * Returns a structured result; does not log or interact with the extension
- * context.
+ * The request keeps the fixed prompt and bounded assistant tail. PI resolves
+ * authentication, endpoint, headers, and provider environment.
  */
 export async function callSuggestionModel(
   opts: SuggestionClientOptions,
 ): Promise<SuggestionClientOutput> {
-  const { model, auth, tail, signal } = opts;
-
-  const response = await completeSimple(
-    model,
-    {
-      systemPrompt: SYSTEM_PROMPT,
-      messages: [
-        {
-          role: "user",
-          content: [{ type: "text", text: buildPrompt(tail) }],
-          timestamp: Date.now(),
-        },
-      ],
-    },
-    {
-      apiKey: auth.apiKey,
-      headers: auth.headers,
-      env: auth.env,
-      signal,
-    },
-  );
-
-  if (response?.stopReason === "error") {
-    const message = `Suggestion model failed: ${response.errorMessage ?? response.stopReason}`;
-    return { ok: false, message };
-  }
-
-  if (!response?.content) {
-    const message = `Suggestion model returned no content (stopReason: ${response?.stopReason ?? "undefined"})`;
-    return { ok: false, message };
-  }
-
-  // Prompt suggestions are taken from normal user-visible text only.
-  const textContent = response.content
-    .filter((c: { type: string }) => c.type === "text")
-    .map((c: { type: string; text?: string }) => c.text)
-    .join("");
-
-  if (!textContent) {
-    const contentTypes = response.content.map((c: { type: string }) => c.type);
-    const message = `Suggestion model returned no text (stopReason: ${response.stopReason ?? "undefined"}, content types: [${contentTypes.join(", ") || "none"}])`;
-    return { ok: false, message };
+  const context: Context = {
+    systemPrompt: SYSTEM_PROMPT,
+    messages: [
+      {
+        role: "user",
+        content: [{ type: "text", text: buildPrompt(opts.tail) }],
+        timestamp: Date.now(),
+      },
+    ],
+  };
+
+  try {
+    const response = await completeModelRequest(opts.ctx, opts.model, context, {
+      affinityScope: "prompt-suggestions",
+      signal: opts.signal,
+      maxTokens: clampMaxTokensToContext(opts.model, context, opts.model.maxTokens),
+    });
+
+    if (response.stopReason === "aborted") {
+      return failureResult(createSuggestionFailure("timeout"));
+    }
+    if (response.stopReason === "error") {
+      return failureResult(classifySuggestionFailure(response.errorMessage));
+    }
+
+    // An empty successful response is a valid no-suggestion result. Thinking or
+    // other non-text blocks are also harmless when no user-visible text exists.
+    const textContent = Array.isArray(response.content)
+      ? response.content
+          .filter((content): content is { type: "text"; text: string } => content.type === "text")
+          .map((content) => content.text)
+          .join("")
+      : "";
+
+    return { ok: true, text: textContent };
+  } catch (error) {
+    return failureResult(classifySuggestionFailure(error));
   }
+}
 
-  return { ok: true, text: textContent };
+function failureResult(failure: SuggestionFailure): SuggestionClientError {
+  return { ok: false, failure };
 }