pi-ghost-autocomplete 0.3.1 → 0.4.0

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

@@ -1,5 +1,10 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { OpenAICompatProviderConfig } from "../config.js";
-import type { GhostProvider, GhostRequest } from "./types.js";
+import type { CandidateSet, GhostProvider, GhostRequest } from "./types.js";
+import { type PromptIntent } from "../intent.js";
 export interface PreflightResult {
     ok: boolean;
     status?: number;
@@ -25,5 +30,33 @@ export declare class OpenAICompatProvider implements GhostProvider {
      */
     preflight(): Promise<PreflightResult>;
     predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * Multi-candidate prediction. Fires `config.parallelN` FIM requests in
+     * parallel and dedupes by exact text. PRD §M3b: FIM does not support
+     * the `n` parameter, so parallel POSTs are the only n>1 path. Parallel
+     * fire is only useful at temperature > 0 — at temp=0 every call returns
+     * the same greedy result. We downgrade silently to n=1 in that case.
+     */
+    predictMulti(req: GhostRequest): Promise<CandidateSet | null>;
+    private effectiveParallelN;
+    private fireOne;
 }
-//# sourceMappingURL=openai-compat-provider.d.ts.map
+/**
+ * Whether the conversation context should be included in the FIM prompt for a
+ * given intent. Pure + exported for direct testing. Set
+ * `PI_GHOST_FIM_CONTEXT_ALL_INTENTS=1` to force-include context for every
+ * intent (A/B against the empty-rate fix).
+ */
+export declare function fimContextIncluded(intent: PromptIntent | undefined, allIntentsRaw: string | undefined): boolean;
+/**
+ * Build the FIM prompt/suffix pair from the ghost request.
+ *
+ * Recent conversation messages are prepended as comments in the prompt so the
+ * model has context about what the user is working on — except for `prose` /
+ * `question` intents, where the context is dropped to avoid the empty-rate
+ * spike described on {@link FIM_CONTEXT_SUPPRESSED_INTENTS}.
+ */
+export declare function buildFIMPrompt(req: GhostRequest, maxRecent: number): {
+    prompt: string;
+    suffix: string;
+};

package/dist/providers/race.d.ts

@@ -1,5 +1,9 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { ProviderLatency } from "../metrics.js";
-import type { GhostProvider, GhostRequest } from "./types.js";
+import { type GhostProvider, type GhostRequest, type StreamDelta } from "./types.js";
 export interface RaceConfig {
     /** Pause/debounce before race starts. Reported as `debounceMs`. */
     pauseMs: number;
@@ -11,6 +15,8 @@ export interface RaceConfig {
 export interface RaceTrace {
     providers: ProviderLatency[];
     winner?: string;
+    /** Members that the weighting policy declined to fire (PRD §M8). */
+    skipped?: string[];
 }
 /**
  * Implements {@link GhostProvider} by racing several providers in parallel.
@@ -26,10 +32,65 @@ export declare class RaceProvider implements GhostProvider {
     readonly name: string;
     private cooldownUntil;
     private lastTrace;
+    private readonly stats;
     constructor(members: GhostProvider[], cfg: RaceConfig);
+    /** Snapshot of per-member weighting stats. Test/diagnostic only. */
+    getMemberStats(): Array<{
+        name: string;
+        slowCount: number;
+        wins: number;
+        skipRemaining: number;
+    }>;
     get debounceMs(): number;
     consumeLastTrace(): RaceTrace | null;
+    /**
+     * Cooldown snapshot for speculative cache warm. The editor consults this
+     * synchronously in `handleTextChange` to decide whether the backspace-of-N
+     * branch may serve a result (it is the most aggressive branch and is only
+     * appropriate when a fresh race would no-op anyway). See PRD §6 M1b.
+     */
+    getCooldownState(now?: number): {
+        active: boolean;
+        remainingMs: number;
+    };
     predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * After a race resolves, update per-member rolling stats and decide who
+     * gets a skip penalty for the next `SKIP_RACES`. A member earns "slow"
+     * if it ran but didn't win this race (when there was a winner).
+     *
+     * `userAborted` distinguishes user-keystroke cancellation from
+     * race-cancellation-by-winner. Member's trace result is "aborted" in
+     * both cases; we only penalize the latter (the member could have run
+     * to completion but lost the race). User keystrokes shouldn't drift
+     * the weighting at all.
+     */
+    private recordRaceOutcome;
+    /**
+     * PRD §M3.5a — streaming variant of `predict`. Each member runs its own
+     * stream under a dedicated AbortController; first member to emit a
+     * non-empty delta wins. Losing members are aborted and their iterators
+     * released. The winner's remaining chunks pass through untouched.
+     *
+     * Trace + stats are recorded identically to `predict()` so M8 weighting
+     * works the same way: winner = first to first-chunk; losers that also
+     * produced are still marked `produced` (they did emit), losers aborted
+     * before producing are `aborted`.
+     */
+    predictStream(req: GhostRequest): AsyncIterable<StreamDelta>;
+    /**
+     * Pump a member's stream until its first non-empty delta. Resolves to
+     * the parked iterator + that delta when produced; null on
+     * empty/aborted/error. Trace is appended for terminal outcomes; the
+     * `produced` entry is pushed once the first non-empty delta arrives so
+     * its latency reflects TTFT, not end-of-stream.
+     */
+    private firstChunkOf;
+    /**
+     * Reset all rolling stats (PRD §M8: "Reset state on `setProvider` /
+     * extension reload"). Public for editor reset paths.
+     */
+    resetStats(): void;
     private runMember;
 }
 /**
@@ -37,4 +98,3 @@ export declare class RaceProvider implements GhostProvider {
  * all promises produce null (or throw). Never rejects.
  */
 export declare function firstNonNull<T>(promises: Array<Promise<T | null>>): Promise<T | null>;
-//# sourceMappingURL=race.d.ts.map

package/dist/providers/types.d.ts

@@ -1,18 +1,125 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { PreflightResult } from "./openai-compat-provider.js";
+import type { PromptIntent } from "../intent.js";
 export interface GhostRequest {
     editorText: string;
     editorTextBeforeCursor: string;
+    /**
+     * Recent conversation messages, oldest-first. `role: "tool"` entries
+     * may carry a `toolName` for richer prompt formatting (PRD §M6a). The
+     * editor only surfaces tool entries when `includeTools` is enabled in
+     * `context-aggregator.getRecentMessages`.
+     */
     recentMessages: Array<{
-        role: "user" | "assistant";
+        role: "user" | "assistant" | "tool";
         text: string;
+        toolName?: string;
     }>;
     cwd: string;
     signal: AbortSignal;
+    /**
+     * Classified intent of the current prompt line. When set, providers use
+     * it to tailor the system prompt / FIM prompt so the model receives
+     * explicit signals about what kind of completion to produce.
+     * Undefined for backward compatibility (providers built before intent
+     * classification was added).
+     */
+    intent?: PromptIntent;
+}
+/**
+ * One candidate completion. `avgLogprob` is the average per-token logprob if
+ * the provider returned them; undefined when not supported. Reranker treats
+ * missing logprobs as the neutral mid-value (0.5 after normalization) per
+ * PRD §M3c.
+ */
+export interface GhostCandidate {
+    text: string;
+    avgLogprob?: number;
+}
+/**
+ * Result of a multi-candidate prediction. `candidates` is ordered as the
+ * provider returned them (no rerank applied yet). Single-candidate providers
+ * return a single-element array.
+ */
+export interface CandidateSet {
+    candidates: GhostCandidate[];
+}
+/**
+ * One streaming delta from a provider. PRD §M3.5a — captures both the
+ * incremental piece (`delta`) and the running concatenation (`cumulative`)
+ * so consumers don't have to track state. `firstChunk` flags the very
+ * first non-empty delta, which is what the editor stamps as `ttftMs`.
+ */
+export interface StreamDelta {
+    delta: string;
+    cumulative: string;
+    firstChunk: boolean;
 }
 export interface GhostProvider {
     readonly name: string;
     readonly debounceMs: number;
     predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * Optional multi-candidate variant. When absent the editor wraps
+     * `predict()` via `wrapAsMulti`. See PRD §M3a.
+     */
+    predictMulti?(req: GhostRequest): Promise<CandidateSet | null>;
+    /**
+     * Optional streaming variant. When present the editor uses it on
+     * single-candidate paths to capture `ttftMs` and (in a follow-up
+     * iteration) drive incremental UI rendering. Providers that don't
+     * stream (e.g. Mercury Edit FIM) omit this method.
+     */
+    predictStream?(req: GhostRequest): AsyncIterable<StreamDelta>;
     preflight?(): Promise<boolean | PreflightResult>;
+    /**
+     * PRD §M3g / §M7 capability flag — true iff the provider populates
+     * per-token logprob values on streamed `StreamDelta` events (M7
+     * entropy-stop input). `StreamDelta` will be extended in a future
+     * change to include per-token logprob data. No provider currently sets
+     * this since `@earendil-works/pi-ai` does not surface logprobs; left in
+     * place so M7 wiring can flip on once upstream support lands without
+     * changing the diagnostics surface. Wording aligns with
+     * `GhostCandidate.avgLogprob`.
+     */
+    readonly supportsLogprobs?: boolean;
 }
-//# sourceMappingURL=types.d.ts.map
+/**
+ * Adapt a `predict()`-only provider into the `CandidateSet | null` shape.
+ * Used by the editor to give every provider a uniform multi-candidate
+ * surface without forcing third-party implementations to upgrade.
+ *
+ * Wrapped candidates intentionally have `avgLogprob: undefined` — the
+ * `predict()` signature returns only text, so logprobs aren't recoverable.
+ * The reranker normalizes missing logprobs to the neutral mid-value (0.5)
+ * per PRD §M3c, so single-candidate wrappers aren't penalized against
+ * providers that do return logprobs.
+ */
+export declare function wrapAsMulti(provider: GhostProvider, req: GhostRequest): Promise<CandidateSet | null>;
+/**
+ * Adapt any provider to the streaming surface. Providers with
+ * `predictStream` pass through unchanged; non-streaming providers get a
+ * single-delta stream emitted after `predict()` resolves. `firstChunk`
+ * is true on the only emission in the non-streaming case.
+ *
+ * Yields nothing when the provider returns null/empty. Consumer code
+ * pattern:
+ *
+ * ```ts
+ * let full = "";
+ * for await (const { cumulative } of wrapAsStream(p, req)) full = cumulative;
+ * ```
+ */
+export declare function wrapAsStream(provider: GhostProvider, req: GhostRequest): AsyncIterable<StreamDelta>;
+/**
+ * Drain a stream into its final cumulative text. Records the timestamp
+ * of the first non-empty chunk on `out.ttftMs` (relative to `startedAt`)
+ * for the caller. The result is the full assembled text, or null if the
+ * stream produced no content.
+ */
+export declare function streamToText(stream: AsyncIterable<StreamDelta>, startedAt: number, out?: {
+    ttftMs?: number;
+}): Promise<string | null>;

package/dist/recent-paths.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type RecentMessage } from "./context-aggregator.js";
 /**
@@ -22,4 +26,3 @@ export declare function recentBoost(matchPath: string, recent: Set<string> | nul
  * assistant messages. Oldest-first.
  */
 export declare function getRoleWeightedRecent(ctx: ExtensionContext, userMax: number, assistantMax: number): RecentMessage[];
-//# sourceMappingURL=recent-paths.d.ts.map