pi-ghost-autocomplete 0.3.1

package/dist/path-matcher.js

@@ -0,0 +1,85 @@
+import { recentBoost } from "./recent-paths.js";
+const PATH_CHAR = /[A-Za-z0-9_./@\-]/;
+const QUOTE_CHARS = new Set(['"', "'", "`"]);
+/**
+ * Extract a path-like token from the end of `before` (text before the cursor).
+ * Returns null when no path-prefix mode is applicable: a token is only
+ * eligible when it contains a `/` (path-prefix mode is structural, not fuzzy).
+ *
+ * `insideQuote` is true when the character immediately preceding the token is
+ * a quote or backtick; callers can still trust the token in that case.
+ */
+export function extractPathPrefixToken(before) {
+    if (!before)
+        return null;
+    let end = before.length;
+    let start = end;
+    while (start > 0) {
+        const ch = before[start - 1];
+        if (!ch || !PATH_CHAR.test(ch))
+            break;
+        start--;
+    }
+    if (start === end)
+        return null;
+    const token = before.slice(start, end);
+    if (!token.includes("/"))
+        return null;
+    const prev = start > 0 ? before[start - 1] : undefined;
+    const insideQuote = prev !== undefined && QUOTE_CHARS.has(prev);
+    return { token, insideQuote };
+}
+/**
+ * Pick the best path-prefix match for `token`. Strategy: enumerate matches
+ * (capped), prefer files inside `cwdRel` subtree, then shorter paths.
+ *
+ * Returns null when the token has no matches or matches itself exactly
+ * (nothing to insert).
+ */
+export function findPathPrefix(index, token, opts = {}) {
+    // Back-compat: legacy callers pass a numeric `limit`.
+    const o = typeof opts === "number" ? { limit: opts } : opts;
+    const limit = o.limit ?? 64;
+    const recent = o.recentPaths ?? null;
+    // Normalize a leading `./` — extractPathPrefixToken preserves it from the
+    // user's text (e.g. "./src/con") but git ls-files entries never start with
+    // `./`, so the prefix lookup would otherwise miss every cwd-relative entry.
+    const lookupToken = token.startsWith("./") ? token.slice(2) : token;
+    if (!lookupToken)
+        return null;
+    const matches = index.prefixMatches(lookupToken, limit);
+    if (matches.length === 0)
+        return null;
+    const cwdRel = relSubtree(index.root, index.cwd);
+    let best = null;
+    let bestScore = -Infinity;
+    let bestBoost = 0;
+    for (const m of matches) {
+        const inSub = cwdRel === "" || m.startsWith(cwdRel);
+        const rb = recentBoost(m, recent);
+        // Lex-rank: subtree dominates, then recent-mention boost, then short.
+        const score = (inSub ? 1_000_000_000 : 0) + rb * 1_000_000 - m.length;
+        if (score > bestScore) {
+            bestScore = score;
+            best = m;
+            bestBoost = rb;
+        }
+    }
+    if (!best)
+        return null;
+    const suffix = best.slice(lookupToken.length);
+    if (!suffix)
+        return null;
+    return { match: best, suffix, score: 100 + bestBoost };
+}
+function relSubtree(root, cwd) {
+    const r = root.replace(/\\/g, "/").replace(/\/+$/, "");
+    const c = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (c === r)
+        return "";
+    const prefix = `${r}/`;
+    if (c.startsWith(prefix))
+        return `${c.slice(prefix.length)}/`;
+    return "";
+}
+//# sourceMappingURL=path-matcher.js.map

package/dist/path-matcher.js.map

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

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

@@ -0,0 +1,10 @@
+import type { CloudProviderConfig } from "../config.js";
+import type { GhostProvider, GhostRequest } from "./types.js";
+export declare class CloudProvider implements GhostProvider {
+    private readonly config;
+    readonly name = "ghost-cloud";
+    constructor(config: CloudProviderConfig);
+    get debounceMs(): number;
+    predict(req: GhostRequest): Promise<string | null>;
+}
+//# sourceMappingURL=cloud-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-provider.d.ts","sourceRoot":"","sources":["../../src/providers/cloud-provider.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,qBAAa,aAAc,YAAW,aAAa;IAGtC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,IAAI,iBAAiB;gBAED,MAAM,EAAE,mBAAmB;IAExD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAyBxD"}

