pi-ghost-autocomplete 0.3.2 → 0.5.0

package/dist/intent.d.ts

@@ -0,0 +1,179 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+/**
+ * Intent detection for ghost autocompletion.
+ *
+ * Centralises all prose / path / filename heuristics so they can be shared
+ * between the deterministic fast-path engine and the LLM provider layer
+ * without circular dependencies.
+ *
+ * This module is the single source of truth for:
+ * - `PromptIntent`           — discriminated union for intent classification
+ * - `classifyPromptIntent()`  — regex-based intent classifier
+ * - `ACTION_VERBS`            — canonical action-verb list (used by isPathContext,
+ *                              draftLooksLikePathContext, and fuzzy-matcher)
+ * - `looksLikeProse()`        — single-line prose detection
+ * - `looksLikeProseContext()`  — multi-line prose detection
+ * - `isPathContext()`         — path-prefix context validation
+ * - `looksLikeFilename()`     — completion output shape detection
+ * - `draftLooksLikePathContext()` — draft context shape detection
+ *
+ * Consumers import from here; legacy re-exports live in `fast-path-engine.ts`
+ * and `providers/truncate.ts` for backward compatibility with existing tests.
+ */
+/**
+ * Coarse-grained intent of the current prompt line. Used to route the
+ * autocompletion pipeline:
+ *
+ * - `command`   — shell-like command (starts with `/`, `$`, `!`, `@`)
+ *                → deterministic + LLM
+ * - `question`  — user asks a question (starts with how/what/why/...)
+ *                → LLM only (skip deterministic)
+ * - `instruction` — imperative sentence (starts with a verb)
+ *                  → deterministic + LLM
+ * - `path-ref`  — user is typing a file path or referencing files
+ *                → deterministic only
+ * - `prose`     — natural-language sentence (none of the above)
+ *                → LLM only (skip deterministic)
+ */
+export type PromptIntent = "command" | "question" | "instruction" | "path-ref" | "prose";
+/**
+ * Action verbs that strongly signal the user is about to reference a file
+ * path. Used by `isPathContext`, `draftLooksLikePathContext`, and the
+ * fuzzy matcher's `hasActionTrigger` gate.
+ *
+ * Single canonical source — do NOT duplicate elsewhere.
+ * Covers: file manipulation (open/edit/read/write/save), navigation (cd/ls),
+ * search (find/check/look), shell commands (cat/less/head/tail/touch/mkdir/
+ * rm/cp/mv), loading (load/import/include), and general (show/view/see/run/add).
+ */
+export declare const ACTION_VERBS: Set<string>;
+/** Alternation group for use in regex character classes.  Kept in sync
+ *  with `ACTION_VERBS` — rebuild with `[...ACTION_VERBS].join("|")`.
+ *  Exported so consumers (fast-path-engine, etc.) can build verb-aware
+ *  regexes without duplicating the list. */
+export declare const ACTION_VERBS_ALT: string;
+/**
+ * Heuristic: does the text before the cursor look like natural-language prose
+ * rather than a command / path context? Returns true when there are 4+ word
+ * tokens (\w{2,}) — a strong signal the user is writing a sentence, not a
+ * filename.
+ *
+ * This prevents the fuzzy matcher from proposing `config.ts` when the user
+ * types "please add a con|" ("con" fuzzy-matches config.ts at score ~75).
+ */
+export declare function looksLikeProse(lineBeforeCursor: string): boolean;
+/** Reason a multi-line prose context fired. Used for observability so
+ *  callers can log *why* the deterministic path was suppressed. */
+export type ProseContextReason = "density" | "cohesion" | "punctuation";
+/** Detailed result of multi-line prose detection. `reason` is set iff
+ *  `isProse` is true, naming the rule that triggered. */
+export interface ProseContextResult {
+    isProse: boolean;
+    reason?: ProseContextReason;
+}
+/**
+ * Heuristic: do the surrounding lines indicate a prose context (the user
+ * is writing natural-language text across multiple lines)? Returns the
+ * verdict together with the matching reason for observability.
+ *
+ * Rules (first match wins):
+ *
+ * 1. **High word density**: the previous lines contain 8+ word tokens total
+ *    (\w{2,}) — strong signal of paragraph-level prose.
+ * 2. **Lexical cohesion**: the previous lines share ≥2 word tokens with the
+ *    current line — inspired by Hearst's TextTiling algorithm for
+ *    detecting topic continuity.
+ * 3. **Sentence punctuation**: the previous non-empty line ends with a
+ *    period or comma AND carries at least PUNCTUATION_MIN_PREV_TOKENS
+ *    alpha word tokens. The token-count guard kills shell one-liners
+ *    like `echo hello,` that would otherwise be misrouted.
+ *    Semicolons are excluded (common in code).
+ */
+export declare function classifyProseContext(previousLines: string[], currentLineBeforeCursor: string): ProseContextResult;
+/**
+ * Boolean wrapper kept for back-compat with existing tests / call sites
+ * that don't need the reason. Prefer `classifyProseContext` when the
+ * caller wants to log why prose mode triggered.
+ *
+ * @param previousLines — lines before the current line
+ * @param currentLineBeforeCursor — text on the current line before the cursor
+ */
+export declare function looksLikeProseContext(previousLines: string[], currentLineBeforeCursor: string): boolean;
+/**
+ * Heuristic: is the path-prefix token in a context that suggests the user
+ * intends to type a filename? Returns true when:
+ * - The token is inside quotes
+ * - The token is preceded by an action verb + whitespace ("read src/|")
+ * - The token starts at column 0 or after only whitespace
+ * - The preceding character is a non-letter boundary (`=`, `:`, `,`, etc.)
+ *
+ * Returns false when the token is embedded in prose (e.g. "and then src/|").
+ */
+export declare function isPathContext(lineBeforeCursor: string, _token: {
+    token: string;
+    insideQuote: boolean;
+}): boolean;
+/**
+ * Short human-readable description for each intent, suitable for injection
+ * into LLM system prompts or FIM comment headers. Single canonical source —
+ * both chat-style (`truncate.ts`) and FIM (`openai-compat-provider.ts`)
+ * providers use these so the wording stays consistent.
+ */
+export declare const INTENT_DESCRIPTION: Record<PromptIntent, string>;
+/**
+ * Classify the user's current prompt intent. Uses simple regex / keyword
+ * heuristics to decide which completion pipeline to activate.
+ *
+ * The classifier examines only the current line before the cursor (fast)
+ * plus optional previous lines for multi-line prose detection.
+ *
+ * Returns one of: `command`, `question`, `instruction`, `path-ref`, `prose`.
+ *
+ * Classification order (first match wins):
+ * 1. `command`   — line starts with `/`, `!`, `$`, `@`
+ * 2. `path-ref`  — line ends with a path-like prefix (contains `/`) or is
+ *                  inside quotes after an action verb
+ * 3. `question`  — line starts with a question word (how/what/why/...)
+ * 4. `instruction` — line starts with an action verb
+ * 5. `prose`     — multi-line prose context detected, or single-line prose
+ *                  (4+ word tokens)
+ */
+export declare function classifyPromptIntent(lineBeforeCursor: string, previousLines?: string[]): PromptIntent;
+/** Reason a prompt was classified as prose. `single-line` corresponds to
+ *  `looksLikeProse` (4+ word tokens on the current line); the others
+ *  mirror `ProseContextReason`. */
+export type ProseReason = ProseContextReason | "single-line";
+/** Detailed intent classification including the prose-rule reason when
+ *  applicable. Lets the editor log *why* the deterministic path was
+ *  suppressed without re-running the heuristic. */
+export interface IntentClassification {
+    intent: PromptIntent;
+    proseReason?: ProseReason;
+}
+/**
+ * Detailed variant of `classifyPromptIntent`. Same classification order,
+ * but returns the prose-rule reason when intent === "prose" so callers
+ * can emit observability records.
+ */
+export declare function classifyPromptIntentDetailed(lineBeforeCursor: string, previousLines?: string[]): IntentClassification;
+/**
+ * Heuristic: does the completion text look like a raw filename or path?
+ * Matches patterns like "src/foo/bar.ts", "config.json", "./path/to/file",
+ * and extensions like .ts, .js, .py, .json, .md, etc.
+ *
+ * Intentionally conservative: requires at least a 2-char extension with
+ * no trailing dot, and rejects common false positives like "hello.there"
+ * by requiring the extension part to look like a real file extension
+ * (starts with a letter, contains only letters/digits).
+ */
+export declare function looksLikeFilename(text: string): boolean;
+/**
+ * Heuristic: does the user's draft text look like they're in a path-typing
+ * context? Returns true when the draft ends with a path-like prefix
+ * (contains `/`, optionally preceded by `./` or `~/`) or when the last
+ * few words include an action verb ("read", "open", "edit", etc.).
+ */
+export declare function draftLooksLikePathContext(draft: string): boolean;

