pi-ghost-autocomplete 0.10.0 → 0.12.0

package/dist/intent-classifier.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+import type { CompletionRegister } from "./intent.js";
+export interface IntentClassifierOptions {
+    /** Per-consult abort timeout. Default 400 ms (`PI_GHOST_INTENT_CLASSIFIER_TIMEOUT_MS`). */
+    timeoutMs: number;
+    /** Minimum answer confidence to apply a verdict. Default 0.6 (`PI_GHOST_INTENT_CLASSIFIER_MIN_CONFIDENCE`). */
+    minConfidence: number;
+    /** Verdict cache TTL. Default 60 s. */
+    ttlMs: number;
+    /** Verdict cache capacity (insertion-order eviction). Default 64. */
+    capacity: number;
+    /** Draft-prefix length the cache keys on. Default 32 chars. */
+    keyPrefixLen: number;
+    /**
+     * Debounce for the consult itself — a keystroke burst collapses into one
+     * classify call on the latest draft (the pending-set alone can't dedupe:
+     * every keystroke changes the cache key). Default 120 ms
+     * (`PI_GHOST_INTENT_CLASSIFIER_DEBOUNCE_MS`, clamped [0, 1000]).
+     */
+    consultDebounceMs: number;
+    now?: () => number;
+}
+/**
+ * Gate for consulting the classifier. Pure. True only when the heuristic
+ * marked the classification low-confidence AND the draft is long enough to
+ * classify meaningfully. Uses display width (string-width), matching the
+ * editor's completion gate — a 2-char CJK draft at the default `minChars=4`
+ * displays 4 columns wide, reaches the LLM, and must also be classifiable.
+ */
+export declare function shouldConsultClassifier(confidence: "high" | "low" | undefined, draft: string, minChars: number): boolean;
+/** Truncated, trimmed draft the verdict cache keys on. Exported for tests. */
+export declare function verdictCacheKey(draft: string, keyPrefixLen: number): string;
+/** The classification question handed to the classifier model. Pure. */
+export declare function buildClassifierContext(draft: string): unknown;
+/** Parse `PI_GHOST_INTENT_CLASSIFIER_TIMEOUT_MS` (clamped to [50, 5000]). */
+export declare function classifierTimeoutFromEnv(raw: string | undefined, fallback: number): number;
+/** Parse `PI_GHOST_INTENT_CLASSIFIER_MIN_CONFIDENCE` (clamped to [0, 1]). */
+export declare function classifierMinConfidenceFromEnv(raw: string | undefined, fallback: number): number;
+/** Parse `PI_GHOST_INTENT_CLASSIFIER_DEBOUNCE_MS` (clamped to [0, 1000]). */
+export declare function classifierConsultDebounceFromEnv(raw: string | undefined, fallback: number): number;
+export declare class IntentClassifier {
+    readonly spec: string;
+    private readonly registry;
+    private readonly opts;
+    private readonly classifyFn;
+    /** Resolved classifier model (any provider), or null when unresolvable. */
+    private modelPromise;
+    private readonly verdicts;
+    private readonly pending;
+    /** Consult debounce: keystroke bursts collapse into one classify call. */
+    private consultTimer;
+    private consultDraft;
+    private constructor();
+    /**
+     * Build from a config spec. Returns null when disabled (`off`/empty),
+     * when the host registry has no `classify` (pi < 0.99), or — for an
+     * explicit `provider/model-id` spec — when the typed lookup methods are
+     * absent. Model *resolution* stays lazy: `auto` needs the async
+     * `getAvailableOfType`, so an unavailable model degrades per-consult
+     * (no verdict) rather than disabling the feature at startup.
+     */
+    static create(spec: string, registry: unknown, opts?: Partial<IntentClassifierOptions>): IntentClassifier | null;
+    /** Resolve (once) the classifier model the spec names or auto-picks. */
+    private resolveModel;
+    private doResolveModel;
+    /**
+     * Fire-and-forget consult request. Rapid calls (one per keystroke)
+     * collapse into a single classify on the latest draft after
+     * {@link IntentClassifierOptions.consultDebounceMs} of quiet — the
+     * pending-set alone cannot dedupe because every keystroke changes the
+     * cache key. Never blocks, never throws.
+     */
+    maybeConsult(draft: string): void;
+    private fireConsult;
+    private storeVerdict;
+    /**
+     * Fresh verdict for the draft's cache key, or null. Prefix-aware: a
+     * verdict consulted on an earlier prefix of the same line applies as
+     * the line grows (and, symmetrically, after backspacing into it), so
+     * the classification of a line's opening sticks without re-consulting
+     * per keystroke. Strong-classification gating in the editor bounds any
+     * stale-prefix reuse.
+     */
+    verdictFor(draft: string): CompletionRegister | null;
+    /** Number of live verdicts — surfaced in `/ghost` diagnostics. */
+    get verdictCount(): number;
+}

