@mrace07/kairo 0.1.0

package/dist/infrastructure/providers/jev-safety-advisor.d.ts

@@ -0,0 +1,18 @@
+import type { JevAssessment, JevDecision, JevRecovery, JevModelTier, JevInteractionIntent, JevRoute, JevSafetyAdvisor } from "../../domain/ports.js";
+/** Calls TypeSafe Jev directly for one bounded, typed action-risk decision. */
+export declare class JevDecisionProvider implements JevSafetyAdvisor {
+    private readonly apiKey;
+    private readonly fetcher;
+    constructor(apiKey: string, fetcher?: typeof fetch);
+    assess(state: string): Promise<JevAssessment>;
+    /** Separates chat from repository work before Kairo exposes workspace context or tools. */
+    intent(state: string): Promise<JevDecision<JevInteractionIntent>>;
+    route(state: string): Promise<JevDecision<JevRoute>>;
+    recover(state: string): Promise<JevDecision<JevRecovery>>;
+    /** Selects a bounded coding-model tier; Kairo applies the local allowlist and credentials. */
+    modelTier(state: string): Promise<JevDecision<JevModelTier>>;
+    private decide;
+    /** Uses a minimal typed request because TypeSafe does not publish a key-only probe. */
+    validate(): Promise<void>;
+    private error;
+}

package/dist/infrastructure/providers/jev-safety-advisor.js

@@ -0,0 +1,95 @@
+import { ProviderError } from "../../domain/provider-error.js";
+const endpoint = "https://api.typesafe.ai/v1/systemone";
+const riskChoices = {
+    low: "A workspace-local, reversible action with limited impact, such as an ordinary source edit or focused test.",
+    medium: "An action that can affect multiple files, dependencies, build artifacts, or execute a command with meaningful workspace impact.",
+    high: "An action that can delete data, publish or transmit data, change credentials, alter broad configuration, or run a destructive command.",
+};
+/** Calls TypeSafe Jev directly for one bounded, typed action-risk decision. */
+export class JevDecisionProvider {
+    apiKey;
+    fetcher;
+    constructor(apiKey, fetcher = fetch) {
+        this.apiKey = apiKey;
+        this.fetcher = fetcher;
+    }
+    async assess(state) {
+        const decision = await this.decide("action_risk", state, riskChoices);
+        return { risk: decision.value, confidence: decision.confidence };
+    }
+    /** Separates chat from repository work before Kairo exposes workspace context or tools. */
+    async intent(state) {
+        return this.decide("interaction_intent", state, {
+            conversation: "A greeting, acknowledgement, or casual social message that needs a short direct reply and no model call.",
+            answer: "A general question or explanation that can be answered without repository context or tools.",
+            repository_task: "A request to inspect, explain using, change, test, run, or otherwise act on the current repository.",
+        });
+    }
+    async route(state) {
+        return this.decide("task_route", state, {
+            build: "A bounded implementation request that can proceed directly with the coding agent.",
+            plan: "A broad, ambiguous, multi-file, risky, or architectural request that should first create a read-only plan.",
+        });
+    }
+    async recover(state) {
+        return this.decide("verification_recovery", state, {
+            repair: "The failure is specific enough for the coding model to attempt a focused repair.",
+            broaden: "The current check is too narrow; recommend the next broader discovered verification command.",
+            escalate: "The failure is ambiguous, risky, or lacks enough evidence; stop automatic repair and ask the user.",
+        });
+    }
+    /** Selects a bounded coding-model tier; Kairo applies the local allowlist and credentials. */
+    async modelTier(state) {
+        return this.decide("coding_model_tier", state, {
+            fast: "A small, focused, low-risk implementation or explanation where low latency matters most.",
+            balanced: "A normal feature or bug fix that benefits from reliable coding ability and moderate latency.",
+            strong: "A complex, multi-file, architectural, or difficult debugging task needing the strongest available coding model.",
+        });
+    }
+    async decide(questionId, state, criteria) {
+        const response = await this.fetcher(endpoint, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: "jev-latest",
+                state: state.slice(0, 4_000),
+                questions: {
+                    [questionId]: {
+                        type: "choice",
+                        instructions: "Classify only the operational risk of the proposed Kairo action. Do not authorize it.",
+                        criteria,
+                    },
+                },
+            }),
+        });
+        if (!response.ok)
+            throw this.error(response.status);
+        const answer = (await response.json());
+        const choice = answer.answers?.[questionId]?.choice;
+        const confidence = answer.answers?.[questionId]?.confidence;
+        if (typeof choice !== "string" ||
+            !Object.hasOwn(criteria, choice) ||
+            typeof confidence !== "number" ||
+            !Number.isFinite(confidence) ||
+            confidence < 0 ||
+            confidence > 1)
+            throw new ProviderError("request", false, undefined, "Jev");
+        return { value: choice, confidence };
+    }
+    /** Uses a minimal typed request because TypeSafe does not publish a key-only probe. */
+    async validate() {
+        await this.assess("Kairo credential validation. Proposed action: no operation.");
+    }
+    error(status) {
+        if (status === 401 || status === 403)
+            return new ProviderError("authentication", false, undefined, "Jev");
+        if (status === 429)
+            return new ProviderError("quota", true, undefined, "Jev");
+        if (status >= 500)
+            return new ProviderError("service", true, undefined, "Jev");
+        return new ProviderError("request", false, undefined, "Jev");
+    }
+}

