@mrclrchtr/supi-prompt-suggestions 1.16.1

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mrclrchtr/supi-prompt-suggestions",
+  "version": "1.16.1",
+  "description": "Advisory ghost-text prompt suggestions for the pi coding agent",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src/**/*.ts",
+    "!__tests__"
+  ],
+  "exports": {
+    "./extension": {
+      "types": "./src/extension.ts",
+      "import": "./src/extension.ts"
+    },
+    "./api": {
+      "types": "./src/api.ts",
+      "import": "./src/api.ts"
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "devDependencies": {
+    "@types/node": "25.9.4",
+    "vitest": "4.1.9"
+  }
+}

package/src/api.ts

@@ -0,0 +1,8 @@
+/**
+ * @mrclrchtr/supi-prompt-suggestions
+ *
+ * Advisory ghost-text prompt suggestions for the pi coding agent.
+ * @module
+ */
+
+export type { PromptSuggestionsConfig } from "./config/config.ts";

package/src/config/config.ts

@@ -0,0 +1,16 @@
+/**
+ * Config types and defaults for supi-prompt-suggestions.
+ *
+ * @module
+ */
+
+export interface PromptSuggestionsConfig extends Record<string, unknown> {
+  /** The suggestion model in `provider/model-id` format, or `"disabled"`. */
+  model: string;
+}
+
+export const DEFAULTS: PromptSuggestionsConfig = {
+  model: "disabled",
+};
+
+export const CONFIG_SECTION = "promptSuggestions";

package/src/config/settings.ts

@@ -0,0 +1,44 @@
+/**
+ * Settings registration for supi-prompt-suggestions.
+ *
+ * Registers a `promptSuggestions` section with a single `model` picker
+ * that shows `disabled` first, then the scoped model set.
+ *
+ * @module
+ */
+
+import { registerConfigSettings } from "@mrclrchtr/supi-core/config";
+import { createModelPickerSubmenu } from "@mrclrchtr/supi-core/settings-ui";
+import { CONFIG_SECTION, DEFAULTS } from "./config.ts";
+
+const MODEL_ITEM_ID = "model";
+
+/** Register the prompt-suggestions settings section. */
+export function registerPromptSuggestionsSettings(): void {
+  registerConfigSettings({
+    id: "promptSuggestions",
+    label: "Prompt suggestions",
+    section: CONFIG_SECTION,
+    defaults: DEFAULTS,
+    buildItems: (settings, _scope, _cwd, ctx) => [
+      {
+        id: MODEL_ITEM_ID,
+        label: "Suggestion model",
+        description: "Model used for ghost-text suggestions. Select 'disabled' to turn off.",
+        currentValue: settings.model,
+        submenu: (currentValue: string, done: (selectedValue?: string) => void) =>
+          createModelPickerSubmenu(currentValue, done, ctx),
+      },
+    ],
+    // biome-ignore lint/complexity/useMaxParams: callback shape mandated by registerConfigSettings API
+    persistChange: (_scope, _cwd, settingId, value, helpers) => {
+      if (settingId === MODEL_ITEM_ID) {
+        if (value === "disabled") {
+          helpers.unset(MODEL_ITEM_ID);
+        } else {
+          helpers.set(MODEL_ITEM_ID, value);
+        }
+      }
+    },
+  });
+}

package/src/editor/editor.ts

@@ -0,0 +1,138 @@
+/**
+ * Ghost-text editor component.
+ *
+ * Extends PI's CustomEditor and renders prompt suggestions as dim ghost text
+ * after the cursor in an empty editor.
+ *
+ * @module
+ */
+
+import { CustomEditor, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import {
+  CURSOR_MARKER,
+  type EditorOptions,
+  type EditorTheme,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface GhostTextCallbacks {
+  onAccept: (suggestion: string) => void;
+  onDismiss: () => void;
+}
+
+export interface GhostTextEditorOptions extends EditorOptions {
+  callbacks: GhostTextCallbacks;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export class GhostTextEditor extends CustomEditor {
+  private suggestion: string | null = null;
+  private callbacks: GhostTextCallbacks;
+
+  constructor(
+    tui: TUI,
+    theme: EditorTheme,
+    keybindings: KeybindingsManager,
+    options: GhostTextEditorOptions,
+  ) {
+    const { callbacks, ...editorOptions } = options;
+    super(tui, theme, keybindings, editorOptions);
+    this.callbacks = callbacks;
+  }
+
+  // ── Ghost text API ──────────────────────────────────────────
+
+  setSuggestion(suggestion: string | null): void {
+    this.suggestion = suggestion;
+    this.tui.requestRender();
+  }
+
+  clearGhost(): void {
+    this.suggestion = null;
+    this.tui.requestRender();
+  }
+
+  // ── Input handling ──────────────────────────────────────────
+
+  override handleInput(data: string): void {
+    if (this.suggestion) {
+      // Use PI's matchesKey (not raw escape sequences) — it handles
+      // CSI (\x1b[C), SS3 (\x1bOC), and Kitty keyboard protocol correctly.
+      if (matchesKey(data, "right")) {
+        this.insertTextAtCursor(this.suggestion);
+        this.callbacks.onAccept(this.suggestion);
+        this.clearGhost();
+        return;
+      }
+      this.clearGhost();
+      this.callbacks.onDismiss();
+    }
+    super.handleInput(data);
+  }
+
+  // ── Rendering ───────────────────────────────────────────────
+
+  override render(width: number): string[] {
+    const lines = super.render(width);
+    if (!this.suggestion || !this.focused) return lines;
+
+    const markerIndex = findCursorMarkerLine(lines);
+    if (markerIndex === -1) return lines;
+
+    const markerLine = lines[markerIndex];
+    if (!markerLine) return lines;
+
+    // Cap ghost text to at most half the terminal width.
+    const cursorPos = markerLine.indexOf(CURSOR_MARKER);
+    const available = width - visibleWidth(markerLine.slice(0, cursorPos));
+    const maxGhost = Math.min(available - 1, Math.floor(width / 2));
+    if (maxGhost <= 0) return lines;
+    const plainSuggestion = truncateToWidth(this.suggestion, maxGhost, "");
+    if (!plainSuggestion) return lines;
+    const ghost = `\x1b[2m${plainSuggestion}\x1b[0m`;
+    const gw = visibleWidth(plainSuggestion);
+
+    // Shrink the line first so ghost addition stays within terminal width.
+    const shrunk = truncateToWidth(markerLine, width - gw, "");
+    if (!shrunk.includes(CURSOR_MARKER)) return lines;
+
+    const insertPos = ghostInsertPosition(shrunk);
+
+    lines[markerIndex] = shrunk.slice(0, insertPos) + ghost + shrunk.slice(insertPos);
+    return lines;
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Find the character position where ghost text should be inserted on
+ * a line containing {@link CURSOR_MARKER}.
+ *
+ * The ghost text is inserted after the visual cursor block emitted by
+ * `CustomEditor`.  Since the cursor is rendered as an inverse-video span
+ * bounded by `\x1b[7m` … `\x1b[0m`, we search for the reset escape after
+ * the cursor marker to skip the entire block.
+ *
+ * @remarks
+ * This depends on `CustomEditor`'s internal ANSI encoding of the cursor.
+ * If the upstream cursor rendering changes, this helper must be updated.
+ */
+function ghostInsertPosition(line: string): number {
+  const cursorIdx = line.indexOf(CURSOR_MARKER);
+  if (cursorIdx === -1) return 0;
+
+  const afterMarker = line.slice(cursorIdx + CURSOR_MARKER.length);
+  const inverseEnd = afterMarker.indexOf("\x1b[0m");
+  return cursorIdx + CURSOR_MARKER.length + (inverseEnd >= 0 ? inverseEnd + 4 : 0);
+}
+
+function findCursorMarkerLine(lines: string[]): number {
+  return lines.findIndex((l) => l.includes(CURSOR_MARKER));
+}

package/src/extension.ts

@@ -0,0 +1,26 @@
+/**
+ * supi-prompt-suggestions PI extension entrypoint.
+ *
+ * Registers settings and wires session event handlers to a
+ * {@link SessionLifecycle} instance that owns the ghost editor,
+ * status spinner, and suggestion generator lifecycle.
+ *
+ * @module
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerPromptSuggestionsSettings } from "./config/settings.ts";
+import { SuggestionGenerator } from "./generation/generator.ts";
+import { SessionLifecycle } from "./session.ts";
+
+export default function (pi: ExtensionAPI): void {
+  registerPromptSuggestionsSettings();
+
+  const generator = new SuggestionGenerator();
+  const session = new SessionLifecycle(generator);
+
+  pi.on("session_start", (_event, ctx) => session.onStart(ctx));
+  pi.on("agent_end", (event, ctx) => session.onAgentEnd(event, ctx));
+  pi.on("agent_start", () => session.onAgentStart());
+  pi.on("session_shutdown", () => session.onShutdown());
+}

package/src/generation/client.ts

@@ -0,0 +1,122 @@
+/**
+ * Low-level suggestion model client.
+ *
+ * Pure functions for calling the suggestion model — no module-level state,
+ * no orchestration, no debug logging.
+ *
+ * @module
+ */
+
+import { completeSimple } from "@earendil-works/pi-ai";
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+export const GENERATION_TIMEOUT_MS = 20_000;
+
+/**
+ * System prompt instructs the model to suggest a follow-up user message
+ * (question, answer, or directive) or return the NO_SUGGESTION sentinel
+ * when none is useful.
+ *
+ * The model receives no PI, SuPi, project, or conversation context —
+ * only the last assistant message text is sent.
+ */
+const SYSTEM_PROMPT =
+  "You suggest follow-up messages for a coding assistant conversation. " +
+  "Given the assistant's last message, write a single line the user would type next. " +
+  "It must be a direct question, answer, or directive — nothing else. " +
+  "Do NOT include greetings, thank-yous, politeness, or conversational filler. " +
+  "If there is no useful follow-up, respond with exactly the word NO_SUGGESTION and nothing else. " +
+  "Keep suggestions under 240 characters.";
+
+// ── 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.
+ */
+export function buildPrompt(tail: string): string {
+  return `<assistant_message>\n${tail}\n</assistant_message>\n\nSuggestion:`;
+}
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export interface SuggestionClientResult {
+  ok: true;
+  text: string;
+}
+
+export interface SuggestionClientError {
+  ok: false;
+  message: string;
+}
+
+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?: Record<string, string> };
+  tail: string;
+  signal: AbortSignal;
+}
+
+// ── API call ───────────────────────────────────────────────────────────
+
+/**
+ * Call the suggestion model with a simple completion prompt.
+ *
+ * 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.
+ */
+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,
+      signal,
+    },
+  );
+
+  if (!response?.content) {
+    const message = `Suggestion model returned no content (stopReason: ${response?.stopReason ?? "undefined"})`;
+    return { ok: false, message };
+  }
+
+  if (response.stopReason === "error") {
+    const message = `Suggestion model failed: ${response.errorMessage ?? response.stopReason}`;
+    return { ok: false, message };
+  }
+
+  // Prefer text blocks; fall back to thinking blocks for reasoning-only models.
+  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 (content types: [${contentTypes.join(", ")}])`;
+    return { ok: false, message };
+  }
+
+  return { ok: true, text: textContent };
+}

package/src/generation/generator.ts

@@ -0,0 +1,225 @@
+/**
+ * Suggestion generator — async orchestration of prompt suggestion
+ * generation with concurrency control.
+ *
+ * Manages the lifecycle: config check, model resolution, model call,
+ * normalization, and callback dispatch. Uses an internal abort controller
+ * and generation ID to cancel or discard stale results.
+ *
+ * @module
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { combineAbortSignals } from "@mrclrchtr/supi-core/abort-utils";
+import { loadSectionConfig } from "@mrclrchtr/supi-core/config";
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import { CONFIG_SECTION, DEFAULTS } from "../config/config.ts";
+import {
+  callSuggestionModel,
+  GENERATION_TIMEOUT_MS,
+  type SuggestionClientOutput,
+} from "./client.ts";
+import { resolveSuggestionAuth } from "./model-resolution.ts";
+import { normalizeSuggestion } from "./normalize.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type GenerationStatus =
+  | { kind: "idle" }
+  | { kind: "generating" }
+  | { kind: "ready"; suggestion: string }
+  | { kind: "error"; message: string };
+
+export interface SuggestionCallbacks {
+  /** Called when generation status changes. */
+  onStatus: (status: GenerationStatus) => void;
+}
+
+interface RunOptions {
+  ctx: ExtensionContext;
+  modelId: string;
+  tail: string;
+  id: number;
+  abort: AbortController;
+  callbacks: SuggestionCallbacks;
+}
+
+// ── Generator ──────────────────────────────────────────────────────────────
+
+/**
+ * Encapsulates the async suggestion generation lifecycle.
+ *
+ * Manages concurrency via an internal abort controller and generation ID.
+ * Instances are independent — tests can create fresh instances without
+ * shared mutable state.
+ */
+export class SuggestionGenerator {
+  private currentAbort: AbortController | null = null;
+  private generationId = 0;
+
+  /**
+   * Start suggestion generation from the last assistant text.
+   *
+   * Fire-and-forget — the caller does not await the returned promise.
+   * Cancels any in-flight generation.
+   */
+  start(ctx: ExtensionContext, lastAssistantText: string, callbacks: SuggestionCallbacks): void {
+    // Cancel any in-flight generation
+    this.dismiss();
+
+    const config = loadSectionConfig(CONFIG_SECTION, ctx.cwd, DEFAULTS);
+    if (config.model === "disabled") {
+      recordDebugEvent({
+        source: "prompt-suggestions",
+        level: "debug",
+        category: "generation.skipped",
+        message: "Prompt suggestion generation skipped: model is disabled",
+        cwd: ctx.cwd,
+      });
+      callbacks.onStatus({ kind: "idle" });
+      return;
+    }
+
+    const text = lastAssistantText.trim();
+    if (!text) {
+      recordDebugEvent({
+        source: "prompt-suggestions",
+        level: "debug",
+        category: "generation.skipped",
+        message: "Prompt suggestion generation skipped: no text in last assistant message",
+        cwd: ctx.cwd,
+      });
+      callbacks.onStatus({ kind: "idle" });
+      return;
+    }
+
+    const tail = text.slice(-8_000);
+    const id = ++this.generationId;
+    const abort = new AbortController();
+    this.currentAbort = abort;
+
+    callbacks.onStatus({ kind: "generating" });
+
+    // Fire-and-forget
+    void this.#run({ ctx, modelId: config.model, tail, id, abort, callbacks });
+  }
+
+  /** Cancel in-flight generation and invalidate the current generation ID. */
+  dismiss(): void {
+    if (this.currentAbort) {
+      this.currentAbort.abort();
+      this.currentAbort = null;
+    }
+    this.generationId++;
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────
+
+  async #run(opts: RunOptions): Promise<void> {
+    const { ctx, tail, id, abort, callbacks } = opts;
+
+    recordDebugEvent({
+      source: "prompt-suggestions",
+      level: "debug",
+      category: "generation.start",
+      message: "Prompt suggestion generation started",
+      cwd: ctx.cwd,
+      data: { tailLength: tail.length },
+    });
+
+    try {
+      const authResult = await resolveSuggestionAuth(ctx, opts.modelId);
+
+      // Discard if generation was cancelled while resolving auth
+      if (id !== this.generationId || abort.signal.aborted) return;
+
+      if (authResult.kind === "error") {
+        recordDebugEvent({
+          source: "prompt-suggestions",
+          level: "warning",
+          category: "generation.auth-failure",
+          message: authResult.message,
+          cwd: ctx.cwd,
+        });
+        callbacks.onStatus({ kind: "error", message: authResult.message });
+        return;
+      }
+
+      const { auth } = authResult;
+
+      if (id !== this.generationId || abort.signal.aborted) return;
+
+      const { signal: combinedSignal, cleanup: cleanupTimeout } = combineAbortSignals(
+        abort,
+        GENERATION_TIMEOUT_MS,
+      );
+
+      try {
+        const response = await callSuggestionModel({
+          model: auth.model,
+          auth: { apiKey: auth.apiKey, headers: auth.headers },
+          tail,
+          signal: combinedSignal,
+        });
+
+        this.#handleResponse(response, id, ctx.cwd, callbacks);
+      } finally {
+        cleanupTimeout();
+      }
+    } catch (err) {
+      if (id !== this.generationId) return;
+      const message = err instanceof Error ? err.message : String(err);
+      recordDebugEvent({
+        source: "prompt-suggestions",
+        level: "warning",
+        category: "generation.error",
+        message: `Prompt suggestion generation failed: ${message}`,
+        cwd: ctx.cwd,
+        data: { error: message },
+      });
+      callbacks.onStatus({ kind: "error", message });
+    } finally {
+      if (this.currentAbort === abort) {
+        this.currentAbort = null;
+      }
+    }
+  }
+
+  #handleResponse(
+    response: SuggestionClientOutput,
+    id: number,
+    cwd: string,
+    callbacks: SuggestionCallbacks,
+  ): void {
+    if (id !== this.generationId) return;
+
+    if (!response.ok) {
+      callbacks.onStatus({ kind: "error", message: response.message });
+      return;
+    }
+
+    const normalized = normalizeSuggestion(response.text);
+    if (!normalized) {
+      recordDebugEvent({
+        source: "prompt-suggestions",
+        level: "debug",
+        category: "generation.rejected",
+        message: `Prompt suggestion rejected: empty after normalization (${response.text.length} raw chars)`,
+        cwd,
+        data: { rawLength: response.text.length },
+      });
+      callbacks.onStatus({ kind: "idle" });
+      return;
+    }
+
+    recordDebugEvent({
+      source: "prompt-suggestions",
+      level: "debug",
+      category: "generation.done",
+      message: `Prompt suggestion ready: "${normalized}"`,
+      cwd,
+      data: { suggestion: normalized, length: normalized.length },
+    });
+    callbacks.onStatus({ kind: "ready", suggestion: normalized });
+  }
+}

package/src/generation/model-resolution.ts

@@ -0,0 +1,72 @@
+/**
+ * Suggestion model resolution.
+ *
+ * Resolves the configured suggestion model from the scoped model set
+ * and obtains its API key.  Extracted from {@link SuggestionGenerator}
+ * for isolated testing.
+ *
+ * @module
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSelectableModels } from "@mrclrchtr/supi-core/model-selection";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface ResolvedAuth {
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+  model: any;
+  apiKey: string;
+  headers?: Record<string, string>;
+}
+
+export interface AuthResolutionError {
+  kind: "error";
+  message: string;
+}
+
+export type AuthResolutionResult = { kind: "ok"; auth: ResolvedAuth } | AuthResolutionError;
+
+// ── Resolution ─────────────────────────────────────────────────────────────
+
+/**
+ * Resolve model + API key for the configured suggestion model.
+ *
+ * Finds the model in the scoped set and obtains an API key via
+ * `modelRegistry.getApiKeyAndHeaders`.
+ *
+ * The caller must check for `"disabled"` before invoking — this function
+ * assumes a valid, non-disabled model ID.
+ */
+export async function resolveSuggestionAuth(
+  ctx: ExtensionContext,
+  modelId: string,
+): Promise<AuthResolutionResult> {
+  const match = findSuggestionModel(ctx, modelId);
+  if (!match) {
+    return {
+      kind: "error",
+      message: `Suggestion model "${modelId}" not in scoped set`,
+    };
+  }
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(match.model);
+  if (!auth.ok) {
+    return {
+      kind: "error",
+      message: `No API key configured for ${match.canonicalId}`,
+    };
+  }
+
+  return {
+    kind: "ok",
+    auth: { model: match.model, apiKey: auth.apiKey ?? "", headers: auth.headers },
+  };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function findSuggestionModel(ctx: ExtensionContext, modelId: string) {
+  const models = getSelectableModels(ctx);
+  return models.find((m) => m.canonicalId === modelId);
+}