@shrkcrft/ai 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/llm-recommendations.d.ts

@@ -0,0 +1,72 @@
+import type { IAiProvider } from './ai-provider.js';
+import { type IAiBlock } from './llm-hints.js';
+export type RecommendationSeverity = 'info' | 'warn' | 'error';
+export interface ILlmRecommendation {
+    severity: RecommendationSeverity;
+    category: string;
+    /** Short, one-sentence description of what's recommended. */
+    title: string;
+    /** Detailed prose; typically 1-3 sentences with concrete next-steps. */
+    detail: string;
+    /** Optional target identifier (rule id, template id, file path) the recommendation applies to. */
+    target?: string;
+    /** Confidence in [0, 1]; lower for fuzzier judgments. */
+    confidence: number;
+}
+export interface IRecommendationEnvelope {
+    /** Always present, even when LLM is unavailable. */
+    ai: IAiBlock;
+    recommendations: readonly ILlmRecommendation[];
+}
+export interface IEnrichWithLlmRecommendationsInput {
+    /**
+     * The shape of the deterministic surface (e.g., 'doctor', 'templates-drift').
+     * Used in the LLM prompt so the model knows what it's looking at.
+     */
+    surface: string;
+    /**
+     * Human-readable description of the deterministic findings (what's already
+     * known). Should be tight — the prompt fits into one LLM call.
+     */
+    deterministicSummary: string;
+    /**
+     * Provider kind to request. Defaults to 'auto' (local-first walk).
+     */
+    providerKind?: string;
+    /**
+     * Override the auto-selection by passing an already-resolved provider
+     * (useful for tests).
+     */
+    providerOverride?: IAiProvider | null;
+    /**
+     * True when the caller's --no-enhance equivalent was passed.
+     * When true, no LLM call is made and the AI block records the opt-out.
+     */
+    userOptedOut?: boolean;
+    /**
+     * Per-surface ask: what should the LLM produce on top of the
+     * deterministic summary? E.g. "for each warning, produce one concrete
+     * next-step the user can run from the CLI."
+     */
+    ask: string;
+    /**
+     * Optional override for the model used by the provider.
+     */
+    model?: string;
+    maxTokens?: number;
+}
+/**
+ * Shared utility for layering LLM recommendations onto any deterministic
+ * surface. The deterministic portion is the caller's responsibility; this
+ * helper only adds the `ai` block and a structured `recommendations` array.
+ *
+ * Hard guarantee: if no LLM is reachable (or `userOptedOut` is true), the
+ * call is a no-op apart from emitting the `ai` block with setup hints.
+ *
+ * Lives in `@shrkcrft/ai` so any callable surface (CLI commands, packs,
+ * read-only MCP tools that want recommendations alongside their data)
+ * can reuse the same envelope shape.
+ */
+export declare function enrichWithLlmRecommendations(input: IEnrichWithLlmRecommendationsInput): Promise<IRecommendationEnvelope>;
+export declare function renderRecommendationsMarkdown(envelope: IRecommendationEnvelope): string;
+//# sourceMappingURL=llm-recommendations.d.ts.map

package/dist/llm-recommendations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-recommendations.d.ts","sourceRoot":"","sources":["../src/llm-recommendations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC,uBAAuB,CAAC,CAoClC;AA2FD,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,CA+BvF"}

package/dist/llm-recommendations.js