package/dist/infrastructure/providers/mistral-provider.d.ts

@@ -0,0 +1,15 @@
+import { type ProviderProgress } from "../../domain/provider-error.js";
+import type { Message, ModelTurn } from "../../domain/models.js";
+import type { ModelProvider, ToolDefinition } from "../../domain/ports.js";
+/** Adapts Mistral's OpenAI-compatible Chat Completions API to Kairo's provider contract. */
+export declare class MistralProvider implements ModelProvider {
+    private readonly apiKey;
+    private readonly model;
+    private readonly tools;
+    private readonly fetcher;
+    constructor(apiKey: string, model: string, tools: ToolDefinition[], fetcher?: typeof fetch);
+    stream(messages: Message[], onText: (chunk: string) => void, onProgress?: (event: ProviderProgress) => void, systemInstruction?: string, toolsEnabled?: boolean): Promise<ModelTurn>;
+    private streamOnce;
+    private message;
+    private error;
+}

package/dist/infrastructure/providers/mistral-provider.js

@@ -0,0 +1,137 @@
+import { modelSystemInstruction } from "../../application/model-system-instruction.js";
+import { ProviderError } from "../../domain/provider-error.js";
+import { recoverProvider } from "./provider-recovery.js";
+/** Adapts Mistral's OpenAI-compatible Chat Completions API to Kairo's provider contract. */
+export class MistralProvider {
+    apiKey;
+    model;
+    tools;
+    fetcher;
+    constructor(apiKey, model, tools, fetcher = fetch) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.tools = tools;
+        this.fetcher = fetcher;
+    }
+    async stream(messages, onText, onProgress, systemInstruction = modelSystemInstruction, toolsEnabled = true) {
+        return recoverProvider((markContent) => this.streamOnce(messages, onText, markContent, systemInstruction, toolsEnabled), onProgress, undefined, "Mistral");
+    }
+    async streamOnce(messages, onText, markContent, systemInstruction, toolsEnabled) {
+        const response = await this.fetcher("https://api.mistral.ai/v1/chat/completions", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                model: this.model,
+                stream: true,
+                messages: [
+                    { role: "system", content: systemInstruction },
+                    ...messages.map((message) => this.message(message)),
+                ],
+                ...(toolsEnabled
+                    ? {
+                        tools: this.tools.map(({ name, description, parameters }) => ({
+                            type: "function",
+                            function: { name, description, parameters },
+                        })),
+                        tool_choice: "auto",
+                        parallel_tool_calls: false,
+                    }
+                    : {}),
+            }),
+        });
+        if (!response.ok)
+            throw this.error(response.status);
+        if (!response.body)
+            throw new ProviderError("service", true, undefined, "Mistral");
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let text = "";
+        const pending = new Map();
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            buffer += decoder.decode(next.value, { stream: true });
+            const frames = buffer.split("\n\n");
+            buffer = frames.pop() ?? "";
+            for (const frame of frames) {
+                const payload = frame
+                    .split("\n")
+                    .filter((line) => line.startsWith("data:"))
+                    .map((line) => line.slice(5).trim())
+                    .join("\n");
+                if (!payload || payload === "[DONE]")
+                    continue;
+                let chunk;
+                try {
+                    chunk = JSON.parse(payload);
+                }
+                catch {
+                    throw new ProviderError("service", true, undefined, "Mistral");
+                }
+                const delta = chunk.choices?.[0]?.delta;
+                if (delta?.content) {
+                    markContent();
+                    text += delta.content;
+                    onText(delta.content);
+                }
+                for (const call of delta?.tool_calls ?? []) {
+                    markContent();
+                    const index = call.index ?? 0;
+                    const current = pending.get(index) ?? { name: "", arguments: "" };
+                    if (call.id)
+                        current.id = call.id;
+                    if (call.function?.name)
+                        current.name += call.function.name;
+                    if (call.function?.arguments)
+                        current.arguments += call.function.arguments;
+                    pending.set(index, current);
+                }
+            }
+        }
+        return {
+            text,
+            toolCalls: [...pending.entries()]
+                .sort(([left], [right]) => left - right)
+                .map(([, call]) => {
+                try {
+                    return {
+                        id: call.id || crypto.randomUUID(),
+                        name: call.name,
+                        args: JSON.parse(call.arguments || "{}"),
+                    };
+                }
+                catch {
+                    throw new ProviderError("request", false, undefined, "Mistral");
+                }
+            }),
+        };
+    }
+    message(message) {
+        if (message.role === "tool")
+            return { role: "tool", tool_call_id: message.toolCallId, content: message.content };
+        if (message.role === "model" && message.toolCallId && message.toolName)
+            return {
+                role: "assistant",
+                content: null,
+                tool_calls: [
+                    {
+                        id: message.toolCallId,
+                        type: "function",
+                        function: { name: message.toolName, arguments: message.content },
+                    },
+                ],
+            };
+        return { role: message.role === "model" ? "assistant" : "user", content: message.content };
+    }
+    error(status) {
+        if (status === 401 || status === 403)
+            return new ProviderError("authentication", false, undefined, "Mistral");
+        if (status === 429)
+            return new ProviderError("quota", true, undefined, "Mistral");
+        if (status >= 500)
+            return new ProviderError("service", true, undefined, "Mistral");
+        return new ProviderError("request", false, undefined, "Mistral");
+    }
+}