package/dist/intent.d.ts

@@ -221,6 +221,18 @@ export interface IntentClassification {
     intent: PromptIntent;
     register: CompletionRegister;
     proseReason?: ProseReason;
+    /**
+     * Heuristic signal strength (track C). `"low"` marks the two weak spots
+     * of the regex pipeline — single-line prose (persona split between
+     * `general-prose` and `agent-message` is guesswork below 4 lines of
+     * context) and the final fallback `instruction` (no verb, marker, or
+     * question shape matched — the draft could equally be code like
+     * `npm install`). The editor consults the optional intent classifier
+     * (pi ≥ 0.99 `registry.classify`, e.g. Jev or a llama.cpp classifier)
+     * only for `"low"` classifications, so strong signals never pay the
+     * round-trip. Absent means `"high"` (pre-track-C callers).
+     */
+    confidence?: "high" | "low";
 }
 /**
  * Detailed variant of `classifyPromptIntent`. Same classification order,

package/dist/providers/pi-model-provider.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { EmptyReason } from "../metrics.js";
+import type { PiModelProviderConfig } from "../config.js";
+import { type GhostProvider, type GhostRequest, type StreamDelta } from "./types.js";
+/**
+ * Pi-registry backend: complete through the session's own `ModelRegistry`.
+ *
+ * Unlike {@link CloudProvider} — which can only resolve models from pi-ai's
+ * *static builtin* catalog and must hand-resolve auth (skipping registries
+ * with a custom `baseUrl`) — this backend delegates both concerns to pi:
+ *
+ *  - **Model resolution** via `registry.find(provider, id)` / first match in
+ *    `registry.getAvailable()`. Works for dynamic providers (e.g. "radius")
+ *    and any model registered by other extensions, none of which exist in
+ *    the static catalog.
+ *  - **Auth + endpoint** via `registry.complete()`, which resolves
+ *    request-time auth (models.json keys, stored credentials, OAuth) and the
+ *    provider's real `baseUrl` exactly as the main agent sees them
+ *    (`ModelRuntime.prepareRequest`). No ghost API key needed.
+ *
+ * Available on pi 0.84+; streaming additionally requires 0.99's
+ * `registry.stream` (feature-detected, falls back to the pipeline's
+ * non-streaming `predict()` path on 0.84).
+ */
+export declare class PiModelProvider implements GhostProvider {
+    readonly name: string;
+    private readonly registry;
+    private readonly config;
+    private readonly streamFn;
+    private resolved;
+    private resolvedSpec;
+    private lastEmpty;
+    /**
+     * Streaming variant — attached in the constructor **only** when the
+     * registry exposes `stream()` (pi ≥ 0.99). The request pipeline selects
+     * the streaming path whenever `predictStream` is present, so a class
+     * method would make every host look streaming-capable and silently starve
+     * pi 0.84–0.98 of ghosts instead of falling back to `predict()`.
+     */
+    predictStream?: (req: GhostRequest) => AsyncIterable<StreamDelta>;
+    constructor(config: PiModelProviderConfig, registry: ModelRegistry);
+    get debounceMs(): number;
+    consumeLastEmptyReason(): EmptyReason | null;
+    /**
+     * Resolve `modelSpec` (`"provider/model-id"` or bare `"model-id"`) to a
+     * registry model. Successful lookups are cached per spec; failures retry
+     * on the next call (the registry may still be loading models.json early
+     * in a session, and a failed scan of the model list is cheap).
+     */
+    private resolveModel;
+    /**
+     * One completion through the registry. Auth, headers, and endpoint are
+     * resolved by pi at request time; we only supply sampling knobs, the
+     * abort signal, and the SEC-3 timeout.
+     */
+    predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * Streaming implementation behind the conditionally-attached
+     * {@link predictStream} — only reachable when the registry exposes
+     * `stream()` (pi ≥ 0.99; see {@link StreamingRegistry}). Mirrors
+     * {@link CloudProvider.predictStream}: sanitize once on the final
+     * assembled text, never per delta.
+     */
+    private streamPredict;
+    /**
+     * Preflight for /ghost diagnostics and router chat-leg warnings: resolves
+     * the spec and (when the registry supports it) checks that the model's
+     * provider has configured auth.
+     */
+    preflight(): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+}