pi-ghost-autocomplete 0.3.1 → 0.3.2

package/dist/session-trie.js

@@ -0,0 +1,280 @@
+/**
+ * Session trie — fast-path completion source backed by the user's own past
+ * accepts and committed messages. See PRD §M2.
+ *
+ * Structurally this is `Map<prefix, Map<suffix, weight>>` rather than a true
+ * trie. At the PRD's 5000-entry cap, hash-lookup-by-exact-prefix is faster
+ * than walking a character trie, and the simpler shape is easier to reason
+ * about for decay and eviction.
+ *
+ * Insertion sources and weights (PRD §M2 "Insertion signals"):
+ *  - full accept: +3
+ *  - partial accept: +2 on the partial word, +1 on the full candidate
+ *  - committed user message: +1, prefix length 3..12 chars, suffix capped at
+ *    4 word-boundary shingles
+ *  - divergent dismiss: -0.5 (caller decides what counts as divergent;
+ *    per-keystroke dismisses must NOT call here, per PRD)
+ *
+ * Lookup gates (PRD §M2 "Lookup"):
+ *  - prefix length ≥ 3
+ *  - winner weight ≥ 1.5
+ *  - winner margin over runner-up ≥ 1.0
+ */
+import { containsSensitive } from "./trie-sanitize.js";
+export const MIN_PREFIX_LEN = 3;
+export const MIN_WEIGHT = 1.5;
+export const MIN_MARGIN = 1.0;
+export const DEFAULT_CAPACITY = 5000;
+export const DEFAULT_DECAY_EVERY = 200;
+export const DEFAULT_DECAY_FACTOR = 0.5;
+export const MAX_COMMITTED_PREFIX_LEN = 12;
+export const MAX_COMMITTED_SUFFIX_WORDS = 4;
+export class SessionTrie {
+    capacity;
+    decayEvery;
+    decayFactor;
+    /**
+     * `Map` insertion order is the LRU stamp — we re-insert a prefix key after
+     * touching it. Beyond capacity, the oldest key (first in iteration order)
+     * is evicted.
+     */
+    map = new Map();
+    insertsSinceDecay = 0;
+    constructor(capacity = DEFAULT_CAPACITY, decayEvery = DEFAULT_DECAY_EVERY, decayFactor = DEFAULT_DECAY_FACTOR) {
+        this.capacity = capacity;
+        this.decayEvery = decayEvery;
+        this.decayFactor = decayFactor;
+        if (capacity <= 0) {
+            this.capacity = DEFAULT_CAPACITY;
+        }
+    }
+    get size() {
+        return this.map.size;
+    }
+    get stats() {
+        let candidates = 0;
+        for (const m of this.map.values())
+            candidates += m.size;
+        return {
+            prefixes: this.map.size,
+            candidates,
+            insertsSinceDecay: this.insertsSinceDecay,
+        };
+    }
+    insert(prefix, suffix, weight) {
+        if (prefix.length === 0 || suffix.length === 0)
+            return;
+        if (containsSensitive(prefix) || containsSensitive(suffix))
+            return;
+        this.bumpCandidate(prefix, suffix, weight);
+        this.tickDecayCounter();
+        this.enforceCapacity();
+    }
+    /**
+     * Insert prefix→remainder pairs from an accepted ghost: prefix is the
+     * editor text immediately before the ghost; the full accepted suffix is
+     * the value. Weight is the caller's choice (+3 full, +2 partial-word, +1
+     * full-candidate-on-partial). Caller handles signal selection.
+     */
+    insertFromAccept(prefix, suffix, weight) {
+        this.insert(prefix, suffix, weight);
+    }
+    /**
+     * Insert sliding-window prefix→remainder pairs from a committed user
+     * message at weight +1 each (PRD §M2). Prefix lengths 3..12 chars,
+     * remainder capped at 4 word-boundary shingles to limit memory and avoid
+     * memorizing entire messages.
+     *
+     * Skips the whole message if any token matches a sensitive pattern.
+     */
+    insertFromCommittedMessage(text, weightPerShingle = 1) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        if (containsSensitive(trimmed))
+            return;
+        const wordBoundaries = collectWordBoundaries(trimmed);
+        if (wordBoundaries.length === 0)
+            return;
+        for (let prefixLen = MIN_PREFIX_LEN; prefixLen <= MAX_COMMITTED_PREFIX_LEN && prefixLen < trimmed.length; prefixLen++) {
+            const prefix = trimmed.slice(0, prefixLen);
+            const suffix = sliceWordsAfter(trimmed, prefixLen, wordBoundaries, MAX_COMMITTED_SUFFIX_WORDS);
+            if (!suffix)
+                continue;
+            this.bumpCandidate(prefix, suffix, weightPerShingle);
+        }
+        this.tickDecayCounter();
+        this.enforceCapacity();
+    }
+    /**
+     * Penalize an entry that diverged from the user's eventual commit.
+     * Per-keystroke dismisses must NOT call this (would penalize correct
+     * ghosts mid-typing). See PRD §M2.
+     */
+    penalize(prefix, suffix, magnitude = 0.5) {
+        magnitude = Math.max(0, magnitude);
+        const bucket = this.map.get(prefix);
+        if (!bucket)
+            return;
+        const current = bucket.get(suffix);
+        if (current === undefined)
+            return;
+        const next = current - magnitude;
+        if (next <= 0) {
+            bucket.delete(suffix);
+            if (bucket.size === 0)
+                this.map.delete(prefix);
+        }
+        else {
+            bucket.set(suffix, next);
+        }
+    }
+    lookup(prefix) {
+        if (prefix.length < MIN_PREFIX_LEN)
+            return null;
+        // Walk from longest to shortest prefix. The longest match that satisfies
+        // weight + margin wins. For a stored entry whose key is shorter than the
+        // user's current prefix, the user has already typed part of the
+        // suggested suffix → shift the ghost accordingly (typeahead-delta logic,
+        // same idea as `tryWarm`'s typeahead branch). If the user's typing
+        // diverges from the stored suffix, that candidate is skipped.
+        const maxLen = prefix.length;
+        for (let keyLen = maxLen; keyLen >= MIN_PREFIX_LEN; keyLen--) {
+            const key = prefix.slice(0, keyLen);
+            const bucket = this.map.get(key);
+            if (!bucket || bucket.size === 0)
+                continue;
+            const typedDelta = prefix.slice(keyLen);
+            let bestSuffix = null;
+            let bestWeight = -Infinity;
+            let runnerUp = 0;
+            for (const [suffix, weight] of bucket) {
+                // Stored suffix must agree with what the user typed since `key`.
+                if (typedDelta.length > 0 && !suffix.startsWith(typedDelta))
+                    continue;
+                if (weight > bestWeight) {
+                    runnerUp = bestWeight === -Infinity ? 0 : bestWeight;
+                    bestWeight = weight;
+                    bestSuffix = suffix;
+                }
+                else if (weight > runnerUp) {
+                    runnerUp = weight;
+                }
+            }
+            if (bestSuffix === null)
+                continue;
+            if (bestWeight < MIN_WEIGHT)
+                continue;
+            const margin = bestWeight - runnerUp;
+            if (margin < MIN_MARGIN)
+                continue;
+            const shifted = bestSuffix.slice(typedDelta.length);
+            if (shifted.length === 0)
+                continue;
+            // LRU touch on hit.
+            this.map.delete(key);
+            this.map.set(key, bucket);
+            return { ghost: shifted, weight: bestWeight, margin };
+        }
+        return null;
+    }
+    clear() {
+        this.map.clear();
+        this.insertsSinceDecay = 0;
+    }
+    /**
+     * Halve all weights. Exposed for testing; callers normally rely on the
+     * automatic decay every `decayEvery` inserts.
+     */
+    decayNow() {
+        for (const bucket of this.map.values()) {
+            for (const [suffix, weight] of bucket) {
+                const next = weight * this.decayFactor;
+                if (next < 0.05)
+                    bucket.delete(suffix);
+                else
+                    bucket.set(suffix, next);
+            }
+        }
+        // Drop empty buckets.
+        for (const [prefix, bucket] of this.map) {
+            if (bucket.size === 0)
+                this.map.delete(prefix);
+        }
+        this.insertsSinceDecay = 0;
+    }
+    bumpCandidate(prefix, suffix, weight) {
+        let bucket = this.map.get(prefix);
+        if (bucket) {
+            // LRU touch.
+            this.map.delete(prefix);
+        }
+        else {
+            bucket = new Map();
+        }
+        bucket.set(suffix, (bucket.get(suffix) ?? 0) + weight);
+        this.map.set(prefix, bucket);
+    }
+    tickDecayCounter() {
+        this.insertsSinceDecay++;
+        if (this.insertsSinceDecay >= this.decayEvery) {
+            this.decayNow();
+        }
+    }
+    enforceCapacity() {
+        while (this.map.size > this.capacity) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
+    }
+}
+/**
+ * Return the end-of-word offsets in `text` (exclusive). For "ab cd ef", returns
+ * [2, 5, 8]. Used to align committed-message shingles to word boundaries.
+ */
+/**
+ * Pure helper used by `GhostEditor.onPromptCommitted`. Seeds `trie` from the
+ * committed text. If `accepted` is non-null AND the committed text contains
+ * the accepted ghost, the per-shingle weight drops from +1 to +0.25 to avoid
+ * double-counting (PRD §M2 "Insertion signals").
+ */
+export function seedTrieFromCommit(trie, text, accepted) {
+    if (!text)
+        return;
+    const overlaps = accepted ? text.includes(accepted.ghost) : false;
+    trie.insertFromCommittedMessage(text, overlaps ? 0.25 : 1);
+}
+function collectWordBoundaries(text) {
+    const out = [];
+    let inWord = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        const isWS = /\s/.test(ch);
+        if (!isWS && !inWord)
+            inWord = true;
+        if (isWS && inWord) {
+            out.push(i);
+            inWord = false;
+        }
+    }
+    if (inWord)
+        out.push(text.length);
+    return out;
+}
+function sliceWordsAfter(text, start, boundaries, maxWords) {
+    let crossed = 0;
+    let end = text.length;
+    for (const b of boundaries) {
+        if (b <= start)
+            continue;
+        crossed++;
+        if (crossed >= maxWords) {
+            end = b;
+            break;
+        }
+    }
+    return text.slice(start, end);
+}
+//# sourceMappingURL=session-trie.js.map

