pi-ghost-autocomplete 0.5.0 → 0.6.0

package/dist/metrics.d.ts

@@ -7,12 +7,30 @@
  * and the parser whitelist (runtime, in `bench.ts`) derive from this array so
  * adding a mode means updating one place.
  */
-export declare const COMPLETION_MODES: readonly ["deterministic", "llm", "cache", "trie", "speculative-warm", "provisional", "profile-slash"];
+export declare const COMPLETION_MODES: readonly ["deterministic", "llm", "cache", "trie", "speculative-warm", "provisional", "profile-slash", "command-slash"];
 export type CompletionMode = (typeof COMPLETION_MODES)[number];
 export type RequestResult = "produced" | "empty" | "rejected" | "aborted" | "error";
 export type AcceptanceOutcome = "accepted" | "accepted-partial" | "dismissed" | "stale" | "expired";
 export type QualityAttribution = "accepted" | "dismissed-attributed" | "unknown";
 export type RejectionReason = "stale-text" | "newline" | "too-long" | "assistant-phrasing" | "duplicate-suffix" | "markdown" | "empty" | "echo-token";
+/**
+ * Diagnosed cause of an `empty` LLM verdict (session-51 todo #4). Without this
+ * the metrics can't distinguish a model that returned a bare newline from one
+ * whose output the sanitizer dropped, or a request that never reached the
+ * backend — that distinction previously needed synthetic probing.
+ *
+ *  - `model-empty`   — the model returned empty/whitespace-only text (the
+ *                      Mercury Edit "nothing to insert" case from session 51).
+ *  - `sanitizer-null`— the model returned content but `sanitizeCompletion`
+ *                      rejected it (echo / filename-in-prose / markdown).
+ *  - `http-error`    — the request failed: missing key, non-2xx, malformed
+ *                      JSON, fetch throw, or timeout.
+ *
+ * Only set by providers that implement `consumeLastEmptyReason()`. Records from
+ * providers that don't (or that predate this field) omit it — bench buckets
+ * those as `unattributed`.
+ */
+export type EmptyReason = "model-empty" | "sanitizer-null" | "http-error";
 export interface ProviderLatency {
     provider: string;
     latencyMs: number;
@@ -27,6 +45,8 @@ export interface MetricsRecord {
     winner?: string;
     result: RequestResult;
     rejectionReason?: RejectionReason;
+    /** When `result === "empty"`, the diagnosed cause (session-51 todo #4). */
+    emptyReason?: EmptyReason;
     completionLength?: number;
     shown?: boolean;
     acceptance?: AcceptanceOutcome;

package/dist/providers/openai-compat-chat-provider.d.ts

@@ -4,7 +4,8 @@
  */
 import type { OpenAICompatChatProviderConfig } from "../config.js";
 import type { PreflightResult } from "./openai-compat-provider.js";
-import type { GhostProvider, GhostRequest } from "./types.js";
+import { type GhostProvider, type GhostRequest } from "./types.js";
+import type { EmptyReason } from "../metrics.js";
 /**
  * Chat-register provider for OpenAI-compatible `/chat/completions` backends
  * (e.g. Inception Mercury's conversational model). Sibling of
@@ -20,8 +21,12 @@ import type { GhostProvider, GhostRequest } from "./types.js";
 export declare class OpenAICompatChatProvider implements GhostProvider {
     private readonly config;
     readonly name: string;
+    /** Why the most recent `predict` resolved empty; consumed by the editor. */
+    private lastEmptyReason;
     constructor(config: OpenAICompatChatProviderConfig);
     get debounceMs(): number;
+    /** Return + clear the cause of the last empty completion (session-51 #4). */
+    consumeLastEmptyReason(): EmptyReason | null;
     /**
      * Validate the API key with a minimal chat request. A successful response
      * (even an empty completion) proves auth + connectivity.

package/dist/providers/openai-compat-provider.d.ts

@@ -3,7 +3,8 @@
  * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
  */
 import type { OpenAICompatProviderConfig } from "../config.js";
-import type { CandidateSet, GhostProvider, GhostRequest } from "./types.js";
+import { type CandidateSet, type GhostProvider, type GhostRequest } from "./types.js";
+import type { EmptyReason } from "../metrics.js";
 import { type PromptIntent } from "../intent.js";
 export interface PreflightResult {
     ok: boolean;
@@ -22,8 +23,17 @@ export interface PreflightResult {
 export declare class OpenAICompatProvider implements GhostProvider {
     private readonly config;
     readonly name: string;
+    /** Why the most recent `fireOne` resolved empty; consumed by the editor. */
+    private lastEmptyReason;
     constructor(config: OpenAICompatProviderConfig);
     get debounceMs(): number;
+    /**
+     * Return + clear the cause of the last empty completion (session-51 todo
+     * #4). With `parallelN > 1` this reflects the last FIM call to resolve;
+     * since the editor only consumes it when the whole candidate set is empty,
+     * every parallel call was empty and the reasons are typically identical.
+     */
+    consumeLastEmptyReason(): EmptyReason | null;
     /**
      * Validate the API key with a minimal FIM request. A successful
      * response (even an empty completion) proves auth + connectivity.

package/dist/providers/router.d.ts

@@ -20,6 +20,7 @@
  * reachable chat backend never regresses.
  */
 import type { PromptIntent } from "../intent.js";
+import type { EmptyReason } from "../metrics.js";
 import type { PreflightResult } from "./openai-compat-provider.js";
 import { type CandidateSet, type GhostProvider, type GhostRequest } from "./types.js";
 /** Pure routing predicate — exported for direct testing. */
@@ -28,6 +29,9 @@ export declare class RouterProvider implements GhostProvider {
     private readonly fim;
     private readonly chat;
     readonly name = "ghost-router";
+    /** Leg that served the most recent request — the one to query for the
+     *  empty-cause diagnostic so it reflects the register that actually ran. */
+    private lastLeg;
     constructor(fim: GhostProvider, chat: GhostProvider | null);
     get debounceMs(): number;
     /**
@@ -38,8 +42,12 @@ export declare class RouterProvider implements GhostProvider {
      */
     legFor(intent: PromptIntent | undefined): "fim" | "chat";
     /** Choose the leg for this request. Chat leg only when present AND the
-     *  intent is natural-language; otherwise FIM. */
+     *  intent is natural-language; otherwise FIM. Records the choice so
+     *  `consumeLastEmptyReason` can forward to the leg that actually ran. */
     private leg;
+    /** Forward the empty-cause diagnostic to whichever leg last served a
+     *  request. Null when no request has run yet or the leg doesn't track it. */
+    consumeLastEmptyReason(): EmptyReason | null;
     predict(req: GhostRequest): Promise<string | null>;
     /**
      * Route, then adapt the chosen leg to the multi-candidate surface. The

package/dist/providers/types.d.ts

@@ -4,6 +4,7 @@
  */
 import type { PreflightResult } from "./openai-compat-provider.js";
 import type { PromptIntent } from "../intent.js";
+import type { EmptyReason } from "../metrics.js";
 export interface GhostRequest {
     editorText: string;
     editorTextBeforeCursor: string;
@@ -75,6 +76,16 @@ export interface GhostProvider {
      */
     predictStream?(req: GhostRequest): AsyncIterable<StreamDelta>;
     preflight?(): Promise<boolean | PreflightResult>;
+    /**
+     * Optional empty-cause diagnostic (session-51 todo #4). When the provider's
+     * last `predict`/`predictMulti` resolved to null/empty, returns *why*
+     * (`model-empty` / `sanitizer-null` / `http-error`) and clears it; returns
+     * null otherwise. The editor reads this only when it's about to log an
+     * `empty` result, so the value reflects the just-resolved request. Providers
+     * that don't implement it leave the metric's `emptyReason` unset
+     * (bench buckets those as `unattributed`).
+     */
+    consumeLastEmptyReason?(): EmptyReason | null;
     /**
      * PRD §M3g / §M7 capability flag — true iff the provider populates
      * per-token logprob values on streamed `StreamDelta` events (M7
@@ -87,6 +98,14 @@ export interface GhostProvider {
      */
     readonly supportsLogprobs?: boolean;
 }
+/**
+ * Classify an empty completion from the raw model text. Shared by providers
+ * that run text through `sanitizeCompletion`: a whitespace-only raw response is
+ * the model declining to insert (`model-empty`); non-empty raw that sanitized
+ * to null/empty was dropped by the sanitizer (`sanitizer-null`). HTTP/transport
+ * failures are classified `http-error` at the call site, not here.
+ */
+export declare function classifyEmpty(rawModelText: string): "model-empty" | "sanitizer-null";
 /**
  * Adapt a `predict()`-only provider into the `CandidateSet | null` shape.
  * Used by the editor to give every provider a uniform multi-candidate