package/dist/infrastructure/providers/openrouter-provider.d.ts

@@ -0,0 +1,15 @@
+import { type ProviderProgress } from "../../domain/provider-error.js";
+import type { Message, ModelTurn } from "../../domain/models.js";
+import type { ModelProvider, ToolDefinition } from "../../domain/ports.js";
+/** Adapts OpenRouter's OpenAI-compatible chat API to Kairo's provider contract. */
+export declare class OpenRouterProvider implements ModelProvider {
+    private readonly model;
+    private readonly tools;
+    private readonly client;
+    constructor(apiKey: string, model: string, tools: ToolDefinition[]);
+    stream(messages: Message[], onText: (chunk: string) => void, onProgress?: (event: ProviderProgress) => void, systemInstruction?: string, toolsEnabled?: boolean): Promise<ModelTurn>;
+    private streamOnce;
+    private message;
+    /** Free endpoints are rate-limited; do not consume their small allowance with automatic retries. */
+    private isFreeModel;
+}

package/dist/infrastructure/providers/openrouter-provider.js

@@ -0,0 +1,104 @@
+import { OpenRouter } from "@openrouter/sdk";
+import { modelSystemInstruction } from "../../application/model-system-instruction.js";
+import { ProviderError } from "../../domain/provider-error.js";
+import { recoverProvider } from "./provider-recovery.js";
+/** Adapts OpenRouter's OpenAI-compatible chat API to Kairo's provider contract. */
+export class OpenRouterProvider {
+    model;
+    tools;
+    client;
+    constructor(apiKey, model, tools) {
+        this.model = model;
+        this.tools = tools;
+        this.client = new OpenRouter({
+            apiKey,
+            appTitle: "Kairo",
+            // Kairo owns retry behavior so transcript progress remains accurate.
+            retryConfig: { strategy: "none" },
+        });
+    }
+    async stream(messages, onText, onProgress, systemInstruction = modelSystemInstruction, toolsEnabled = true) {
+        return recoverProvider((markContent) => this.streamOnce(messages, onText, markContent, systemInstruction, toolsEnabled), onProgress, undefined, "OpenRouter", !this.isFreeModel());
+    }
+    async streamOnce(messages, onText, markContent, systemInstruction, toolsEnabled) {
+        const stream = (await this.client.chat.send({
+            chatRequest: {
+                model: this.model,
+                stream: true,
+                messages: [
+                    { role: "system", content: systemInstruction },
+                    ...messages.map((message) => this.message(message)),
+                ],
+                ...(toolsEnabled
+                    ? {
+                        tools: this.tools.map(({ name, description, parameters }) => ({
+                            type: "function",
+                            function: { name, description, parameters },
+                        })),
+                        toolChoice: "auto",
+                        parallelToolCalls: false,
+                    }
+                    : {}),
+            },
+        }));
+        let text = "";
+        const pending = new Map();
+        for await (const chunk of stream) {
+            if (chunk.error)
+                throw { status: chunk.error.code };
+            const delta = chunk.choices[0]?.delta;
+            if (delta?.content) {
+                markContent();
+                text += delta.content;
+                onText(delta.content);
+            }
+            for (const call of delta?.toolCalls ?? []) {
+                markContent();
+                const current = pending.get(call.index) ?? { name: "", arguments: "" };
+                if (call.id)
+                    current.id = call.id;
+                if (call.function?.name)
+                    current.name += call.function.name;
+                if (call.function?.arguments)
+                    current.arguments += call.function.arguments;
+                pending.set(call.index, current);
+            }
+        }
+        const toolCalls = [...pending.entries()]
+            .sort(([left], [right]) => left - right)
+            .map(([, call]) => {
+            try {
+                return {
+                    id: call.id || crypto.randomUUID(),
+                    name: call.name,
+                    args: JSON.parse(call.arguments || "{}"),
+                };
+            }
+            catch {
+                throw new ProviderError("request", false, undefined, "OpenRouter");
+            }
+        });
+        return { text, toolCalls };
+    }
+    message(message) {
+        if (message.role === "tool")
+            return { role: "tool", toolCallId: message.toolCallId, content: message.content };
+        if (message.role === "model" && message.toolCallId && message.toolName)
+            return {
+                role: "assistant",
+                content: null,
+                toolCalls: [
+                    {
+                        id: message.toolCallId,
+                        type: "function",
+                        function: { name: message.toolName, arguments: message.content },
+                    },
+                ],
+            };
+        return { role: message.role === "model" ? "assistant" : "user", content: message.content };
+    }
+    /** Free endpoints are rate-limited; do not consume their small allowance with automatic retries. */
+    isFreeModel() {
+        return this.model === "openrouter/free" || this.model.endsWith(":free");
+    }
+}