@@ -0,0 +1,188 @@
+import { AiMessageRole } from "./ai-request.js";
+import { selectAiProvider } from "./provider-resolver.js";
+import { buildAiBlock } from "./llm-hints.js";
+/**
+ * Shared utility for layering LLM recommendations onto any deterministic
+ * surface. The deterministic portion is the caller's responsibility; this
+ * helper only adds the `ai` block and a structured `recommendations` array.
+ *
+ * Hard guarantee: if no LLM is reachable (or `userOptedOut` is true), the
+ * call is a no-op apart from emitting the `ai` block with setup hints.
+ *
+ * Lives in `@shrkcrft/ai` so any callable surface (CLI commands, packs,
+ * read-only MCP tools that want recommendations alongside their data)
+ * can reuse the same envelope shape.
+ */
+export async function enrichWithLlmRecommendations(input) {
+    if (input.userOptedOut) {
+        const aiBlock = buildAiBlock({
+            selection: { requested: normaliseKind(input.providerKind), provider: null },
+            userOptedOut: true,
+        });
+        return { ai: aiBlock, recommendations: [] };
+    }
+    const selection = input.providerOverride !== undefined
+        ? { requested: normaliseKind(input.providerKind), provider: input.providerOverride }
+        : selectAiProvider(input.providerKind);
+    if (!selection.provider) {
+        const aiBlock = buildAiBlock({ selection, userOptedOut: false });
+        return { ai: aiBlock, recommendations: [] };
+    }
+    if (input.model)
+        selection.provider.configure({ model: input.model });
+    const messages = buildRecommendationMessages(input);
+    let recommendations = [];
+    try {
+        const res = await selection.provider.send({
+            messages,
+            maxTokens: input.maxTokens ?? 1024,
+        });
+        if (res.ok) {
+            recommendations = parseRecommendations(res.value.content);
+        }
+    }
+    catch {
+        // Swallow — recommendations stay empty; ai block still carries provider info.
+    }
+    const aiBlock = buildAiBlock({ selection, userOptedOut: false });
+    return { ai: aiBlock, recommendations };
+}
+function buildRecommendationMessages(input) {
+    const system = {
+        role: AiMessageRole.System,
+        content: [
+            `You are a critic layering concrete next-step recommendations on top of a deterministic SharkCraft "${input.surface}" report.`,
+            'The deterministic report is supplied verbatim — treat its findings as facts. Your job is to translate them into actions a developer (or an AI coding agent) can take immediately.',
+            '',
+            'The user-specified ask is:',
+            input.ask,
+            '',
+            'Return ONLY a JSON object with this exact shape, no preface, no fences:',
+            '{',
+            '  "recommendations": [',
+            '    {',
+            '      "severity": "info" | "warn" | "error",',
+            '      "category": "<short kebab-case category>",',
+            '      "title": "<one-sentence summary>",',
+            '      "detail": "<one to three sentences with concrete next-steps; name files, commands, or symbols when possible>",',
+            '      "target": "<optional id or path>",',
+            '      "confidence": 0.0',
+            '    }',
+            '  ]',
+            '}',
+            'Skip the bullet entirely if you cannot say anything specific. Better silence than ceremony.',
+        ].join('\n'),
+    };
+    const user = {
+        role: AiMessageRole.User,
+        content: [`# Deterministic ${input.surface} summary`, '', input.deterministicSummary].join('\n'),
+    };
+    return [system, user];
+}
+function parseRecommendations(raw) {
+    const trimmed = raw.trim();
+    let jsonText = trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        jsonText = fenced[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        const first = jsonText.indexOf('{');
+        const last = jsonText.lastIndexOf('}');
+        if (first < 0 || last <= first)
+            return [];
+        try {
+            parsed = JSON.parse(jsonText.slice(first, last + 1));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const list = parsed.recommendations;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const item of list) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const severity = coerceSeverity(obj.severity);
+        const category = typeof obj.category === 'string' && obj.category.trim()
+            ? obj.category.trim()
+            : 'other';
+        const title = typeof obj.title === 'string' ? obj.title.trim() : '';
+        const detail = typeof obj.detail === 'string' ? obj.detail.trim() : '';
+        if (!title || !detail)
+            continue;
+        const confidence = typeof obj.confidence === 'number' && obj.confidence >= 0 && obj.confidence <= 1
+            ? obj.confidence
+            : 0.5;
+        const target = typeof obj.target === 'string' && obj.target.trim() ? obj.target.trim() : undefined;
+        out.push({ severity, category, title, detail, confidence, ...(target ? { target } : {}) });
+    }
+    return out;
+}
+function coerceSeverity(value) {
+    if (value === 'error' || value === 'warn' || value === 'info')
+        return value;
+    if (value === 'warning')
+        return 'warn';
+    return 'info';
+}
+function normaliseKind(kind) {
+    const known = new Set(['claude', 'gemini', 'ollama', 'llamacpp']);
+    if (kind && known.has(kind.toLowerCase()))
+        return kind.toLowerCase();
+    return 'auto';
+}
+export function renderRecommendationsMarkdown(envelope) {
+    const out = [];
+    if (envelope.recommendations.length === 0) {
+        out.push('## LLM recommendations');
+        out.push('');
+        out.push(envelope.ai.reachable
+            ? '(LLM returned no actionable recommendations — the deterministic output already covers the surface.)'
+            : '(LLM unavailable — see the AI configuration block below to enable.)');
+        out.push('');
+    }
+    else {
+        out.push(`## LLM recommendations (${envelope.recommendations.length})`);
+        out.push('');
+        const order = ['error', 'warn', 'info'];
+        for (const sev of order) {
+            const group = envelope.recommendations.filter((r) => r.severity === sev);
+            if (group.length === 0)
+                continue;
+            for (const rec of group) {
+                out.push(`- **[${sev}]** \`${rec.category}\`${rec.target ? ` (${rec.target})` : ''} — ${rec.title} _(confidence ${rec.confidence.toFixed(2)})_`);
+                out.push(`  - ${rec.detail}`);
+            }
+        }
+        out.push('');
+    }
+    out.push('---');
+    out.push('');
+    out.push(renderAiHintsCompact(envelope.ai));
+    return out.join('\n');
+}
+function renderAiHintsCompact(ai) {
+    const out = [];
+    const status = ai.reachable
+        ? `active via \`${ai.providerId}\``
+        : ai.enhancementSkipped
+            ? 'disabled by user'
+            : 'unavailable';
+    out.push(`### AI configuration — ${status}`);
+    for (const hint of ai.hints) {
+        out.push(`- [${hint.level}] **${hint.title}**`);
+        for (const step of hint.steps) {
+            out.push(`  - ${step}`);
+        }
+    }
+    return out.join('\n');
+}

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"}