package/dist/session-trie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-trie.js","sourceRoot":"","sources":["../src/session-trie.ts"],"names":[],"mappings":"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"}

package/dist/speculative.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Speculative cache warm — covers the gap between an exact cache hit and a
+ * full LLM call. See PRD §6 M1b.
+ *
+ * Three match branches:
+ *  - exact: prefix matches a recent ghost's prefix → reuse the ghost.
+ *  - typeahead-delta: user typed forward into the ghost text → return the
+ *    remaining ghost suffix.
+ *  - backspace-of-N: user backspaced ≤3 chars within an old prefix → return
+ *    droppedTail + oldGhost. Only fires while the race is in cooldown,
+ *    because a fresh LLM call is preferable when budget allows.
+ *
+ * All branches require context/provider/version fingerprints to match the
+ * shown ghost to avoid leaking stale results across context shifts.
+ */
+export interface LastGhost {
+    prefix: string;
+    ghost: string;
+    ts: number;
+    contextFingerprint: string;
+    providerFingerprint: string;
+    versionFingerprint: string;
+    /** Engine config fingerprint at the time this entry was recorded
+     *  (refactor #57 phase 2). Optional — entries without it match any
+     *  fingerprint (legacy + test-fixture compatibility). */
+    configFingerprint?: string;
+    /**
+     * Originating provider name (e.g. "mercury-edit", "ghost-race:..."). Used
+     * by the editor to attribute speculative-warm metrics back to the provider
+     * that produced the source ghost, instead of the synthetic "speculative-warm"
+     * label. See PRD §5b.
+     */
+    providerName: string;
+}
+export interface SpeculativeMatchInput {
+    prefix: string;
+    contextFingerprint: string;
+    providerFingerprint: string;
+    versionFingerprint: string;
+    /** Engine config fingerprint to match against. Optional — when omitted,
+     *  the warm path skips the config check (legacy / test compatibility). */
+    configFingerprint?: string;
+    cooldownActive: boolean;
+}
+export type SpeculativeBranch = "exact" | "typeahead-delta" | "backspace-of-N";
+export interface SpeculativeMatch {
+    ghost: string;
+    branch: SpeculativeBranch;
+    source: LastGhost;
+}
+/**
+ * Fixed-capacity ring of recent ghosts. The newest entry sits at the end.
+ */
+export declare class LastGhostsRing {
+    private readonly capacity;
+    private readonly buf;
+    constructor(capacity?: number);
+    get size(): number;
+    push(entry: LastGhost): void;
+    entries(): readonly LastGhost[];
+    clear(): void;
+}
+/**
+ * Try to satisfy a prefix from `ring` without firing the LLM. Returns the
+ * first match across exact / typeahead-delta / backspace-N. Newest entries
+ * are checked first.
+ *
+ * Grapheme-aware slicing is NOT applied here — the editor passes string
+ * prefixes/ghosts that were already produced grapheme-aware in
+ * `ghost-editor.ts`. The PRD's grapheme-awareness requirement is for the
+ * editor's slicing; this helper operates on the resulting strings.
+ */
+export declare function tryWarm(ring: LastGhostsRing, input: SpeculativeMatchInput): SpeculativeMatch | null;
+//# sourceMappingURL=speculative.d.ts.map