package/dist/infrastructure/providers/provider-recovery.d.ts

@@ -0,0 +1,10 @@
+import { ProviderError, type ProviderProgress } from "../../domain/provider-error.js";
+/** Reads bounded nested SDK/HTTP error metadata without persisting any raw values. */
+export declare function normalizeProviderError(error: unknown, provider?: string): ProviderError;
+export interface RecoveryClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    random(): number;
+}
+/** Retries only pre-content failures within three retries and 30 seconds of waiting. */
+export declare function recoverProvider<T>(request: (markContent: () => void) => Promise<T>, progress?: (event: ProviderProgress) => void, timer?: RecoveryClock, provider?: string, retryQuota?: boolean): Promise<T>;

package/dist/infrastructure/providers/provider-recovery.js

@@ -0,0 +1,108 @@
+import { ProviderError } from "../../domain/provider-error.js";
+/** Reads bounded nested SDK/HTTP error metadata without persisting any raw values. */
+export function normalizeProviderError(error, provider = "Model provider") {
+    if (error instanceof ProviderError)
+        return error;
+    const texts = [];
+    const codes = [];
+    let retryAfterMs;
+    const visit = (value, depth) => {
+        if (depth > 6 || !value)
+            return;
+        if (typeof value === "string") {
+            const text = value.slice(0, 16000);
+            texts.push(text);
+            try {
+                visit(JSON.parse(text), depth + 1);
+            }
+            catch {
+                /* SDK messages may be plain text. */
+            }
+            return;
+        }
+        if (typeof value !== "object")
+            return;
+        const record = value;
+        for (const field of ["code", "status", "statusCode", "name"])
+            if (record[field] !== undefined)
+                codes.push(String(record[field]));
+        if (typeof record.retryDelay === "string") {
+            const match = /^(\d+(?:\.\d+)?)s$/.exec(record.retryDelay);
+            if (match)
+                retryAfterMs = Math.max(retryAfterMs ?? 0, Number(match[1]) * 1000);
+        }
+        const headers = record.headers;
+        const header = headers?.get?.("retry-after") ??
+            record.headers?.["retry-after"];
+        if (header) {
+            const delay = /^\d+(?:\.\d+)?$/.test(header)
+                ? Number(header) * 1000
+                : Date.parse(header) - Date.now();
+            if (Number.isFinite(delay))
+                retryAfterMs = Math.max(retryAfterMs ?? 0, delay, 0);
+        }
+        for (const field of [
+            "message",
+            "error",
+            "cause",
+            "details",
+            "response",
+            "violations",
+            "quotaId",
+        ])
+            visit(record[field], depth + 1);
+        if (Array.isArray(value))
+            for (const item of value.slice(0, 20))
+                visit(item, depth + 1);
+    };
+    visit(error, 0);
+    const text = texts.join(" ");
+    const code = codes.join(" ");
+    if (/\b(401|403|UNAUTHENTICATED|PERMISSION_DENIED)\b/.test(code))
+        return new ProviderError("authentication", false, undefined, provider, "Check the API key in /models.");
+    if (/\b(402|429|RESOURCE_EXHAUSTED)\b/.test(code)) {
+        const permanent = /per.?day|daily|billing|credit/i.test(text.replace(/check your plan and billing details/gi, ""));
+        return new ProviderError("quota", !permanent, retryAfterMs, provider, "Check the provider's credits, limits, or available model routes.");
+    }
+    if (/\b(500|502|503|504|UNAVAILABLE|INTERNAL)\b/.test(code))
+        return new ProviderError("service", true, retryAfterMs, provider);
+    if (/ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|TimeoutError|AbortError/.test(code) ||
+        /fetch failed|network error|timed out/i.test(text))
+        return new ProviderError("network", true, retryAfterMs, provider);
+    return new ProviderError("request", false, undefined, provider, "Check that the selected model supports chat and tool calling.");
+}
+const clock = {
+    now: () => performance.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    random: Math.random,
+};
+/** Retries only pre-content failures within three retries and 30 seconds of waiting. */
+export async function recoverProvider(request, progress = () => { }, timer = clock, provider = "Model provider", retryQuota = true) {
+    let retries = 0;
+    let waited = 0;
+    for (;;) {
+        let hasContent = false;
+        try {
+            return await request(() => {
+                hasContent = true;
+            });
+        }
+        catch (raw) {
+            let error = normalizeProviderError(raw, provider);
+            if (!retryQuota && error.category === "quota")
+                error = new ProviderError("quota", false, error.retryAfterMs, provider, "The provider quota was exhausted. Wait before trying again or use a provider with available capacity.");
+            const delay = error.retryAfterMs ?? 1000 * 2 ** retries + timer.random() * 250;
+            if (!error.retryable || hasContent || retries >= 3 || delay > 30000 - waited) {
+                progress({ kind: "exhausted", category: error.category, retry: retries, delayMs: 0 });
+                throw error;
+            }
+            retries += 1;
+            progress({ kind: "retry", category: error.category, retry: retries, delayMs: delay });
+            const started = timer.now();
+            await timer.sleep(delay);
+            const elapsed = Math.max(delay, timer.now() - started);
+            waited += elapsed;
+            progress({ kind: "retry_wait", category: error.category, retry: retries, delayMs: elapsed });
+        }
+    }
+}