package/dist/providers/cloud-provider.js

@@ -0,0 +1,52 @@
+import { complete, getEnvApiKey, getModels, } from "@earendil-works/pi-ai";
+import { buildPromptMessages, sanitizeCompletion } from "./truncate.js";
+export class CloudProvider {
+    config;
+    name = "ghost-cloud";
+    constructor(config) {
+        this.config = config;
+    }
+    get debounceMs() {
+        return this.config.debounceMs;
+    }
+    async predict(req) {
+        const apiKey = this.config.apiKey ?? getEnvApiKey(this.config.provider);
+        if (!apiKey)
+            return null;
+        const model = resolveModel(this.config.provider, this.config.modelId);
+        if (!model)
+            return null;
+        const { systemPrompt, user } = buildPromptMessages(req, this.config.maxRecentMessages);
+        const messages = [{ role: "user", content: user, timestamp: Date.now() }];
+        const ctx = { systemPrompt, messages };
+        const result = await complete(model, ctx, {
+            signal: req.signal,
+            temperature: 0.2,
+            maxTokens: this.config.maxTokens,
+            apiKey,
+        });
+        if (result.stopReason === "error" || result.stopReason === "aborted")
+            return null;
+        const text = result.content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("");
+        return sanitizeCompletion(text, req.editorTextBeforeCursor, 200);
+    }
+}
+/**
+ * Look up a model by id from pi-ai's registry. Returns null if the provider
+ * has no model with that id; the caller drops the prediction silently.
+ *
+ * Avoids `getModel(provider, id as never)` — the registry's typed lookup
+ * requires a literal id and would otherwise need an unsafe cast.
+ */
+function resolveModel(provider, modelId) {
+    const models = getModels(provider);
+    for (const m of models) {
+        if (m.id === modelId)
+            return m;
+    }
+    return null;
+}
+//# sourceMappingURL=cloud-provider.js.map

package/dist/providers/cloud-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-provider.js","sourceRoot":"","sources":["../../src/providers/cloud-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,QAAQ,EACR,YAAY,EACZ,SAAS,GAMT,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxE,MAAM,OAAO,aAAa;IAGI;IAFpB,IAAI,GAAG,aAAa,CAAC;IAE9B,YAA6B,MAA2B;QAA3B,WAAM,GAAN,MAAM,CAAqB;IAAG,CAAC;IAE5D,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAiB;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAEzB,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACvF,MAAM,QAAQ,GAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACrF,MAAM,GAAG,GAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;QAEhD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE;YACzC,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,WAAW,EAAE,GAAG;YAChB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAChC,MAAM;SACN,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,UAAU,KAAK,OAAO,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAClF,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO;aACzB,MAAM,CAAC,CAAC,CAAC,EAAuC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aACrE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAClB,IAAI,CAAC,EAAE,CAAC,CAAC;QACX,OAAO,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IAClE,CAAC;CACD;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,QAAuB,EAAE,OAAe;IAC7D,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,EAAE,KAAK,OAAO;YAAE,OAAO,CAAe,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

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

@@ -0,0 +1,11 @@
+import type { LocalProviderConfig } from "../config.js";
+import type { GhostProvider, GhostRequest } from "./types.js";
+export declare class LocalProvider implements GhostProvider {
+    private readonly config;
+    readonly name = "ghost-local";
+    constructor(config: LocalProviderConfig);
+    get debounceMs(): number;
+    preflight(): Promise<boolean>;
+    predict(req: GhostRequest): Promise<string | null>;
+}
+//# sourceMappingURL=local-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-provider.d.ts","sourceRoot":"","sources":["../../src/providers/local-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9D,qBAAa,aAAc,YAAW,aAAa;IAGtC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,IAAI,iBAAiB;gBAED,MAAM,EAAE,mBAAmB;IAExD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAY7B,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAWxD"}

package/dist/providers/local-provider.js