package/dist/speculative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speculative.d.ts","sourceRoot":"","sources":["../src/speculative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;6DAEyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B;8EAC0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE/E,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,SAAS,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,cAAc;IAGd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;gBAEV,QAAQ,GAAE,MAAU;IAEjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAoB5B,OAAO,IAAI,SAAS,SAAS,EAAE;IAI/B,KAAK,IAAI,IAAI;CAGb;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACtB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,qBAAqB,GAC1B,gBAAgB,GAAG,IAAI,CAmDzB"}

package/dist/speculative.js

@@ -0,0 +1,107 @@
+/**
+ * Speculative cache warm — covers the gap between an exact cache hit and a
+ * full LLM call. See PRD §6 M1b.
+ *
+ * Three match branches:
+ *  - exact: prefix matches a recent ghost's prefix → reuse the ghost.
+ *  - typeahead-delta: user typed forward into the ghost text → return the
+ *    remaining ghost suffix.
+ *  - backspace-of-N: user backspaced ≤3 chars within an old prefix → return
+ *    droppedTail + oldGhost. Only fires while the race is in cooldown,
+ *    because a fresh LLM call is preferable when budget allows.
+ *
+ * All branches require context/provider/version fingerprints to match the
+ * shown ghost to avoid leaking stale results across context shifts.
+ */
+const BACKSPACE_MAX_DELTA = 3;
+/**
+ * Fixed-capacity ring of recent ghosts. The newest entry sits at the end.
+ */
+export class LastGhostsRing {
+    capacity;
+    buf = [];
+    constructor(capacity = 8) {
+        this.capacity = capacity;
+    }
+    get size() {
+        return this.buf.length;
+    }
+    push(entry) {
+        // Treat (prefix, providerFingerprint, contextFingerprint, versionFingerprint)
+        // as the identity. A new completion for the same prefix in the same context
+        // supersedes the older one.
+        for (let i = 0; i < this.buf.length; i++) {
+            const e = this.buf[i];
+            if (e.prefix === entry.prefix &&
+                e.contextFingerprint === entry.contextFingerprint &&
+                e.providerFingerprint === entry.providerFingerprint &&
+                e.versionFingerprint === entry.versionFingerprint) {
+                this.buf.splice(i, 1);
+                break;
+            }
+        }
+        this.buf.push(entry);
+        while (this.buf.length > this.capacity)
+            this.buf.shift();
+    }
+    entries() {
+        return this.buf;
+    }
+    clear() {
+        this.buf.length = 0;
+    }
+}
+/**
+ * Try to satisfy a prefix from `ring` without firing the LLM. Returns the
+ * first match across exact / typeahead-delta / backspace-N. Newest entries
+ * are checked first.
+ *
+ * Grapheme-aware slicing is NOT applied here — the editor passes string
+ * prefixes/ghosts that were already produced grapheme-aware in
+ * `ghost-editor.ts`. The PRD's grapheme-awareness requirement is for the
+ * editor's slicing; this helper operates on the resulting strings.
+ */
+export function tryWarm(ring, input) {
+    const entries = ring.entries();
+    // Newest first.
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const lg = entries[i];
+        if (lg.contextFingerprint !== input.contextFingerprint ||
+            lg.providerFingerprint !== input.providerFingerprint ||
+            lg.versionFingerprint !== input.versionFingerprint) {
+            continue;
+        }
+        // Config fingerprint folded in #57 phase 2 — skip the check when
+        // either side is undefined (legacy entries / test fixtures); reject
+        // only when both are defined and differ.
+        if (lg.configFingerprint !== undefined &&
+            input.configFingerprint !== undefined &&
+            lg.configFingerprint !== input.configFingerprint) {
+            continue;
+        }
+        // Branch 1: exact prefix match (always short-circuit).
+        if (lg.prefix === input.prefix) {
+            return { ghost: lg.ghost, branch: "exact", source: lg };
+        }
+        // Branch 2: typeahead-delta — user typed forward into the ghost.
+        if (input.prefix.startsWith(lg.prefix)) {
+            const delta = input.prefix.slice(lg.prefix.length);
+            if (delta.length > 0 && lg.ghost.startsWith(delta)) {
+                const remainder = lg.ghost.slice(delta.length);
+                if (remainder.length > 0) {
+                    return { ghost: remainder, branch: "typeahead-delta", source: lg };
+                }
+            }
+        }
+        // Branch 3: backspace-of-N — only when cooldown is active.
+        if (input.cooldownActive &&
+            lg.prefix.startsWith(input.prefix) &&
+            lg.prefix.length > input.prefix.length &&
+            lg.prefix.length - input.prefix.length <= BACKSPACE_MAX_DELTA) {
+            const droppedTail = lg.prefix.slice(input.prefix.length);
+            return { ghost: droppedTail + lg.ghost, branch: "backspace-of-N", source: lg };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=speculative.js.map

package/dist/speculative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speculative.js","sourceRoot":"","sources":["../src/speculative.ts"],"names":[],"mappings":"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"}

package/dist/tool-summarize.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Type-aware compact summaries of tool outputs for inclusion in ghost
+ * context. See PRD §M6c.
+ *
+ * Each summarizer takes the flattened tool message (`toolName` + raw
+ * `text`) and produces a short, typed description. The goal is to
+ * preserve the *signal* of the tool result (file path, command, exit
+ * code, top symbol) without dragging the full output into the prompt.
+ *
+ * Pure module: no I/O. Dispatch by `toolName` (case-insensitive); falls
+ * back to a generic short-line summary for unknown tools.
+ */
+import type { RecentMessage } from "./context-aggregator.js";
+export declare const DEFAULT_TOOL_MAX = 3;
+export interface ToolSummary {
+    text: string;
+}
+/**
+ * Summarize a single tool entry. Returns a new `RecentMessage` with the
+ * compact summary as `text`; preserves `role` and `toolName`.
+ *
+ * Note: PRD §M6c specs this as `summarizeToolResult(entry): ToolSummary`
+ * — we deviate by returning a `RecentMessage` so callers can preserve
+ * `role`/`toolName` for downstream prompt formatting in `truncate.ts` and
+ * `openai-compat-provider.ts`. The internal `ToolSummary` type is the
+ * dispatcher return; it carries the rewritten `text` only.
+ */
+export declare function summarizeToolEntry(entry: RecentMessage): RecentMessage;
+/**
+ * Apply summarization across an array, optionally capping the number of
+ * tool entries retained (PRD §M6c: cap 3 by default). Non-tool entries
+ * pass through unchanged.
+ */
+export declare function summarizeAndCapTools(entries: RecentMessage[], maxTools?: number): RecentMessage[];
+/**
+ * Parse `PI_GHOST_CONTEXT_TOOL_MAX`. Returns fallback on bad input or
+ * negative values.
+ */
+export declare function parseToolMaxEnv(raw: string | undefined): number;
+//# sourceMappingURL=tool-summarize.d.ts.map

package/dist/tool-summarize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-summarize.d.ts","sourceRoot":"","sources":["../src/tool-summarize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAKlC,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAKtE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,aAAa,EAAE,EACxB,QAAQ,GAAE,MAAyB,GACjC,aAAa,EAAE,CAgBjB;AAoLD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK/D"}