@shrkcrft/ai 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/ai-request.d.ts

@@ -13,6 +13,16 @@ export interface IAiRequest {
     maxTokens?: number;
     temperature?: number;
     context?: string;
+    responseFormat?: IAiResponseFormat;
+    /**
+     * Optional callback invoked with each newly-decoded token chunk as
+     * generation streams in. Providers that don't natively stream
+     * (HTTP Gemini / Claude in our non-SSE adapter) ignore this; the
+     * llamacpp provider forwards chunks live. Useful for stderr "live
+     * preview" in CLI commands and for an agent who wants to display
+     * progress without the synchronous wait.
+     */
+    onTokenStream?: (chunk: string) => void;
 }
 export interface IAiResponse {
     content: string;
@@ -30,4 +40,9 @@ export interface IAiProviderConfig {
     model?: string;
     timeoutMs?: number;
 }
+export interface IAiResponseFormat {
+    type: 'json_object' | 'json_schema';
+    schema?: Record<string, unknown>;
+    schemaName?: string;
+}
 //# sourceMappingURL=ai-request.d.ts.map

package/dist/ai-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-request.d.ts","sourceRoot":"","sources":["../src/ai-request.ts"],"names":[],"mappings":"AAAA,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"ai-request.d.ts","sourceRoot":"","sources":["../src/ai-request.ts"],"names":[],"mappings":"AAAA,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,iBAAiB,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/gemini/gemini-provider.d.ts

@@ -0,0 +1,24 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import { AbstractAiProvider } from '../ai-provider.js';
+import { type IAiRequest, type IAiResponse } from '../ai-request.js';
+/**
+ * HTTP adapter for Google's Gemini (Generative Language API).
+ *
+ * Reads `GEMINI_API_KEY` from env (or `IAiProviderConfig.apiKey`). When
+ * the key is missing `isReady()` returns false and `send()` reports an
+ * actionable error — same contract as `ClaudeProvider`.
+ *
+ * The Gemini REST surface differs from Anthropic's: system messages are
+ * passed as a top-level `systemInstruction`, conversation turns become
+ * `contents[]` with roles `user`/`model`, and the response token cap is
+ * `generationConfig.maxOutputTokens` (not `max_tokens`). This adapter
+ * translates the provider-neutral `IAiRequest` shape into that wire
+ * format and back.
+ */
+export declare class GeminiProvider extends AbstractAiProvider {
+    readonly id = "gemini";
+    readonly name = "Google Gemini (HTTP)";
+    isReady(): boolean;
+    send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+}
+//# sourceMappingURL=gemini-provider.d.ts.map

package/dist/gemini/gemini-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-provider.d.ts","sourceRoot":"","sources":["../../src/gemini/gemini-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAErG;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,EAAE,YAAY;IACvB,QAAQ,CAAC,IAAI,0BAA0B;IAEvC,OAAO,IAAI,OAAO;IAIZ,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;CAyExE"}

package/dist/gemini/gemini-provider.js

@@ -0,0 +1,97 @@
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { AbstractAiProvider } from "../ai-provider.js";
+import { AiMessageRole } from "../ai-request.js";
+/**
+ * HTTP adapter for Google's Gemini (Generative Language API).
+ *
+ * Reads `GEMINI_API_KEY` from env (or `IAiProviderConfig.apiKey`). When
+ * the key is missing `isReady()` returns false and `send()` reports an
+ * actionable error — same contract as `ClaudeProvider`.
+ *
+ * The Gemini REST surface differs from Anthropic's: system messages are
+ * passed as a top-level `systemInstruction`, conversation turns become
+ * `contents[]` with roles `user`/`model`, and the response token cap is
+ * `generationConfig.maxOutputTokens` (not `max_tokens`). This adapter
+ * translates the provider-neutral `IAiRequest` shape into that wire
+ * format and back.
+ */
+export class GeminiProvider extends AbstractAiProvider {
+    id = 'gemini';
+    name = 'Google Gemini (HTTP)';
+    isReady() {
+        return Boolean(this.config.apiKey ?? process.env.GEMINI_API_KEY);
+    }
+    async send(request) {
+        const apiKey = this.config.apiKey ?? process.env.GEMINI_API_KEY;
+        if (!apiKey) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'GEMINI_API_KEY is not set — cannot reach Gemini', { suggestion: 'Put GEMINI_API_KEY=... in .env or `export GEMINI_API_KEY=...`' }));
+        }
+        const baseUrl = this.config.baseUrl ?? 'https://generativelanguage.googleapis.com';
+        const model = request.model ?? this.config.model ?? 'gemini-2.5-flash';
+        const maxTokens = request.maxTokens ?? 4096;
+        const systemInstructionText = collectSystem(request.messages);
+        const contents = collectContents(request.messages);
+        const body = {
+            contents,
+            generationConfig: {
+                maxOutputTokens: maxTokens,
+                ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+                ...(request.responseFormat
+                    ? {
+                        responseMimeType: 'application/json',
+                    }
+                    : {}),
+            },
+        };
+        if (systemInstructionText) {
+            body.systemInstruction = { role: 'system', parts: [{ text: systemInstructionText }] };
+        }
+        try {
+            const url = `${baseUrl}/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Gemini API ${res.status}: ${text.slice(0, 500)}`));
+            }
+            const json = (await res.json());
+            const content = (json.candidates?.[0]?.content?.parts ?? [])
+                .map((p) => (typeof p.text === 'string' ? p.text : ''))
+                .join('');
+            return ok({
+                content,
+                model: json.modelVersion ?? model,
+                finishReason: json.candidates?.[0]?.finishReason,
+                usage: {
+                    inputTokens: json.usageMetadata?.promptTokenCount,
+                    outputTokens: json.usageMetadata?.candidatesTokenCount,
+                },
+                raw: json,
+            });
+        }
+        catch (e) {
+            return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Failed to call Gemini: ${e.message}`, {
+                cause: e,
+            }));
+        }
+    }
+}
+function collectSystem(messages) {
+    const parts = messages.filter((m) => m.role === AiMessageRole.System).map((m) => m.content);
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+function collectContents(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === AiMessageRole.System)
+            continue;
+        out.push({
+            role: m.role === AiMessageRole.Assistant ? 'model' : 'user',
+            parts: [{ text: m.content }],
+        });
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -3,4 +3,9 @@ export * from './ai-request.js';
 export * from './prompt/prompt-builder.js';
 export * from './claude/claude-provider.js';
 export * from './claude/claude-cli-adapter.js';
+export * from './gemini/gemini-provider.js';
+export * from './ollama/ollama-provider.js';
+export * from './llamacpp/llama-cpp-provider.js';
+export * from './provider-resolver.js';
+export * from './pipeline/enhancement-pipeline.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC"}

package/dist/index.js

@@ -3,3 +3,8 @@ export * from "./ai-request.js";
 export * from "./prompt/prompt-builder.js";
 export * from "./claude/claude-provider.js";
 export * from "./claude/claude-cli-adapter.js";
+export * from "./gemini/gemini-provider.js";
+export * from "./ollama/ollama-provider.js";
+export * from "./llamacpp/llama-cpp-provider.js";
+export * from "./provider-resolver.js";
+export * from "./pipeline/enhancement-pipeline.js";

package/dist/llamacpp/llama-cpp-provider.d.ts

@@ -0,0 +1,56 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import { AbstractAiProvider } from '../ai-provider.js';
+import { type IAiRequest, type IAiResponse } from '../ai-request.js';
+/**
+ * In-process generative provider backed by `node-llama-cpp` (a Node
+ * binding for llama.cpp). No HTTP. No daemon. The model is loaded
+ * once into process memory and reused across requests.
+ *
+ * Configuration (env or `IAiProviderConfig`):
+ *   - `LLAMACPP_MODEL_PATH`   — absolute or repo-relative path to a
+ *                               local `.gguf` file. If unset, the
+ *                               provider is `isReady() === false`.
+ *   - `LLAMACPP_CONTEXT_SIZE` — context window in tokens (default 8192).
+ *   - `LLAMACPP_GPU`          — `auto` (default) | `metal` | `cuda` | `off`.
+ *
+ * The first `send()` call pays the model-load cost (typically 1–10 s
+ * for a 3B Q4 model on Apple Silicon). Subsequent calls reuse
+ * the same `LlamaModel` + `LlamaContext`. A fresh `LlamaChatSession`
+ * is created per request so context isn't leaked between unrelated
+ * tasks.
+ *
+ * Tests can inject a fake generator via `_overrideForTests` to avoid
+ * pulling in the native binding and a 2 GB model file.
+ */
+export declare class LlamaCppProvider extends AbstractAiProvider {
+    readonly id = "llamacpp";
+    readonly name = "llama.cpp (in-process)";
+    /** Test hook — bypasses the native binding when set. */
+    static _overrideForTests: ((request: IAiRequest, modelPath: string) => Promise<IAiResponse>) | null;
+    /**
+     * Reads the module-level cache to expose the active model path for
+     * tools that need it (mostly the disposer). Returns null when no
+     * model has been loaded in this process.
+     */
+    static activeModelPath(): string | null;
+    isReady(): boolean;
+    send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+    private ensureLoaded;
+}
+/**
+ * Release the loaded llama.cpp model + context so the process can
+ * exit cleanly.
+ *
+ * Without this, the libc++ destructor for the Metal device list
+ * aborts on `exit()` with `ggml_metal_device_free` because the
+ * device list isn't empty — same shape of teardown crash as the
+ * ONNX mutex issue, different native library. Disposing in the
+ * order session → context → model → llama lets the destructors
+ * run while the JS runtime is still healthy.
+ *
+ * Safe to call multiple times. Safe to call when no model was
+ * loaded. Errors during dispose are swallowed (the alternative is
+ * the abort we're trying to prevent).
+ */
+export declare function disposeLlamaCppRuntime(): Promise<void>;
+//# sourceMappingURL=llama-cpp-provider.d.ts.map

package/dist/llamacpp/llama-cpp-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llama-cpp-provider.d.ts","sourceRoot":"","sources":["../../src/llamacpp/llama-cpp-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKrG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB;IACtD,QAAQ,CAAC,EAAE,cAAc;IACzB,QAAQ,CAAC,IAAI,4BAA4B;IAEzC,wDAAwD;IACxD,MAAM,CAAC,iBAAiB,EACpB,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,GAClE,IAAI,CAAQ;IAEhB;;;;OAIG;IACH,MAAM,CAAC,eAAe,IAAI,MAAM,GAAG,IAAI;IAIvC,OAAO,IAAI,OAAO;IAIZ,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;YA4IzD,YAAY;CAwB3B;AAWD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAU5D"}

package/dist/llamacpp/llama-cpp-provider.js

@@ -0,0 +1,268 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { AbstractAiProvider } from "../ai-provider.js";
+import { AiMessageRole } from "../ai-request.js";
+const DEFAULT_CONTEXT_SIZE = 8192;
+const DEFAULT_MAX_TOKENS = 1024;
+/**
+ * In-process generative provider backed by `node-llama-cpp` (a Node
+ * binding for llama.cpp). No HTTP. No daemon. The model is loaded
+ * once into process memory and reused across requests.
+ *
+ * Configuration (env or `IAiProviderConfig`):
+ *   - `LLAMACPP_MODEL_PATH`   — absolute or repo-relative path to a
+ *                               local `.gguf` file. If unset, the
+ *                               provider is `isReady() === false`.
+ *   - `LLAMACPP_CONTEXT_SIZE` — context window in tokens (default 8192).
+ *   - `LLAMACPP_GPU`          — `auto` (default) | `metal` | `cuda` | `off`.
+ *
+ * The first `send()` call pays the model-load cost (typically 1–10 s
+ * for a 3B Q4 model on Apple Silicon). Subsequent calls reuse
+ * the same `LlamaModel` + `LlamaContext`. A fresh `LlamaChatSession`
+ * is created per request so context isn't leaked between unrelated
+ * tasks.
+ *
+ * Tests can inject a fake generator via `_overrideForTests` to avoid
+ * pulling in the native binding and a 2 GB model file.
+ */
+export class LlamaCppProvider extends AbstractAiProvider {
+    id = 'llamacpp';
+    name = 'llama.cpp (in-process)';
+    /** Test hook — bypasses the native binding when set. */
+    static _overrideForTests = null;
+    /**
+     * Reads the module-level cache to expose the active model path for
+     * tools that need it (mostly the disposer). Returns null when no
+     * model has been loaded in this process.
+     */
+    static activeModelPath() {
+        return sharedLlamaState?.modelPath ?? null;
+    }
+    isReady() {
+        return resolveModelPath(this.config.model) !== null;
+    }
+    async send(request) {
+        const modelPath = resolveModelPath(request.model ?? this.config.model);
+        if (modelPath === null) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'LLAMACPP_MODEL_PATH is not set or the file does not exist.', {
+                suggestion: 'Set LLAMACPP_MODEL_PATH=/path/to/qwen2.5-coder-3b.gguf in .env, or pass --model <path> on the CLI.',
+            }));
+        }
+        if (LlamaCppProvider._overrideForTests) {
+            try {
+                const value = await LlamaCppProvider._overrideForTests(request, modelPath);
+                return ok(value);
+            }
+            catch (e) {
+                return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Test override failed: ${e.message}`, {
+                    cause: e,
+                }));
+            }
+        }
+        try {
+            const tf = (await import('node-llama-cpp'));
+            const { LlamaChatSession } = tf;
+            const { model, context } = await this.ensureLoaded(modelPath);
+            const sequence = context.getSequence();
+            const session = new LlamaChatSession({
+                contextSequence: sequence,
+                systemPrompt: collectSystemPrompt(request.messages),
+            });
+            // Prior assistant/user turns get fed into the session in order so
+            // the model sees the conversation history. The trailing user turn
+            // is what we ask `prompt()` to respond to.
+            const turns = nonSystemTurns(request.messages);
+            for (let i = 0; i < turns.length - 1; i += 1) {
+                const turn = turns[i];
+                if (turn.role === AiMessageRole.Assistant) {
+                    // node-llama-cpp 3.x exposes session.addAssistantMessage in some
+                    // versions; older versions don't. Best effort: skip silently.
+                    const fn = session.addAssistantMessage;
+                    if (typeof fn === 'function')
+                        fn.call(session, turn.content);
+                    continue;
+                }
+                // For user turns that aren't the trailing one, prime them so the
+                // assistant response gets folded back into the context too.
+                await session.prompt(turn.content, {
+                    maxTokens: 1,
+                    stopOnAbortSignal: true,
+                });
+            }
+            const lastUser = turns[turns.length - 1];
+            const userPrompt = lastUser && lastUser.role === AiMessageRole.User ? lastUser.content : '';
+            const maxTokens = request.maxTokens ?? DEFAULT_MAX_TOKENS;
+            const wantsJson = !!request.responseFormat;
+            // When the caller wants JSON, ask llama.cpp to enforce it at
+            // sample time via a grammar. This eliminates a whole class of
+            // parse failures (preamble prose, trailing markdown, runaway
+            // continuation) that small models routinely produce. Best effort:
+            // if the grammar constructor isn't available in this version we
+            // fall back to plain prompting + trim.
+            let grammar = undefined;
+            if (wantsJson) {
+                try {
+                    const Ctor = tf.LlamaJsonSchemaGrammar;
+                    // CRITICAL: pass the *same* Llama instance the model was
+                    // loaded with. node-llama-cpp rejects mixing grammars from
+                    // one instance with a session from another ("The
+                    // LlamaGrammar … was created with a different Llama
+                    // instance"). Calling getLlama() again would also leak a
+                    // second native Metal device, which then crashes the
+                    // process on exit (`ggml_metal_device_free`).
+                    const sharedLlama = sharedLlamaState?.llama;
+                    if (Ctor && request.responseFormat?.schema && sharedLlama) {
+                        grammar = new Ctor(sharedLlama, request.responseFormat.schema);
+                    }
+                }
+                catch {
+                    grammar = undefined;
+                }
+            }
+            const start = Date.now();
+            const onChunk = request.onTokenStream;
+            const text = await session.prompt(userPrompt, {
+                maxTokens,
+                ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+                ...(wantsJson ? { trimWhitespaceSuffix: true } : {}),
+                ...(grammar ? { grammar: grammar } : {}),
+                ...(onChunk
+                    ? {
+                        onTextChunk: (chunk) => {
+                            try {
+                                onChunk(chunk);
+                            }
+                            catch {
+                                // never let a callback failure break inference
+                            }
+                        },
+                    }
+                    : {}),
+            });
+            const elapsedMs = Date.now() - start;
+            // Release the LlamaContext sequence so the next send() can take it.
+            // Without this we hit "No sequences left" on the second call. The
+            // LlamaModel + LlamaContext themselves stay loaded across calls.
+            const sessionDisposable = session;
+            if (typeof sessionDisposable.dispose === 'function')
+                sessionDisposable.dispose();
+            const seqDisposable = sequence;
+            if (typeof seqDisposable.dispose === 'function')
+                seqDisposable.dispose();
+            return ok({
+                content: text,
+                model: nodePath.basename(modelPath),
+                finishReason: 'stop',
+                usage: {
+                // node-llama-cpp does not surface input/output token counts in a
+                // stable v3 API path; we leave usage undefined and let callers
+                // approximate from char count if needed.
+                },
+                raw: { backend: 'node-llama-cpp', modelPath, elapsedMs },
+            });
+        }
+        catch (e) {
+            return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `node-llama-cpp call failed: ${e.message}`, {
+                cause: e,
+                suggestion: 'Verify LLAMACPP_MODEL_PATH points to a valid .gguf file readable by llama.cpp.',
+            }));
+        }
+    }
+    async ensureLoaded(modelPath) {
+        // Cached at MODULE scope so the disposer can find it on process
+        // exit. (Per-instance caching used to live here, but the disposer
+        // doesn't know which provider instance to ask.)
+        if (sharedLlamaState && sharedLlamaState.modelPath === modelPath) {
+            return { model: sharedLlamaState.model, context: sharedLlamaState.context };
+        }
+        if (sharedLlamaState) {
+            // Different model requested — tear down the old one before
+            // loading a new one. Best-effort; failures are tolerated.
+            await disposeLlamaCppRuntime();
+        }
+        const { getLlama } = (await import('node-llama-cpp'));
+        const llama = await getLlama({
+            gpu: resolveGpuChoice(this.config.baseUrl),
+        });
+        const model = await llama.loadModel({ modelPath });
+        const contextSize = Number.isFinite(this.config.timeoutMs)
+            ? DEFAULT_CONTEXT_SIZE
+            : Number(process.env.LLAMACPP_CONTEXT_SIZE ?? DEFAULT_CONTEXT_SIZE);
+        const context = await model.createContext({ contextSize });
+        sharedLlamaState = { llama, model, context, modelPath };
+        return { model, context };
+    }
+}
+let sharedLlamaState = null;
+/**
+ * Release the loaded llama.cpp model + context so the process can
+ * exit cleanly.
+ *
+ * Without this, the libc++ destructor for the Metal device list
+ * aborts on `exit()` with `ggml_metal_device_free` because the
+ * device list isn't empty — same shape of teardown crash as the
+ * ONNX mutex issue, different native library. Disposing in the
+ * order session → context → model → llama lets the destructors
+ * run while the JS runtime is still healthy.
+ *
+ * Safe to call multiple times. Safe to call when no model was
+ * loaded. Errors during dispose are swallowed (the alternative is
+ * the abort we're trying to prevent).
+ */
+export async function disposeLlamaCppRuntime() {
+    const state = sharedLlamaState;
+    sharedLlamaState = null;
+    if (!state)
+        return;
+    // Context first — it holds the sequence pool that depends on the model.
+    await callMaybeDispose(state.context);
+    // Then the model, which depends on the llama runtime.
+    await callMaybeDispose(state.model);
+    // Finally the Llama instance itself (releases the Metal device).
+    await callMaybeDispose(state.llama);
+}
+async function callMaybeDispose(target) {
+    if (!target || typeof target !== 'object')
+        return;
+    const maybe = target;
+    if (typeof maybe.dispose !== 'function')
+        return;
+    try {
+        const r = maybe.dispose();
+        if (r && typeof r.then === 'function') {
+            await r.catch(() => undefined);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+function resolveModelPath(explicit) {
+    const envPath = process.env.LLAMACPP_MODEL_PATH;
+    const candidate = explicit && explicit.length > 0 ? explicit : envPath;
+    if (!candidate)
+        return null;
+    if (nodePath.isAbsolute(candidate)) {
+        return existsSync(candidate) ? candidate : null;
+    }
+    const fromCwd = nodePath.resolve(process.cwd(), candidate);
+    return existsSync(fromCwd) ? fromCwd : null;
+}
+function resolveGpuChoice(_baseUrl) {
+    const choice = (process.env.LLAMACPP_GPU ?? 'auto').trim().toLowerCase();
+    if (choice === 'metal')
+        return 'metal';
+    if (choice === 'cuda')
+        return 'cuda';
+    if (choice === 'off' || choice === 'false' || choice === 'no' || choice === 'cpu')
+        return false;
+    return 'auto';
+}
+function collectSystemPrompt(messages) {
+    const parts = messages.filter((m) => m.role === AiMessageRole.System).map((m) => m.content);
+    return parts.join('\n\n');
+}
+function nonSystemTurns(messages) {
+    return messages.filter((m) => m.role !== AiMessageRole.System);
+}

package/dist/ollama/ollama-provider.d.ts

@@ -0,0 +1,47 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import { AbstractAiProvider } from '../ai-provider.js';
+import { type IAiRequest, type IAiResponse } from '../ai-request.js';
+/**
+ * HTTP adapter for a local Ollama instance (https://ollama.com).
+ *
+ * Unlike Gemini/Claude, Ollama is host-based and does not need an API
+ * key — `isReady()` is always true; the actual reachability check is
+ * deferred to `send()`. The host is picked from `OLLAMA_HOST` (or the
+ * provider config). Two forms are accepted:
+ *   - A full URL, e.g. `OLLAMA_HOST=http://my-box:11434`.
+ *   - A bare hostname (or IP) when paired with `OLLAMA_PORT`, e.g.
+ *     `OLLAMA_HOST=my-box` + `OLLAMA_PORT=11434`. The URL is assembled
+ *     as `http://<host>:<port>`.
+ * Falls back to `http://localhost:11434`. The default model comes from
+ * `OLLAMA_MODEL` and may be overridden per request.
+ *
+ * Wire format: `POST /api/chat` with `{model, messages, stream:false,
+ * format?, options}`. The provider-neutral `IAiMessage` roles map
+ * directly onto Ollama roles. When `responseFormat` is supplied we ask
+ * Ollama for structured output — newer servers accept a JSON-schema
+ * object as `format`, older servers fall back to `format: "json"`.
+ */
+export declare class OllamaProvider extends AbstractAiProvider {
+    readonly id = "ollama";
+    readonly name = "Ollama (local HTTP)";
+    isReady(): boolean;
+    /**
+     * One-shot preflight against `GET /api/tags`.
+     *
+     * Why this exists: Ollama is the one provider whose readiness is
+     * decoupled from env (the daemon may be down, the model may not be
+     * pulled). The two-stage planner calls this *before* stage 1 so it
+     * can fail with `ollama serve` / `ollama pull <model>` hints instead
+     * of a confusing network error mid-call.
+     *
+     * `requireModel` (optional) is checked against the server's tag list
+     * and reported separately so the caller can build a precise hint.
+     */
+    healthCheck(requireModel?: string): Promise<Result<{
+        host: string;
+        models: string[];
+        modelPresent: boolean | null;
+    }, AppError>>;
+    send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+}
+//# sourceMappingURL=ollama-provider.d.ts.map

package/dist/ollama/ollama-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama-provider.d.ts","sourceRoot":"","sources":["../../src/ollama/ollama-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,EAAE,YAAY;IACvB,QAAQ,CAAC,IAAI,yBAAyB;IAEtC,OAAO,IAAI,OAAO;IAIlB;;;;;;;;;;;OAWG;IACG,WAAW,CACf,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,EAAE,QAAQ,CAAC,CAAC;IA+BxF,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;CAkExE"}

package/dist/ollama/ollama-provider.js

@@ -0,0 +1,166 @@
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { AbstractAiProvider } from "../ai-provider.js";
+import { AiMessageRole } from "../ai-request.js";
+const DEFAULT_OLLAMA_HOST = 'http://localhost:11434';
+const DEFAULT_OLLAMA_MODEL = 'llama3.1';
+const DEFAULT_OLLAMA_PORT = 11434;
+/**
+ * HTTP adapter for a local Ollama instance (https://ollama.com).
+ *
+ * Unlike Gemini/Claude, Ollama is host-based and does not need an API
+ * key — `isReady()` is always true; the actual reachability check is
+ * deferred to `send()`. The host is picked from `OLLAMA_HOST` (or the
+ * provider config). Two forms are accepted:
+ *   - A full URL, e.g. `OLLAMA_HOST=http://my-box:11434`.
+ *   - A bare hostname (or IP) when paired with `OLLAMA_PORT`, e.g.
+ *     `OLLAMA_HOST=my-box` + `OLLAMA_PORT=11434`. The URL is assembled
+ *     as `http://<host>:<port>`.
+ * Falls back to `http://localhost:11434`. The default model comes from
+ * `OLLAMA_MODEL` and may be overridden per request.
+ *
+ * Wire format: `POST /api/chat` with `{model, messages, stream:false,
+ * format?, options}`. The provider-neutral `IAiMessage` roles map
+ * directly onto Ollama roles. When `responseFormat` is supplied we ask
+ * Ollama for structured output — newer servers accept a JSON-schema
+ * object as `format`, older servers fall back to `format: "json"`.
+ */
+export class OllamaProvider extends AbstractAiProvider {
+    id = 'ollama';
+    name = 'Ollama (local HTTP)';
+    isReady() {
+        return true;
+    }
+    /**
+     * One-shot preflight against `GET /api/tags`.
+     *
+     * Why this exists: Ollama is the one provider whose readiness is
+     * decoupled from env (the daemon may be down, the model may not be
+     * pulled). The two-stage planner calls this *before* stage 1 so it
+     * can fail with `ollama serve` / `ollama pull <model>` hints instead
+     * of a confusing network error mid-call.
+     *
+     * `requireModel` (optional) is checked against the server's tag list
+     * and reported separately so the caller can build a precise hint.
+     */
+    async healthCheck(requireModel) {
+        const baseUrl = resolveBaseUrl(this.config.baseUrl);
+        try {
+            const res = await fetch(`${baseUrl}/api/tags`, { method: 'GET' });
+            if (!res.ok) {
+                return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Ollama health-check failed at ${baseUrl}/api/tags (HTTP ${res.status})`, { suggestion: `Is OLLAMA_HOST correct? Currently ${baseUrl}.` }));
+            }
+            const json = (await res.json());
+            const models = (json.models ?? []).map((m) => m.name ?? '').filter((n) => n.length > 0);
+            const modelPresent = requireModel ? models.includes(requireModel) : null;
+            return ok({ host: baseUrl, models, modelPresent });
+        }
+        catch (e) {
+            return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Cannot reach Ollama at ${baseUrl}: ${e.message}`, {
+                cause: e,
+                suggestion: `Start the daemon (\`ollama serve\`) or set OLLAMA_HOST to a reachable instance.`,
+            }));
+        }
+    }
+    async send(request) {
+        const baseUrl = resolveBaseUrl(this.config.baseUrl);
+        const model = request.model ?? this.config.model ?? process.env.OLLAMA_MODEL ?? DEFAULT_OLLAMA_MODEL;
+        const maxTokens = request.maxTokens ?? 4096;
+        const messages = request.messages.map((m) => ({
+            role: roleFor(m.role),
+            content: m.content,
+        }));
+        const body = {
+            model,
+            messages,
+            stream: false,
+            options: {
+                num_predict: maxTokens,
+                ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+            },
+        };
+        const format = formatFor(request.responseFormat);
+        if (format !== undefined)
+            body.format = format;
+        try {
+            const res = await fetch(`${baseUrl}/api/chat`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Ollama API ${res.status}: ${text.slice(0, 500)}`, {
+                    suggestion: `Check OLLAMA_HOST (currently ${baseUrl}) and that the model "${model}" is pulled (\`ollama pull ${model}\`).`,
+                }));
+            }
+            const json = (await res.json());
+            const content = json.message?.content ?? '';
+            return ok({
+                content,
+                model: json.model ?? model,
+                finishReason: json.done_reason,
+                usage: {
+                    inputTokens: json.prompt_eval_count,
+                    outputTokens: json.eval_count,
+                },
+                raw: json,
+            });
+        }
+        catch (e) {
+            return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Failed to call Ollama at ${baseUrl}: ${e.message}`, {
+                cause: e,
+                suggestion: `Is Ollama running? Try \`ollama serve\` or set OLLAMA_HOST to a reachable instance.`,
+            }));
+        }
+    }
+}
+function roleFor(role) {
+    if (role === AiMessageRole.System)
+        return 'system';
+    if (role === AiMessageRole.Assistant)
+        return 'assistant';
+    return 'user';
+}
+function formatFor(responseFormat) {
+    if (!responseFormat)
+        return undefined;
+    if (responseFormat.type === 'json_schema' && responseFormat.schema) {
+        return responseFormat.schema;
+    }
+    return 'json';
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+/**
+ * Resolve the Ollama base URL from config + env. Accepts:
+ *   - An explicit base URL on the provider config (`baseUrl`).
+ *   - `OLLAMA_HOST` as a full URL (`http://my-box:11434`).
+ *   - `OLLAMA_HOST` as a bare host (`my-box`) paired with
+ *     `OLLAMA_PORT` (default 11434 if only host is given).
+ *   - Falls back to `http://localhost:11434`.
+ *
+ * Why split host/port: lets the user point at a remote Ollama with two
+ * dotenv entries instead of having to remember the URL form. Both
+ * styles coexist; if `OLLAMA_HOST` already contains a scheme we keep
+ * it verbatim and ignore `OLLAMA_PORT` (the URL is authoritative).
+ */
+function resolveBaseUrl(configBaseUrl) {
+    if (configBaseUrl && configBaseUrl.length > 0) {
+        return stripTrailingSlash(configBaseUrl);
+    }
+    const rawHost = (process.env.OLLAMA_HOST ?? '').trim();
+    const rawPort = (process.env.OLLAMA_PORT ?? '').trim();
+    if (rawHost.length === 0 && rawPort.length === 0) {
+        return DEFAULT_OLLAMA_HOST;
+    }
+    if (rawHost.length > 0 && /^https?:\/\//i.test(rawHost)) {
+        // Full URL form takes precedence — OLLAMA_PORT is intentionally
+        // ignored so users can't end up with two conflicting sources of
+        // truth.
+        return stripTrailingSlash(rawHost);
+    }
+    const host = rawHost.length > 0 ? rawHost : 'localhost';
+    const port = rawPort.length > 0 ? rawPort : String(DEFAULT_OLLAMA_PORT);
+    return `http://${host}:${port}`;
+}

package/dist/pipeline/enhancement-pipeline.d.ts

@@ -0,0 +1,123 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IAiProvider } from '../ai-provider.js';
+import { type IAiMessage } from '../ai-request.js';
+/**
+ * Identifier for a stage in the multi-pass enhancement pipeline.
+ *
+ * The default Claude-agent-oriented pipeline runs `draft → critique →
+ * refine → polish`. Callers may pass a custom stage list to truncate,
+ * extend, or rearrange the flow.
+ */
+export declare enum EnhancementStageKind {
+    Draft = "draft",
+    Critique = "critique",
+    Refine = "refine",
+    Polish = "polish"
+}
+export interface IEnhancementStageInput {
+    /** The deterministic ground truth assembled by the engine. */
+    originalContext: string;
+    /** The original user task / question. */
+    task: string;
+    /** Output of the previous stage (empty on the first stage). */
+    previous: string;
+    /** Output of the most recent `critique` stage, when relevant. */
+    lastCritique?: string;
+}
+export interface IEnhancementStage {
+    kind: EnhancementStageKind;
+    /**
+     * Build the messages the LLM should see for this stage. Stages stay
+     * pure — the orchestrator owns the provider, retries, and bookkeeping.
+     */
+    buildMessages(input: IEnhancementStageInput): IAiMessage[];
+}
+export interface IEnhancementStageResult {
+    kind: EnhancementStageKind;
+    content: string;
+    model: string;
+    /** Set when the stage failed and we kept the previous-stage output. */
+    degraded?: boolean;
+    errorMessage?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+export interface IEnhancementPipelineOptions {
+    /** Cap the pipeline depth — useful for cheap models. Default: all stages. */
+    maxPasses?: number;
+    /** Per-stage `maxTokens`. Default: 4096. */
+    maxTokensPerStage?: number;
+    /** Per-stage `temperature`. Default: 0.2 (deterministic-ish). */
+    temperature?: number;
+    /** Override the model selection (forwarded to the provider per call). */
+    model?: string;
+    /** Optional progress hook — called once per stage. */
+    onStage?: (event: {
+        kind: EnhancementStageKind;
+        ok: boolean;
+        pass: number;
+        total: number;
+    }) => void;
+}
+export interface IEnhancementPipelineRun {
+    /** Final enriched output. Always defined — falls back to `originalContext` when every stage failed. */
+    finalOutput: string;
+    /** Per-stage history (ordered). */
+    stages: IEnhancementStageResult[];
+    /** Aggregated token usage across stages (when reported by the provider). */
+    totalUsage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /**
+     * True when the pipeline could not call the LLM at all (no provider
+     * passed). The caller is expected to handle this case by returning
+     * the deterministic seed unchanged.
+     */
+    deterministicFallback: boolean;
+}
+/**
+ * Multi-pass refinement pipeline that turns a deterministic brief into
+ * a denser, more agent-ready artefact by making the LLM critique and
+ * rewrite its own work.
+ *
+ * Design contract:
+ *   - When no provider is supplied, the pipeline returns the
+ *     `originalContext` unchanged and flags `deterministicFallback`.
+ *     The deterministic engine remains the source of truth.
+ *   - When a provider is supplied, every stage call is retried-once on
+ *     failure; a permanently-failed stage degrades to the previous
+ *     stage's output (the pipeline never throws and never produces
+ *     less than the deterministic input).
+ *   - Stages compose: a caller can pass a 2-stage `[draft, polish]`
+ *     pipeline for fast paths, or extend with custom critique prompts
+ *     for project-specific quality bars.
+ *
+ * Why a pipeline (vs. a single rich prompt): small local models behave
+ * dramatically better when asked to "find the gaps in this draft" than
+ * when asked to "write the perfect brief in one shot". The critique
+ * pass surfaces vague claims and missing evidence; the refine pass
+ * fixes them; the polish pass enforces Claude-agent ergonomics
+ * (file:line refs, explicit next commands, terse bullets).
+ */
+export declare class EnhancementPipeline {
+    private readonly stages;
+    constructor(stages: ReadonlyArray<IEnhancementStage>);
+    run(input: {
+        task: string;
+        originalContext: string;
+    }, provider: IAiProvider | null, options?: IEnhancementPipelineOptions): Promise<Result<IEnhancementPipelineRun, AppError>>;
+}
+/**
+ * The default stage set for "make this brief more useful to the Claude
+ * agent". Tuned for small local models (Qwen2.5-Coder-3B, Llama-3.1-8B).
+ *
+ * Each stage's user message is intentionally short and concrete; the
+ * heavy lifting (the deterministic seed) lives in the system role
+ * and is reused verbatim across stages so the model never loses
+ * grounding.
+ */
+export declare function buildDefaultEnhancementStages(): IEnhancementStage[];
+//# sourceMappingURL=enhancement-pipeline.d.ts.map

package/dist/pipeline/enhancement-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhancement-pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/enhancement-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;;;;GAMG;AACH,oBAAY,oBAAoB;IAC9B,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,oBAAoB,CAAC;IAC3B;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,UAAU,EAAE,CAAC;CAC5D;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED,MAAM,WAAW,2BAA2B;IAC1C,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,oBAAoB,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACrG;AAED,MAAM,WAAW,uBAAuB;IACtC,uGAAuG;IACvG,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,4EAA4E;IAC5E,UAAU,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D;;;;OAIG;IACH,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAE9C,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC;IAI9C,GAAG,CACP,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,EAChD,QAAQ,EAAE,WAAW,GAAG,IAAI,EAC5B,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,QAAQ,CAAC,CAAC;CAmFtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,IAAI,iBAAiB,EAAE,CAOnE"}

package/dist/pipeline/enhancement-pipeline.js

@@ -0,0 +1,295 @@
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { AiMessageRole } from "../ai-request.js";
+/**
+ * Identifier for a stage in the multi-pass enhancement pipeline.
+ *
+ * The default Claude-agent-oriented pipeline runs `draft → critique →
+ * refine → polish`. Callers may pass a custom stage list to truncate,
+ * extend, or rearrange the flow.
+ */
+export var EnhancementStageKind;
+(function (EnhancementStageKind) {
+    EnhancementStageKind["Draft"] = "draft";
+    EnhancementStageKind["Critique"] = "critique";
+    EnhancementStageKind["Refine"] = "refine";
+    EnhancementStageKind["Polish"] = "polish";
+})(EnhancementStageKind || (EnhancementStageKind = {}));
+/**
+ * Multi-pass refinement pipeline that turns a deterministic brief into
+ * a denser, more agent-ready artefact by making the LLM critique and
+ * rewrite its own work.
+ *
+ * Design contract:
+ *   - When no provider is supplied, the pipeline returns the
+ *     `originalContext` unchanged and flags `deterministicFallback`.
+ *     The deterministic engine remains the source of truth.
+ *   - When a provider is supplied, every stage call is retried-once on
+ *     failure; a permanently-failed stage degrades to the previous
+ *     stage's output (the pipeline never throws and never produces
+ *     less than the deterministic input).
+ *   - Stages compose: a caller can pass a 2-stage `[draft, polish]`
+ *     pipeline for fast paths, or extend with custom critique prompts
+ *     for project-specific quality bars.
+ *
+ * Why a pipeline (vs. a single rich prompt): small local models behave
+ * dramatically better when asked to "find the gaps in this draft" than
+ * when asked to "write the perfect brief in one shot". The critique
+ * pass surfaces vague claims and missing evidence; the refine pass
+ * fixes them; the polish pass enforces Claude-agent ergonomics
+ * (file:line refs, explicit next commands, terse bullets).
+ */
+export class EnhancementPipeline {
+    stages;
+    constructor(stages) {
+        this.stages = stages;
+    }
+    async run(input, provider, options = {}) {
+        if (!provider) {
+            return ok({
+                finalOutput: input.originalContext,
+                stages: [],
+                totalUsage: { inputTokens: 0, outputTokens: 0 },
+                deterministicFallback: true,
+            });
+        }
+        const cap = options.maxPasses ?? this.stages.length;
+        const plan = this.stages.slice(0, Math.max(1, cap));
+        const stagesOut = [];
+        const totalUsage = { inputTokens: 0, outputTokens: 0 };
+        let previous = '';
+        let lastCritique;
+        let lastGood = input.originalContext;
+        for (let i = 0; i < plan.length; i += 1) {
+            const stage = plan[i];
+            const messages = stage.buildMessages({
+                originalContext: input.originalContext,
+                task: input.task,
+                previous,
+                lastCritique,
+            });
+            const stageResult = await callOnceWithRetry(provider, {
+                messages,
+                maxTokens: options.maxTokensPerStage ?? 4096,
+                temperature: options.temperature ?? 0.2,
+                ...(options.model ? { model: options.model } : {}),
+            });
+            const onStage = options.onStage;
+            if (!stageResult.ok) {
+                stagesOut.push({
+                    kind: stage.kind,
+                    content: lastGood,
+                    model: options.model ?? '',
+                    degraded: true,
+                    errorMessage: stageResult.error.message,
+                });
+                if (onStage)
+                    onStage({ kind: stage.kind, ok: false, pass: i + 1, total: plan.length });
+                // Stage failed: keep last-good output but allow the pipeline to
+                // continue. A failed `critique` is recoverable (`refine` just
+                // gets no critique). A failed `refine` falls back to the prior
+                // draft. A failed `polish` returns the refined draft.
+                previous = lastGood;
+                continue;
+            }
+            const content = (stageResult.value.content ?? '').trim();
+            const usage = stageResult.value.usage ?? {};
+            if (typeof usage.inputTokens === 'number')
+                totalUsage.inputTokens += usage.inputTokens;
+            if (typeof usage.outputTokens === 'number')
+                totalUsage.outputTokens += usage.outputTokens;
+            stagesOut.push({
+                kind: stage.kind,
+                content,
+                model: stageResult.value.model,
+                ...(usage.inputTokens || usage.outputTokens ? { usage } : {}),
+            });
+            if (stage.kind === EnhancementStageKind.Critique) {
+                lastCritique = content;
+                // Critique is not a candidate for `finalOutput` — keep the
+                // previous draft as the running best.
+            }
+            else {
+                previous = content;
+                lastGood = content;
+            }
+            if (onStage)
+                onStage({ kind: stage.kind, ok: true, pass: i + 1, total: plan.length });
+        }
+        return ok({
+            finalOutput: lastGood,
+            stages: stagesOut,
+            totalUsage,
+            deterministicFallback: false,
+        });
+    }
+}
+/**
+ * The default stage set for "make this brief more useful to the Claude
+ * agent". Tuned for small local models (Qwen2.5-Coder-3B, Llama-3.1-8B).
+ *
+ * Each stage's user message is intentionally short and concrete; the
+ * heavy lifting (the deterministic seed) lives in the system role
+ * and is reused verbatim across stages so the model never loses
+ * grounding.
+ */
+export function buildDefaultEnhancementStages() {
+    return [
+        new DraftStage(),
+        new CritiqueStage(),
+        new RefineStage(),
+        new PolishStage(),
+    ];
+}
+class DraftStage {
+    kind = EnhancementStageKind.Draft;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are SharkCraft, a deterministic, local-first code-intelligence engine.',
+                    'Your job is to write a concise, Claude-agent-ready brief for the supplied task.',
+                    'Treat the repository context below as the ONLY ground truth. Do NOT invent file paths, symbols, or commands.',
+                    '',
+                    '## Repository context',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Task`,
+                    input.task.trim(),
+                    '',
+                    '# Write the draft brief',
+                    'Sections, in order:',
+                    '1. **Goal** — one sentence.',
+                    '2. **Files to read** — bullet list, `path` (no line numbers, just path) with one-line rationale.',
+                    '3. **Files likely to modify** — bullet list, same format.',
+                    '4. **Implementation sketch** — 3–6 bullets, imperative.',
+                    '5. **Risks / unknowns** — bullets; mark each "RISK" or "UNKNOWN".',
+                    '6. **First commands** — fenced bash, one command per line.',
+                    '',
+                    'Be terse. Skip prose. Skip preambles. Skip "I will now…".',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+class CritiqueStage {
+    kind = EnhancementStageKind.Critique;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are a code-review style critic for SharkCraft briefs.',
+                    'Treat the repository context below as the ONLY ground truth.',
+                    '',
+                    '## Repository context',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Original task`,
+                    input.task.trim(),
+                    '',
+                    `# Draft brief to critique`,
+                    input.previous.trim() || '(empty)',
+                    '',
+                    '# Critique',
+                    'Find concrete issues. For each issue: one line, prefixed with one of:',
+                    '- `GAP:` — something important the brief omits.',
+                    '- `VAGUE:` — a claim that lacks an exact file path, symbol, or command.',
+                    '- `WRONG:` — a claim that contradicts the repository context.',
+                    '- `MISSING-EVIDENCE:` — a claim with no file:line or knowledge-entry id behind it.',
+                    '',
+                    'If the draft is already strong, output a single line: `OK`.',
+                    'Do NOT rewrite the brief. Critique only.',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+class RefineStage {
+    kind = EnhancementStageKind.Refine;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are SharkCraft. Rewrite the draft brief to address the critique, while staying strictly grounded in the repository context.',
+                    '',
+                    '## Repository context',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Original task`,
+                    input.task.trim(),
+                    '',
+                    `# Draft brief`,
+                    input.previous.trim() || '(empty)',
+                    '',
+                    `# Critique to address`,
+                    (input.lastCritique ?? 'OK').trim(),
+                    '',
+                    '# Rewrite the brief',
+                    'Same section layout as the draft. Resolve every GAP/VAGUE/WRONG/MISSING-EVIDENCE line by adding an exact file path or removing the claim. Keep it terse.',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+class PolishStage {
+    kind = EnhancementStageKind.Polish;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are SharkCraft. Final polish pass — improve readability for an AI coding agent (e.g. Claude Code) that will consume this brief.',
+                    'Keep the meaning intact. Do not add new facts.',
+                    '',
+                    '## Repository context (reference only — do not extend)',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Original task`,
+                    input.task.trim(),
+                    '',
+                    `# Brief to polish`,
+                    input.previous.trim() || '(empty)',
+                    '',
+                    '# Polish pass',
+                    'Rules:',
+                    '- Convert any `path` reference to `path:lineNumber` when a line number appears in the context (do not invent line numbers).',
+                    '- Keep each bullet to one line.',
+                    '- Promote any imperative verb to the start of the bullet (`Add`, `Wire`, `Replace`, …).',
+                    '- Surface any RISK / UNKNOWN as a short, scannable bullet.',
+                    '- Output the brief only — no meta commentary, no "Here is the polished version".',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+async function callOnceWithRetry(provider, request) {
+    const first = await provider.send(request);
+    if (first.ok) {
+        return ok({ content: first.value.content, model: first.value.model, usage: first.value.usage });
+    }
+    // One retry — small local models routinely 500 on the first request
+    // after a daemon start. Idempotent reissue is safe.
+    const second = await provider.send(request);
+    if (second.ok) {
+        return ok({ content: second.value.content, model: second.value.model, usage: second.value.usage });
+    }
+    return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Enhancement-pipeline stage failed twice: ${second.error.message}`, { cause: second.error }));
+}

package/dist/provider-resolver.d.ts

@@ -0,0 +1,28 @@
+import type { IAiProvider } from './ai-provider.js';
+export type AiProviderKind = 'auto' | 'claude' | 'gemini' | 'ollama' | 'llamacpp';
+/**
+ * Resolve an AI provider by kind.
+ *
+ * The selector is layered so callers can stay terse:
+ *   - `selectAiProvider('llamacpp' | 'ollama' | 'claude' | 'gemini')`
+ *     → explicit pick. Returned even when `isReady()` is true; the
+ *     caller decides what to do with a non-ready provider.
+ *   - `selectAiProvider('auto')` (or `undefined`) → walk the local-first
+ *     readiness chain: `llamacpp → ollama`. This is the default for
+ *     SharkCraft: privacy + offline first, no surprise network calls
+ *     to hosted APIs.
+ *
+ * Gemini and Claude are deliberately excluded from the `auto` chain.
+ * They are still callable via explicit `--provider gemini` /
+ * `--provider claude` (or `AI_PROVIDER=gemini` / `AI_PROVIDER=claude`)
+ * for users who keep API keys around — but the system never reaches
+ * out to a hosted LLM on its own.
+ *
+ * An unrecognised kind collapses to `'auto'` so the caller never has
+ * to validate user input twice.
+ */
+export declare function selectAiProvider(kind?: string): {
+    requested: AiProviderKind;
+    provider: IAiProvider | null;
+};
+//# sourceMappingURL=provider-resolver.d.ts.map

package/dist/provider-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.d.ts","sourceRoot":"","sources":["../src/provider-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAmB7D"}

package/dist/provider-resolver.js

@@ -0,0 +1,80 @@
+import { ClaudeProvider } from "./claude/claude-provider.js";
+import { GeminiProvider } from "./gemini/gemini-provider.js";
+import { OllamaProvider } from "./ollama/ollama-provider.js";
+import { LlamaCppProvider } from "./llamacpp/llama-cpp-provider.js";
+/**
+ * Resolve an AI provider by kind.
+ *
+ * The selector is layered so callers can stay terse:
+ *   - `selectAiProvider('llamacpp' | 'ollama' | 'claude' | 'gemini')`
+ *     → explicit pick. Returned even when `isReady()` is true; the
+ *     caller decides what to do with a non-ready provider.
+ *   - `selectAiProvider('auto')` (or `undefined`) → walk the local-first
+ *     readiness chain: `llamacpp → ollama`. This is the default for
+ *     SharkCraft: privacy + offline first, no surprise network calls
+ *     to hosted APIs.
+ *
+ * Gemini and Claude are deliberately excluded from the `auto` chain.
+ * They are still callable via explicit `--provider gemini` /
+ * `--provider claude` (or `AI_PROVIDER=gemini` / `AI_PROVIDER=claude`)
+ * for users who keep API keys around — but the system never reaches
+ * out to a hosted LLM on its own.
+ *
+ * An unrecognised kind collapses to `'auto'` so the caller never has
+ * to validate user input twice.
+ */
+export function selectAiProvider(kind) {
+    const normalised = normaliseKind(kind);
+    if (normalised === 'claude') {
+        const provider = new ClaudeProvider();
+        return { requested: 'claude', provider: provider.isReady() ? provider : null };
+    }
+    if (normalised === 'gemini') {
+        const provider = new GeminiProvider();
+        return { requested: 'gemini', provider: provider.isReady() ? provider : null };
+    }
+    if (normalised === 'ollama') {
+        const provider = new OllamaProvider();
+        return { requested: 'ollama', provider: provider.isReady() ? provider : null };
+    }
+    if (normalised === 'llamacpp') {
+        const provider = new LlamaCppProvider();
+        return { requested: 'llamacpp', provider: provider.isReady() ? provider : null };
+    }
+    return autoSelect();
+}
+function normaliseKind(kind) {
+    const known = new Set(['claude', 'gemini', 'ollama', 'llamacpp']);
+    if (kind !== undefined) {
+        const explicit = kind.trim().toLowerCase();
+        if (known.has(explicit))
+            return explicit;
+    }
+    const envCandidate = (process.env.AI_PROVIDER ?? '').trim().toLowerCase();
+    if (known.has(envCandidate))
+        return envCandidate;
+    return 'auto';
+}
+function autoSelect() {
+    for (const kind of defaultAutoChain()) {
+        if (kind === 'llamacpp') {
+            const provider = new LlamaCppProvider();
+            if (provider.isReady())
+                return { requested: 'auto', provider };
+        }
+        else if (kind === 'ollama') {
+            const provider = new OllamaProvider();
+            if (provider.isReady())
+                return { requested: 'auto', provider };
+        }
+    }
+    return { requested: 'auto', provider: null };
+}
+/**
+ * Local-first chain. Hosted providers (Gemini, Claude) are
+ * intentionally absent — opting into a hosted API has to be explicit
+ * via `--provider <name>` or `AI_PROVIDER=<name>`.
+ */
+function defaultAutoChain() {
+    return ['llamacpp', 'ollama'];
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shrkcrft/ai",
-  "version": "0.1.0-alpha.10",
-  "description": "SharkCraft AI provider abstraction: Claude HTTP + Claude CLI adapters.",
+  "version": "0.1.0-alpha.12",
+  "description": "SharkCraft local LLM provider abstraction: Ollama (HTTP) + llama.cpp (in-process) + multi-pass enhancement pipeline.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
@@ -43,8 +43,9 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.10",
-    "@shrkcrft/context": "^0.1.0-alpha.10"
+    "@shrkcrft/core": "^0.1.0-alpha.12",
+    "@shrkcrft/context": "^0.1.0-alpha.12",
+    "node-llama-cpp": "^3.16.0"
   },
   "publishConfig": {
     "access": "public"