package/dist/metrics.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 /**
  * Source of truth for all completion modes. Both the type union (compile-time)
  * and the parser whitelist (runtime, in `bench.ts`) derive from this array so
@@ -150,4 +154,3 @@ export declare class MetricsLogger {
  * sees that *something* was there, without leaking content. SEC-27.
  */
 export declare function redactDebug(rec: DebugRecord): DebugRecord;
-//# sourceMappingURL=metrics.d.ts.map

package/dist/path-index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 export interface PathIndexOptions {
     cap?: number;
     signal?: AbortSignal;
@@ -17,4 +21,3 @@ export interface PathIndex {
  * path completion this session".
  */
 export declare function buildPathIndex(cwd: string, opts?: PathIndexOptions): Promise<PathIndex | null>;
-//# sourceMappingURL=path-index.d.ts.map

package/dist/path-matcher.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { PathIndex } from "./path-index.js";
 export interface PathToken {
     token: string;
@@ -38,4 +42,3 @@ export declare function extractPathPrefixToken(before: string): PathToken | null
  * (nothing to insert).
  */
 export declare function findPathPrefix(index: PathIndex, token: string, opts?: FindPathPrefixOptions | number): PathPrefixMatch | null;
-//# sourceMappingURL=path-matcher.d.ts.map

package/dist/profile-store.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 /**
  * Stateful wrapper around `profile.ts` for the editor. Holds the in-memory
  * `ProfileIndex`, serializes writes, triggers periodic compaction, and
@@ -79,4 +83,3 @@ export declare class ProfileStore {
 }
 /** Exported for tests — surface compactor knob without re-exporting `profile.ts`. */
 export { DEFAULT_DECAY_DAYS };
-//# sourceMappingURL=profile-store.d.ts.map

package/dist/profile.d.ts

@@ -1,23 +1,6 @@
 /**
- * User profile — long-lived, cross-session frequency store. PRD §M4.
- *
- * Storage: `.pi/ghost-autocomplete/profile.jsonl` (append-only). One JSON
- * record per line, written via the in-process writer.
- *
- * The profile feeds three local-only signals:
- *  - ngram trigrams → reranker `profileBias` (PRD §M3c hook)
- *  - path frequency → bounded boost to deterministic path/fuzzy ranking
- *  - slash-command frequency → editor fast-path for `/cmd…` prefixes
- *
- * Privacy: raw full prefixes and full completions are NEVER persisted. We
- * store sanitized n-grams (≤4), absolute paths, slash commands, and SHA-256
- * hashes of prefix keys (`prefixHash`) for exact-prefix lookup without
- * writing prompt text. The sanitizer is shared with `trie-sanitize.ts` so
- * the entropy + key-prefix rules drop the same tokens.
- *
- * The on-disk format is intentionally append-only + line-delimited so a
- * crash mid-write never corrupts the existing index; partial trailing lines
- * are skipped on load. Rotation compacts when the file exceeds 2 MB.
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
  */
 export declare const PROFILE_REL = ".pi/ghost-autocomplete/profile.jsonl";
 export declare const DEFAULT_MAX_BYTES: number;
@@ -182,4 +165,3 @@ export declare function compactRecords(records: ProfileRecord[], opts?: {
 }): ProfileRecord[];
 /** Parse `PI_GHOST_PROFILE_DECAY_DAYS`. Falls back to default when invalid. */
 export declare function parseDecayDaysEnv(raw: string | undefined): number;
-//# sourceMappingURL=profile.d.ts.map

package/dist/providers/cloud-provider.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { CloudProviderConfig } from "../config.js";
 import type { GhostProvider, GhostRequest, StreamDelta } from "./types.js";
 export declare class CloudProvider implements GhostProvider {
@@ -16,4 +20,3 @@ export declare class CloudProvider implements GhostProvider {
      */
     predictStream(req: GhostRequest): AsyncIterable<StreamDelta>;
 }
-//# sourceMappingURL=cloud-provider.d.ts.map

package/dist/providers/local-provider.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { LocalProviderConfig } from "../config.js";
 import type { GhostProvider, GhostRequest, StreamDelta } from "./types.js";
 export declare class LocalProvider implements GhostProvider {
@@ -15,4 +19,3 @@ export declare class LocalProvider implements GhostProvider {
     predictStream(req: GhostRequest): AsyncIterable<StreamDelta>;
     private callOpts;
 }
-//# sourceMappingURL=local-provider.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+import type { OpenAICompatChatProviderConfig } from "../config.js";
+import type { PreflightResult } from "./openai-compat-provider.js";
+import type { GhostProvider, GhostRequest } from "./types.js";
+/**
+ * Chat-register provider for OpenAI-compatible `/chat/completions` backends
+ * (e.g. Inception Mercury's conversational model). Sibling of
+ * {@link OpenAICompatProvider}, which uses `/fim/completions` for code.
+ *
+ * This is the natural-language leg of {@link RouterProvider}: instead of
+ * completing code, it completes the developer's *message to the AI coding
+ * agent*. The persona that frames the model — "continue the developer's
+ * request, don't perform the task" — lives in {@link buildPromptMessages}'s
+ * system prompt, shared with the cloud/local chat providers so the wording
+ * can't drift across backends.
+ */
+export declare class OpenAICompatChatProvider implements GhostProvider {
+    private readonly config;
+    readonly name: string;
+    constructor(config: OpenAICompatChatProviderConfig);
+    get debounceMs(): number;
+    /**
+     * Validate the API key with a minimal chat request. A successful response
+     * (even an empty completion) proves auth + connectivity.
+     */
+    preflight(): Promise<PreflightResult>;
+    predict(req: GhostRequest): Promise<string | null>;
+}

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 { CandidateSet, GhostProvider, GhostRequest } from "./types.js";
+import { type PromptIntent } from "../intent.js";
 export interface PreflightResult {
     ok: boolean;
     status?: number;
@@ -36,4 +41,22 @@ export declare class OpenAICompatProvider implements GhostProvider {
     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,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { ProviderLatency } from "../metrics.js";
 import { type GhostProvider, type GhostRequest, type StreamDelta } from "./types.js";
 export interface RaceConfig {
@@ -94,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/router.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+/**
+ * Register-routing provider (PRD §M3h). Holds two legs and dispatches each
+ * request to the one whose *register* fits the user's intent:
+ *
+ *  - **FIM leg** (code register) — `command`, `path-ref`, and unclassified
+ *    requests. A code fill-in-the-middle model (Mercury Edit) completes
+ *    commands, paths, and code-shaped drafts.
+ *  - **chat leg** (instruction register) — `instruction`, `question`, `prose`.
+ *    A conversational model completes the developer's *message to the AI coding
+ *    agent* (their request/instruction), instead of writing the solution. This
+ *    is the fix for "the autocomplete keeps suggesting solutions": a code-FIM
+ *    model, fed a natural-language prompt, completes it like code.
+ *
+ * When `chat` is null the router degrades to FIM-only — byte-for-byte the
+ * default behavior before routing existed, so enabling router mode without a
+ * reachable chat backend never regresses.
+ */
+import type { PromptIntent } from "../intent.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. */
+export declare function routeToChat(intent: PromptIntent | undefined): boolean;
+export declare class RouterProvider implements GhostProvider {
+    private readonly fim;
+    private readonly chat;
+    readonly name = "ghost-router";
+    constructor(fim: GhostProvider, chat: GhostProvider | null);
+    get debounceMs(): number;
+    /**
+     * Which leg an intent resolves to — `"chat"` only when a chat leg is
+     * present AND the intent is natural-language; otherwise `"fim"` (including
+     * the chat-absent fallback). Pure; used by the editor to tag metrics with
+     * the served register so bench can split FIM-vs-chat quality.
+     */
+    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. */
+    private leg;
+    predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * Route, then adapt the chosen leg to the multi-candidate surface. The
+     * editor calls this (router exposes no `predictStream`, so it takes the
+     * `wrapAsMulti` branch). `wrapAsMulti` uses the leg's own `predictMulti`
+     * when present (FIM parallel-fire) and otherwise wraps `predict`.
+     */
+    predictMulti(req: GhostRequest): Promise<CandidateSet | null>;
+    /**
+     * Preflight the FIM leg — it carries the primary key/endpoint and is the
+     * always-present leg. The chat leg shares the same vendor/key by default;
+     * its own failures surface as silently-dropped NL completions (which fall
+     * back to nothing rather than a wrong answer), so we don't block startup
+     * on it.
+     */
+    preflight(): Promise<boolean | PreflightResult>;
+}

package/dist/providers/types.d.ts

@@ -1,4 +1,9 @@
+/**
+ * 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;
@@ -15,6 +20,14 @@ export interface GhostRequest {
     }>;
     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
@@ -110,4 +123,3 @@ export declare function wrapAsStream(provider: GhostProvider, req: GhostRequest)
 export declare function streamToText(stream: AsyncIterable<StreamDelta>, startedAt: number, out?: {
     ttftMs?: number;
 }): Promise<string | null>;
-//# sourceMappingURL=types.d.ts.map

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