package/dist/infrastructure/providers/provider-registry.d.ts

@@ -0,0 +1,22 @@
+import type { ModelSelection, ProviderId } from "../../domain/models.js";
+import type { ModelProvider, ToolDefinition } from "../../domain/ports.js";
+export interface ProviderDescriptor {
+    id: ProviderId;
+    name: string;
+    environmentVariable: string;
+    models: Array<{
+        id: string;
+        label: string;
+        tier: "fast" | "balanced" | "strong";
+        recommended?: boolean;
+    }>;
+    create(apiKey: string, model: string, tools: ToolDefinition[]): ModelProvider;
+    validate(apiKey: string): Promise<void>;
+}
+export declare const providerRegistry: readonly ProviderDescriptor[];
+/** Narrows untrusted CLI/config text to a registered provider identifier. */
+export declare function isProviderId(value: unknown): value is ProviderId;
+/** Returns the registered behavior for one supported provider. */
+export declare function providerById(id: ProviderId): ProviderDescriptor;
+/** Creates a provider from a validated global selection. */
+export declare function createProvider(selection: ModelSelection, apiKey: string, tools: ToolDefinition[]): ModelProvider;

package/dist/infrastructure/providers/provider-registry.js

@@ -0,0 +1,67 @@
+import { GeminiProvider } from "./gemini-provider.js";
+import { GroqProvider } from "./groq-provider.js";
+import { MistralProvider } from "./mistral-provider.js";
+/** Converts a failed credential probe into a provider-safe authentication error. */
+async function validateResponse(provider, response) {
+    if (!response.ok)
+        throw new Error(`${provider} credential validation failed (${response.status}).`);
+}
+export const providerRegistry = [
+    {
+        id: "gemini",
+        name: "Gemini",
+        environmentVariable: "GEMINI_API_KEY",
+        models: [
+            { id: "gemini-2.5-flash", label: "Gemini 2.5 Flash", tier: "balanced", recommended: true },
+        ],
+        create: (apiKey, model, tools) => new GeminiProvider(apiKey, model, tools),
+        validate: async (apiKey) => validateResponse("Gemini", await fetch(`https://generativelanguage.googleapis.com/v1beta/models?pageSize=1&key=${encodeURIComponent(apiKey)}`)),
+    },
+    {
+        id: "groq",
+        name: "Groq",
+        environmentVariable: "GROQ_API_KEY",
+        models: [
+            { id: "openai/gpt-oss-120b", label: "GPT-OSS 120B", tier: "strong", recommended: true },
+            { id: "openai/gpt-oss-20b", label: "GPT-OSS 20B (faster)", tier: "fast" },
+        ],
+        create: (apiKey, model, tools) => new GroqProvider(apiKey, model, tools),
+        validate: async (apiKey) => validateResponse("Groq", await fetch("https://api.groq.com/openai/v1/models", {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        })),
+    },
+    {
+        id: "mistral",
+        name: "Mistral",
+        environmentVariable: "MISTRAL_API_KEY",
+        models: [
+            {
+                id: "mistral-small-latest",
+                label: "Mistral Small 4",
+                tier: "fast",
+                recommended: true,
+            },
+            {
+                id: "mistral-medium-latest",
+                label: "Mistral Medium 3.5",
+                tier: "strong",
+            },
+        ],
+        create: (apiKey, model, tools) => new MistralProvider(apiKey, model, tools),
+        validate: async (apiKey) => validateResponse("Mistral", await fetch("https://api.mistral.ai/v1/models", {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        })),
+    },
+];
+/** Narrows untrusted CLI/config text to a registered provider identifier. */
+export function isProviderId(value) {
+    return providerRegistry.some((provider) => provider.id === value);
+}
+/** Returns the registered behavior for one supported provider. */
+export function providerById(id) {
+    return providerRegistry.find((provider) => provider.id === id);
+}
+/** Creates a provider from a validated global selection. */
+export function createProvider(selection, apiKey, tools) {
+    return providerById(selection.provider).create(apiKey, selection.model, tools);
+}