@@ -0,0 +1,36 @@
+import { runOpenAICompletion, trimSlash } from "./openai-completions-runner.js";
+const DEFAULT_CONTEXT_WINDOW = 8192;
+export class LocalProvider {
+    config;
+    name = "ghost-local";
+    constructor(config) {
+        this.config = config;
+    }
+    get debounceMs() {
+        return this.config.debounceMs;
+    }
+    async preflight() {
+        try {
+            const ctrl = new AbortController();
+            const timeout = setTimeout(() => ctrl.abort(), 750);
+            const res = await fetch(`${trimSlash(this.config.baseUrl)}/api/tags`, { signal: ctrl.signal });
+            clearTimeout(timeout);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async predict(req) {
+        return runOpenAICompletion(req, {
+            baseUrl: `${trimSlash(this.config.baseUrl)}/v1`,
+            apiKey: "ollama",
+            modelId: this.config.modelId,
+            providerTag: "ollama",
+            maxTokens: this.config.maxTokens,
+            maxRecentMessages: this.config.maxRecentMessages,
+            contextWindow: this.config.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+        });
+    }
+}
+//# sourceMappingURL=local-provider.js.map

package/dist/providers/local-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-provider.js","sourceRoot":"","sources":["../../src/providers/local-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAGhF,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAEpC,MAAM,OAAO,aAAa;IAGI;IAFpB,IAAI,GAAG,aAAa,CAAC;IAE9B,YAA6B,MAA2B;QAA3B,WAAM,GAAN,MAAM,CAAqB;IAAG,CAAC;IAE5D,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,SAAS;QACd,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC;YACpD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAC/F,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,CAAC,EAAE,CAAC;QACf,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAiB;QAC9B,OAAO,mBAAmB,CAAC,GAAG,EAAE;YAC/B,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK;YAC/C,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,WAAW,EAAE,QAAQ;YACrB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAChC,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;YAChD,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,sBAAsB;SAClE,CAAC,CAAC;IACJ,CAAC;CACD"}

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

@@ -0,0 +1,29 @@
+import type { OpenAICompatProviderConfig } from "../config.js";
+import type { GhostProvider, GhostRequest } from "./types.js";
+export interface PreflightResult {
+    ok: boolean;
+    status?: number;
+    message: string;
+}
+/**
+ * Provider for FIM-completions backends (e.g. Mercury Edit 2 by Inception
+ * Labs). Calls `/fim/completions` with `prompt`/`suffix` and returns the
+ * raw text completion.
+ *
+ * A {@link preflight} method validates the API key at startup so the host
+ * can surface configuration errors early instead of silently dropping
+ * every prediction.
+ */
+export declare class OpenAICompatProvider implements GhostProvider {
+    private readonly config;
+    readonly name: string;
+    constructor(config: OpenAICompatProviderConfig);
+    get debounceMs(): number;
+    /**
+     * Validate the API key with a minimal FIM request. A successful
+     * response (even an empty completion) proves auth + connectivity.
+     */
+    preflight(): Promise<PreflightResult>;
+    predict(req: GhostRequest): Promise<string | null>;
+}
+//# sourceMappingURL=openai-compat-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai-compat-provider.d.ts","sourceRoot":"","sources":["../../src/providers/openai-compat-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9D,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IAG7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEO,MAAM,EAAE,0BAA0B;IAI/D,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IA+BrC,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAgCxD"}

package/dist/providers/openai-compat-provider.js

@@ -0,0 +1,128 @@
+import { sanitizeCompletion } from "./truncate.js";
+const PREFLIGHT_TIMEOUT_MS = 5_000;
+/**
+ * Provider for FIM-completions backends (e.g. Mercury Edit 2 by Inception
+ * Labs). Calls `/fim/completions` with `prompt`/`suffix` and returns the
+ * raw text completion.
+ *
+ * A {@link preflight} method validates the API key at startup so the host
+ * can surface configuration errors early instead of silently dropping
+ * every prediction.
+ */
+export class OpenAICompatProvider {
+    config;
+    name;
+    constructor(config) {
+        this.config = config;
+        this.name = `ghost-${config.providerName}`;
+    }
+    get debounceMs() {
+        return this.config.debounceMs;
+    }
+    /**
+     * Validate the API key with a minimal FIM request. A successful
+     * response (even an empty completion) proves auth + connectivity.
+     */
+    async preflight() {
+        const apiKey = this.config.apiKey;
+        if (!apiKey)
+            return { ok: false, message: "no API key configured" };
+        const ctrl = new AbortController();
+        const timeout = setTimeout(() => ctrl.abort(), PREFLIGHT_TIMEOUT_MS);
+        try {
+            const res = await fetch(`${trimSlash(this.config.baseUrl)}/fim/completions`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: this.config.modelId,
+                    prompt: " ",
+                    max_tokens: 1,
+                }),
+                signal: ctrl.signal,
+            });
+            clearTimeout(timeout);
+            if (res.ok)
+                return { ok: true, status: res.status, message: "ok" };
+            return { ok: false, status: res.status, message: describeHttpError(res.status) };
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            const aborted = err?.name === "AbortError";
+            if (aborted)
+                return { ok: false, message: "endpoint timed out" };
+            return { ok: false, message: "endpoint unreachable" };
+        }
+    }
+    async predict(req) {
+        const apiKey = this.config.apiKey;
+        if (!apiKey)
+            return null;
+        const { prompt, suffix } = buildFIMPrompt(req, this.config.maxRecentMessages);
+        try {
+            const res = await fetch(`${trimSlash(this.config.baseUrl)}/fim/completions`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: this.config.modelId,
+                    prompt,
+                    suffix,
+                    max_tokens: this.config.maxTokens,
+                    temperature: 0.2,
+                }),
+                signal: req.signal,
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            const text = data.choices?.[0]?.text ?? "";
+            return sanitizeCompletion(text, req.editorTextBeforeCursor, 200);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * 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.
+ */
+function buildFIMPrompt(req, maxRecent) {
+    const recent = req.recentMessages
+        .slice(-maxRecent)
+        .map((m) => `# ${m.role}: ${truncate(m.text, 280)}`)
+        .join("\n");
+    const ctx = recent ? `${recent}\n\n` : "";
+    // Split the editor text at cursor to form prompt (before) / suffix (after).
+    // Ghost autocomplete only fires when cursor is at end, so suffix is empty
+    // in the common case — but we handle the general case for correctness.
+    const before = req.editorTextBeforeCursor;
+    const after = req.editorText.slice(req.editorTextBeforeCursor.length);
+    return {
+        prompt: `${ctx}${before}`,
+        suffix: after,
+    };
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+function trimSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function describeHttpError(status) {
+    switch (status) {
+        case 401: return "invalid API key (401 Unauthorized)";
+        case 402: return "API key has no credits — please top up (402 Payment Required)";
+        case 403: return "API key not permitted (403 Forbidden)";
+        case 429: return "rate limited (429 Too Many Requests)";
+        default: return `HTTP ${status}`;
+    }
+}
+//# sourceMappingURL=openai-compat-provider.js.map

package/dist/providers/openai-compat-provider.js.map

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

package/dist/providers/openai-completions-runner.d.ts

@@ -0,0 +1,28 @@
+import type { GhostRequest } from "./types.js";
+export interface OpenAICompletionsCallOpts {
+    baseUrl: string;
+    apiKey: string;
+    modelId: string;
+    /**
+     * Metadata tag for pi-ai's `Model.provider`. Cosmetic for logs — the
+     * actual endpoint is driven by `baseUrl`. Accepts any string; cast to
+     * `KnownProvider` at the call site since the field is purely descriptive.
+     */
+    providerTag: string;
+    maxTokens: number;
+    maxRecentMessages: number;
+    contextWindow: number;
+}
+/**
+ * Shared OpenAI-completions request path used by both {@link LocalProvider}
+ * and {@link OpenAICompatProvider}. Builds the pi-ai model record, sends one
+ * `complete()` call with the user's abort signal, and returns a sanitized
+ * completion string (or null when the call aborts/errors/produces nothing
+ * usable).
+ *
+ * Kept as a free function rather than a base class to avoid one-method
+ * inheritance.
+ */
+export declare function runOpenAICompletion(req: GhostRequest, opts: OpenAICompletionsCallOpts): Promise<string | null>;
+export declare function trimSlash(url: string): string;
+//# sourceMappingURL=openai-completions-runner.d.ts.map

package/dist/providers/openai-completions-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-completions-runner.d.ts","sourceRoot":"","sources":["../../src/providers/openai-completions-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,yBAAyB;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,yBAAyB,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/providers/openai-completions-runner.js

@@ -0,0 +1,46 @@
+import { complete } from "@earendil-works/pi-ai";
+import { buildPromptMessages, sanitizeCompletion } from "./truncate.js";
+/**
+ * Shared OpenAI-completions request path used by both {@link LocalProvider}
+ * and {@link OpenAICompatProvider}. Builds the pi-ai model record, sends one
+ * `complete()` call with the user's abort signal, and returns a sanitized
+ * completion string (or null when the call aborts/errors/produces nothing
+ * usable).
+ *
+ * Kept as a free function rather than a base class to avoid one-method
+ * inheritance.
+ */
+export async function runOpenAICompletion(req, opts) {
+    const model = {
+        id: opts.modelId,
+        name: opts.modelId,
+        api: "openai-completions",
+        provider: opts.providerTag,
+        baseUrl: trimSlash(opts.baseUrl),
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: opts.contextWindow,
+        maxTokens: opts.maxTokens,
+    };
+    const { systemPrompt, user } = buildPromptMessages(req, opts.maxRecentMessages);
+    const messages = [{ role: "user", content: user, timestamp: Date.now() }];
+    const ctx = { systemPrompt, messages };
+    const result = await complete(model, ctx, {
+        signal: req.signal,
+        temperature: 0.2,
+        maxTokens: opts.maxTokens,
+        apiKey: opts.apiKey,
+    });
+    if (result.stopReason === "error" || result.stopReason === "aborted")
+        return null;
+    const text = result.content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+    return sanitizeCompletion(text, req.editorTextBeforeCursor, 200);
+}
+export function trimSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=openai-completions-runner.js.map

package/dist/providers/openai-completions-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-completions-runner.js","sourceRoot":"","sources":["../../src/providers/openai-completions-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA8D,MAAM,uBAAuB,CAAC;AAC7G,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAkBxE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,GAAiB,EACjB,IAA+B;IAE/B,MAAM,KAAK,GAAgC;QAC1C,EAAE,EAAE,IAAI,CAAC,OAAO;QAChB,IAAI,EAAE,IAAI,CAAC,OAAO;QAClB,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,IAAI,CAAC,WAA4B;QAC3C,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;QAChC,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;QAC1D,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,SAAS,EAAE,IAAI,CAAC,SAAS;KACzB,CAAC;IAEF,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACrF,MAAM,GAAG,GAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;IAEhD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE;QACzC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW,EAAE,GAAG;QAChB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM;KACnB,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,UAAU,KAAK,OAAO,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAClF,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO;SACzB,MAAM,CAAC,CAAC,CAAC,EAAuC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SACrE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,EAAE,CAAC,CAAC;IACX,OAAO,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACnD,CAAC"}

package/dist/providers/race.d.ts

@@ -0,0 +1,40 @@
+import type { ProviderLatency } from "../metrics.js";
+import type { GhostProvider, GhostRequest } from "./types.js";
+export interface RaceConfig {
+    /** Pause/debounce before race starts. Reported as `debounceMs`. */
+    pauseMs: number;
+    /** After a non-success race, suppress new races for this long. */
+    cooldownMs: number;
+    /** Hard timeout from race start; all in-flight providers aborted. */
+    cutoffMs: number;
+}
+export interface RaceTrace {
+    providers: ProviderLatency[];
+    winner?: string;
+}
+/**
+ * Implements {@link GhostProvider} by racing several providers in parallel.
+ * First non-null result wins; losers are aborted via a shared signal.
+ *
+ * Trace metadata for the most recent race is exposed via
+ * {@link consumeLastTrace}. The editor reads it after `predict()` to emit a
+ * multi-provider metrics record. Consumption is one-shot to avoid stale reuse.
+ */
+export declare class RaceProvider implements GhostProvider {
+    private readonly members;
+    private readonly cfg;
+    readonly name: string;
+    private cooldownUntil;
+    private lastTrace;
+    constructor(members: GhostProvider[], cfg: RaceConfig);
+    get debounceMs(): number;
+    consumeLastTrace(): RaceTrace | null;
+    predict(req: GhostRequest): Promise<string | null>;
+    private runMember;
+}
+/**
+ * Resolve to the first non-null value among `promises`. Resolves null when
+ * 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/race.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"race.d.ts","sourceRoot":"","sources":["../../src/providers/race.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,UAAU;IAC1B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACzB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAa,YAAW,aAAa;IAMhD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IANrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAA0B;gBAGzB,OAAO,EAAE,aAAa,EAAE,EACxB,GAAG,EAAE,UAAU;IAKjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,gBAAgB,IAAI,SAAS,GAAG,IAAI;IAM9B,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YA6C1C,SAAS;CA8BvB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAyBrF"}

package/dist/providers/race.js

@@ -0,0 +1,128 @@
+/**
+ * Implements {@link GhostProvider} by racing several providers in parallel.
+ * First non-null result wins; losers are aborted via a shared signal.
+ *
+ * Trace metadata for the most recent race is exposed via
+ * {@link consumeLastTrace}. The editor reads it after `predict()` to emit a
+ * multi-provider metrics record. Consumption is one-shot to avoid stale reuse.
+ */
+export class RaceProvider {
+    members;
+    cfg;
+    name;
+    cooldownUntil = 0;
+    lastTrace = null;
+    constructor(members, cfg) {
+        this.members = members;
+        this.cfg = cfg;
+        this.name = `ghost-race:${members.map((p) => p.name).join(",")}`;
+    }
+    get debounceMs() {
+        return this.cfg.pauseMs;
+    }
+    consumeLastTrace() {
+        const t = this.lastTrace;
+        this.lastTrace = null;
+        return t;
+    }
+    async predict(req) {
+        if (this.members.length === 0)
+            return null;
+        const now = Date.now();
+        if (now < this.cooldownUntil) {
+            this.lastTrace = { providers: [] };
+            return null;
+        }
+        const trace = [];
+        const localCtrl = new AbortController();
+        const start = now;
+        // Propagate caller cancellation; do not propagate our own internal aborts.
+        const onUserAbort = () => localCtrl.abort();
+        if (req.signal.aborted) {
+            localCtrl.abort();
+        }
+        else {
+            req.signal.addEventListener("abort", onUserAbort, { once: true });
+        }
+        const cutoffTimer = setTimeout(() => localCtrl.abort(), this.cfg.cutoffMs);
+        try {
+            const races = this.members.map((p) => this.runMember(p, { ...req, signal: localCtrl.signal }, start, trace));
+            const winner = await firstNonNull(races);
+            if (winner) {
+                localCtrl.abort();
+                this.lastTrace = { providers: trace, winner: winner.provider };
+                return winner.completion;
+            }
+            // Skip cooldown when the caller cancelled — that's a normal stutter,
+            // not a sign the providers are failing. Only true non-success (empty,
+            // rejected, error, internal-cutoff) should throttle the next race.
+            if (!req.signal.aborted) {
+                this.cooldownUntil = Date.now() + this.cfg.cooldownMs;
+            }
+            this.lastTrace = { providers: trace };
+            return null;
+        }
+        finally {
+            clearTimeout(cutoffTimer);
+            req.signal.removeEventListener("abort", onUserAbort);
+        }
+    }
+    async runMember(provider, req, start, trace) {
+        try {
+            const result = await provider.predict(req);
+            const latencyMs = Date.now() - start;
+            if (req.signal.aborted) {
+                trace.push({ provider: provider.name, latencyMs, result: "aborted" });
+                return null;
+            }
+            if (result === null || result === "") {
+                trace.push({ provider: provider.name, latencyMs, result: "empty" });
+                return null;
+            }
+            trace.push({ provider: provider.name, latencyMs, result: "produced" });
+            return { provider: provider.name, completion: result };
+        }
+        catch (err) {
+            const latencyMs = Date.now() - start;
+            const aborted = err?.name === "AbortError";
+            trace.push({
+                provider: provider.name,
+                latencyMs,
+                result: aborted ? "aborted" : "error",
+            });
+            return null;
+        }
+    }
+}
+/**
+ * Resolve to the first non-null value among `promises`. Resolves null when
+ * all promises produce null (or throw). Never rejects.
+ */
+export function firstNonNull(promises) {
+    if (promises.length === 0)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let remaining = promises.length;
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(v);
+        };
+        for (const p of promises) {
+            p.then((v) => {
+                if (v !== null) {
+                    finish(v);
+                    return;
+                }
+                if (--remaining === 0)
+                    finish(null);
+            }, () => {
+                if (--remaining === 0)
+                    finish(null);
+            });
+        }
+    });
+}
+//# sourceMappingURL=race.js.map