package/dist/infrastructure/repository/repository-awareness.d.ts

@@ -0,0 +1,12 @@
+import type { RepositoryFingerprint, RepositorySnapshot } from "../../domain/models.js";
+import type { TaskStore } from "../../domain/ports.js";
+import { RepositoryProfiler } from "./repository-profiler.js";
+export declare class RepositoryAwareness {
+    private readonly store;
+    private readonly profiler;
+    constructor(store: TaskStore, profiler?: RepositoryProfiler);
+    /** Reuses a current snapshot or atomically replaces stale derived metadata. */
+    ensureFresh(sessionId: string, root: string): Promise<RepositorySnapshot>;
+    build(root: string): Promise<RepositorySnapshot>;
+    fingerprint(root: string): Promise<RepositoryFingerprint>;
+}

package/dist/infrastructure/repository/repository-awareness.js

@@ -0,0 +1,25 @@
+import { RepositoryProfiler } from "./repository-profiler.js";
+export class RepositoryAwareness {
+    store;
+    profiler;
+    constructor(store, profiler = new RepositoryProfiler()) {
+        this.store = store;
+        this.profiler = profiler;
+    }
+    /** Reuses a current snapshot or atomically replaces stale derived metadata. */
+    async ensureFresh(sessionId, root) {
+        const saved = this.store.repositorySnapshot(sessionId);
+        const current = await this.fingerprint(root);
+        if (saved?.fingerprint.value === current.value)
+            return saved;
+        const snapshot = await this.build(root);
+        this.store.saveRepositorySnapshot(sessionId, snapshot);
+        return snapshot;
+    }
+    build(root) {
+        return this.profiler.profile(root);
+    }
+    fingerprint(root) {
+        return this.profiler.fingerprint(root);
+    }
+}