agentic-qe 3.10.9 → 3.11.1

package/dist/routing/free-tier/executor.js

@@ -0,0 +1,182 @@
+/**
+ * Free-tier escalating executor (cross-pollination plan 06, D7-wire + D8).
+ *
+ * Implements Ruv's SWE-bench economics for a QE task:
+ *   1. run on the CHEAP/free local tier
+ *   2. verify with an objective QE oracle (pass/fail [+ feedback])
+ *   3. D8 REPAIR LOOP: on failure, feed the failure back to the SAME tier and
+ *      retry (Round-2 lever: 7.7% -> 15.3% on a fixed model), up to `repairAttempts`
+ *   4. only then escalate up the ladder (when `escalate` is true)
+ *   5. record the start-tier outcome so the base tier adapts across tasks
+ *
+ * Decoupled by injection: free tiers via `freeTierChat`; Claude tiers via an
+ * injected `ClaudeTierRunner` (no Anthropic SDK dep; coordinator delegates to
+ * its HybridRouter). No runner → local-only. `escalate:false` = repair-only,
+ * never leaves the start tier (the "no escalation yet" mode).
+ */
+import { freeTierChat, resolveFreeTierProvider } from './provider.js';
+import { resolveTier } from './ladder.js';
+import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
+function normalizeVerdict(v) {
+    return typeof v === 'boolean' ? { passed: v } : v;
+}
+/**
+ * Executes QE tasks cheap-first with repair-then-escalate. Holds the per-agent
+ * adaptive base tier in an `AutoEscalationTracker`.
+ */
+export class FreeTierEscalatingExecutor {
+    ladder;
+    claudeRunner;
+    tracker;
+    env;
+    baseTier;
+    defaultRepairAttempts;
+    onOutcome;
+    /** Resolved cross-model generator pool (A12); undefined ⇒ single-model best-of-k. */
+    candidateProviders;
+    constructor(opts) {
+        this.ladder = opts.ladder;
+        this.claudeRunner = opts.claudeRunner;
+        this.env = opts.env ?? process.env;
+        this.onOutcome = opts.onOutcome;
+        this.defaultRepairAttempts = opts.defaultRepairAttempts ?? 0;
+        this.baseTier = opts.ladder.tierOrder[0];
+        this.candidateProviders = opts.candidateProviders?.length
+            ? opts.candidateProviders.map((c) => resolveFreeTierProvider(c, this.env))
+            : undefined;
+        this.tracker =
+            opts.tracker ??
+                new AutoEscalationTracker({
+                    tierOrder: opts.ladder.tierOrder,
+                    minTier: opts.ladder.minTier ?? opts.ladder.tierOrder[0],
+                    maxTier: opts.ladder.maxTier ?? opts.ladder.tierOrder[opts.ladder.tierOrder.length - 1],
+                    escalateAfterFailures: opts.ladder.escalateAfterFailures ?? 2,
+                    deEscalateAfterSuccesses: opts.ladder.deEscalateAfterSuccesses ?? 5,
+                });
+    }
+    /** Expose the tracker so a coordinator can inspect/share adaptation state. */
+    getTracker() {
+        return this.tracker;
+    }
+    /** Run ONE tier once; never throws — failure becomes `{ok:false}` so we repair/escalate. */
+    async runTier(resolved, messages) {
+        const started = Date.now();
+        if (resolved.provider === 'free-tier') {
+            const r = await freeTierChat(resolved.resolved, messages);
+            return { ok: r.ok, content: r.content, latencyMs: r.latencyMs, error: r.error };
+        }
+        if (!this.claudeRunner) {
+            return { ok: false, content: '', latencyMs: Date.now() - started, error: 'no claudeRunner (local-only mode)' };
+        }
+        try {
+            const r = await this.claudeRunner(resolved.claudeTier, messages);
+            return { ok: (r.content ?? '').trim().length > 0, content: r.content ?? '', latencyMs: Date.now() - started };
+        }
+        catch (e) {
+            return { ok: false, content: '', latencyMs: Date.now() - started, error: e.message };
+        }
+    }
+    /**
+     * Best-of-k diversity turn (06 §12): nudge the model toward a structurally
+     * different valid solution. Deterministic by `variant` index (no RNG) so runs
+     * replay identically.
+     */
+    diversify(base, variant) {
+        return [
+            ...base,
+            {
+                role: 'user',
+                content: `Alternative approach #${variant}: produce a different valid solution from any ` +
+                    `previous attempt — vary the structure/strategy, not just naming. Return the full output only.`,
+            },
+        ];
+    }
+    /** Build the D8 repair turn: show the model its rejected output + why. */
+    repairMessages(base, lastOutput, feedback) {
+        return [
+            ...base,
+            { role: 'assistant', content: lastOutput },
+            {
+                role: 'user',
+                content: 'That output did not pass verification' +
+                    (feedback ? `: ${feedback}` : '.') +
+                    ' Fix it and return the corrected full output only.',
+            },
+        ];
+    }
+    /**
+     * Execute a QE task cheap-first: try a tier, repair in place on failure, then
+     * (optionally) escalate to the next tier; repeat until pass or top.
+     */
+    async execute(req) {
+        const order = this.ladder.tierOrder;
+        const escalate = req.escalate ?? true;
+        const repairAttempts = req.repairAttempts ?? this.defaultRepairAttempts;
+        const bestOfK = Math.max(1, req.bestOfK ?? 1);
+        const objectiveOracle = (req.oracleKind ?? 'objective') === 'objective';
+        const startTier = this.tracker.getCurrentTier(req.agentId) ?? this.baseTier;
+        const startIdx = Math.max(0, order.indexOf(startTier));
+        const maxIdx = order.indexOf(this.ladder.maxTier ?? order[order.length - 1]);
+        const topIdx = escalate
+            ? (req.maxEscalations != null ? Math.min(startIdx + req.maxEscalations, maxIdx) : maxIdx)
+            : startIdx; // repair-only: never leave the start tier
+        const attempts = [];
+        let passedAtStart = false;
+        const t0 = Date.now();
+        let result = { ok: false, content: '', tierUsed: startTier, escalated: false, repaired: false, bestOf: false, goodhartGuarded: false, attempts };
+        outer: for (let idx = startIdx; idx <= topIdx; idx++) {
+            const tier = order[idx];
+            const resolved = resolveTier(this.ladder, tier, this.env);
+            // round 0 = best-of-k diverse attempts (06 §12); rounds 1..repairAttempts = single repair turns (D8)
+            // A12: at the START free tier, round-0 candidates draw from a CROSS-MODEL pool
+            // (diverse models cover each other's failures) instead of one model's variants.
+            const pool = this.candidateProviders;
+            const xModelHere = !!pool && idx === startIdx && resolved.provider === 'free-tier';
+            for (let round = 0; round <= repairAttempts; round++) {
+                const attemptsThisRound = round === 0 ? bestOfK : 1;
+                for (let k = 0; k < attemptsThisRound; k++) {
+                    const candProvider = round === 0 && xModelHere && pool ? pool[k % pool.length] : undefined;
+                    const candResolved = candProvider ? { provider: 'free-tier', resolved: candProvider } : resolved;
+                    const messages = round !== 0
+                        ? this.repairMessages(req.messages, result.content, attempts[attempts.length - 1]?.feedback)
+                        : candProvider
+                            // model difference IS the diversity; only nudge when k wraps past the pool
+                            ? (pool && k < pool.length ? req.messages : this.diversify(req.messages, k))
+                            : (k === 0 ? req.messages : this.diversify(req.messages, k));
+                    const run = await this.runTier(candResolved, messages);
+                    const verdict = run.ok ? normalizeVerdict(await Promise.resolve(req.verify(run.content))) : { passed: false, feedback: run.error };
+                    attempts.push({ tier, provider: candResolved.provider, repairRound: round, variant: round === 0 ? k : undefined, model: candProvider?.model, ok: run.ok, passed: verdict.passed, latencyMs: run.latencyMs, feedback: verdict.feedback, error: run.error });
+                    // start-tier capability for adaptation: did ANY round-0 attempt pass?
+                    if (idx === startIdx && round === 0 && verdict.passed)
+                        passedAtStart = true;
+                    if (verdict.passed) {
+                        result = { ok: true, content: run.content, tierUsed: tier, escalated: idx > startIdx, repaired: round > 0, bestOf: round === 0 && k > 0, goodhartGuarded: false, attempts };
+                        break outer;
+                    }
+                    result = { ok: false, content: run.content || result.content, tierUsed: tier, escalated: idx > startIdx, repaired: round > 0, bestOf: false, goodhartGuarded: false, attempts };
+                }
+            }
+        }
+        // Goodhart guard (06 §10): only an OBJECTIVE ground-truth oracle may move
+        // routing-feedback. A self-authored gate is an unreliable selection target —
+        // record nothing, so a Goodharted self-test pass can never lift confidence.
+        result.goodhartGuarded = !objectiveOracle;
+        if (objectiveOracle) {
+            // Cross-task adaptation: feed the START-tier verdict to the tracker so the
+            // base tier drifts up when the cheap tier keeps failing, down when it wins.
+            this.tracker.recordOutcome(req.agentId, passedAtStart, this.baseTier);
+            this.onOutcome?.({
+                agentId: req.agentId,
+                startTier,
+                tierUsed: result.tierUsed,
+                passed: result.ok,
+                escalated: result.escalated,
+                repaired: result.repaired,
+                durationMs: Date.now() - t0,
+                attempts: attempts.length,
+            });
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/routing/free-tier/feedback-sink.d.ts

@@ -0,0 +1,49 @@
+/**
+ * D9 — route free-tier executor outcomes into the existing routing-feedback
+ * machinery so the stuck-at-40% routing confidence starts moving from REAL
+ * cheap-vs-escalated results.
+ *
+ * `RoutingFeedbackCollector.recordOutcome` already updates the calibrator, the
+ * auto-escalation tracker, the economic model, and the confidence metrics. This
+ * adapter maps a `FreeTierEscalatingExecutor.onOutcome` event onto that call,
+ * constructing a minimal-but-valid QETask + synthetic QERoutingDecision.
+ *
+ * Decoupled by a structural interface (`RoutingFeedbackLike`) so this module has
+ * no hard dependency on the concrete collector's constructor/DB — the coordinator
+ * passes whatever it already holds, and tests pass a stub.
+ */
+import type { QETask, QERoutingDecision, RoutingOutcome } from '../types.js';
+/** The slice of RoutingFeedbackCollector this adapter needs. */
+export interface RoutingFeedbackLike {
+    recordOutcome(task: QETask, decision: QERoutingDecision, usedAgent: string, outcome: {
+        success: boolean;
+        qualityScore: number;
+        durationMs: number;
+        error?: string;
+    }): RoutingOutcome;
+}
+/** The executor's onOutcome payload (kept structural to avoid a circular import). */
+export interface FreeTierOutcomeEvent {
+    agentId: string;
+    startTier: string;
+    tierUsed: string;
+    passed: boolean;
+    escalated: boolean;
+    repaired: boolean;
+    durationMs: number;
+    attempts: number;
+}
+export interface RoutingFeedbackSinkOptions {
+    /** Short label for the task description (e.g. 'test-generation'). */
+    taskKind?: string;
+    /** Confidence to attribute to the cheap-first decision (0..1). Default 0.5. */
+    decisionConfidence?: number;
+}
+/**
+ * Build an `onOutcome` handler that records each free-tier task result into the
+ * routing-feedback collector. `usedAgent` is set to the TIER that produced the
+ * result so the calibrator/escalation tracker learn per-tier reliability — i.e.
+ * sustained cheap-tier wins raise its confidence and keep work cheap.
+ */
+export declare function createRoutingFeedbackSink(collector: RoutingFeedbackLike, opts?: RoutingFeedbackSinkOptions): (o: FreeTierOutcomeEvent) => void;
+//# sourceMappingURL=feedback-sink.d.ts.map

package/dist/routing/free-tier/feedback-sink.js

@@ -0,0 +1,52 @@
+/**
+ * D9 — route free-tier executor outcomes into the existing routing-feedback
+ * machinery so the stuck-at-40% routing confidence starts moving from REAL
+ * cheap-vs-escalated results.
+ *
+ * `RoutingFeedbackCollector.recordOutcome` already updates the calibrator, the
+ * auto-escalation tracker, the economic model, and the confidence metrics. This
+ * adapter maps a `FreeTierEscalatingExecutor.onOutcome` event onto that call,
+ * constructing a minimal-but-valid QETask + synthetic QERoutingDecision.
+ *
+ * Decoupled by a structural interface (`RoutingFeedbackLike`) so this module has
+ * no hard dependency on the concrete collector's constructor/DB — the coordinator
+ * passes whatever it already holds, and tests pass a stub.
+ */
+/**
+ * Build an `onOutcome` handler that records each free-tier task result into the
+ * routing-feedback collector. `usedAgent` is set to the TIER that produced the
+ * result so the calibrator/escalation tracker learn per-tier reliability — i.e.
+ * sustained cheap-tier wins raise its confidence and keep work cheap.
+ */
+export function createRoutingFeedbackSink(collector, opts = {}) {
+    const kind = opts.taskKind ?? 'free-tier-qe';
+    const confidence = opts.decisionConfidence ?? 0.5;
+    return (o) => {
+        const task = {
+            description: `${kind} task for ${o.agentId} (start=${o.startTier}${o.repaired ? ', repaired' : ''}${o.escalated ? ', escalated' : ''})`,
+        };
+        const decision = {
+            recommended: o.startTier, // cheap-first recommended the bottom tier
+            confidence,
+            alternatives: [],
+            reasoning: `free-tier cheap-first; resolved at ${o.tierUsed} after ${o.attempts} attempt(s)`,
+            scores: { similarity: 0, performance: o.passed ? 1 : 0, capabilities: 0, combined: o.passed ? 1 : 0 },
+            latencyMs: o.durationMs,
+            timestamp: new Date(),
+        };
+        // qualityScore: full marks on a clean cheap win; reduced when repair/escalation
+        // was needed (still a success, but it cost more) so the calibrator learns nuance.
+        const qualityScore = o.passed ? (o.escalated ? 0.6 : o.repaired ? 0.8 : 1.0) : 0;
+        try {
+            collector.recordOutcome(task, decision, o.tierUsed, {
+                success: o.passed,
+                qualityScore,
+                durationMs: o.durationMs,
+            });
+        }
+        catch {
+            // Feedback recording is best-effort — never break the QE task on a sink error.
+        }
+    };
+}
+//# sourceMappingURL=feedback-sink.js.map

package/dist/routing/free-tier/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Free-tier routing (cross-pollination plan 06, D7).
+ *
+ * Adds a configurable FREE / low-cost model tier below haiku in the escalation
+ * ladder: local Ollama, cloud Ollama, OpenRouter, or any OpenAI-compatible
+ * endpoint. Cheap-local handles the bulk; only failures escalate up the chain.
+ * See docs/metaharness/06-darwin-qe-self-learning-action-lane.md (D7).
+ */
+export type { FreeTierKind, FreeTierProviderConfig, ResolvedFreeTierProvider, TierBinding, QeRoutingLadder, } from './types.js';
+export { FREE_TIER_PRESETS, resolveFreeTierProvider, freeTierChat, freeTierHealth, type ChatMessage, type FreeTierChatResult, } from './provider.js';
+export { defaultFreeTierLadder, validateLadder, createFreeTierEscalation, resolveTier, type ResolvedTier, } from './ladder.js';
+export { FreeTierEscalatingExecutor, type ClaudeTierRunner, type QeVerifier, type QeVerdict, type QeTaskRequest, type QeExecutionResult, type TierAttempt, type FreeTierExecutorOptions, } from './executor.js';
+export { createRoutingFeedbackSink, type RoutingFeedbackLike, type FreeTierOutcomeEvent, type RoutingFeedbackSinkOptions, } from './feedback-sink.js';
+export { buildFreeTierExecutor, runFreeTierTextTask, DEFAULT_FREE_TIER_MODEL, type FreeTierCoordinatorConfig, type FreeTierLlmRouter, type BuildFreeTierExecutorOptions, } from './coordinator-support.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/routing/free-tier/index.js

@@ -0,0 +1,6 @@
+export { FREE_TIER_PRESETS, resolveFreeTierProvider, freeTierChat, freeTierHealth, } from './provider.js';
+export { defaultFreeTierLadder, validateLadder, createFreeTierEscalation, resolveTier, } from './ladder.js';
+export { FreeTierEscalatingExecutor, } from './executor.js';
+export { createRoutingFeedbackSink, } from './feedback-sink.js';
+export { buildFreeTierExecutor, runFreeTierTextTask, DEFAULT_FREE_TIER_MODEL, } from './coordinator-support.js';
+//# sourceMappingURL=index.js.map

package/dist/routing/free-tier/ladder.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Free-tier escalation ladder (D7).
+ *
+ * Ties the configurable provider layer to the real `AutoEscalationTracker`:
+ * builds a tracker whose ladder starts at a FREE tier and escalates up the
+ * existing Claude tiers on failure (Ruv's Round-3 economics), and resolves any
+ * tier name to the concrete provider that should serve it.
+ */
+import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
+import type { ResolvedFreeTierProvider, QeRoutingLadder } from './types.js';
+import type { AgentTier } from '../routing-config.js';
+/**
+ * A ready-to-use, opinionated default: a free local Ollama tier under the three
+ * Claude tiers. Override `bindings.local.config.model` / `.kind` to point at
+ * cloud Ollama, OpenRouter, or any compatible endpoint.
+ */
+export declare function defaultFreeTierLadder(model?: string): QeRoutingLadder;
+/** Validate a ladder: every tier in `tierOrder` must have a binding, bounds must exist. */
+export declare function validateLadder(ladder: QeRoutingLadder): void;
+/**
+ * Build an `AutoEscalationTracker` over the ladder's string tiers. Agents start
+ * at the bottom (free) tier; consecutive failures escalate, successes de-escalate
+ * — bounded by min/maxTier. Reuses the unchanged, tested tracker engine.
+ */
+export declare function createFreeTierEscalation(ladder: QeRoutingLadder): {
+    tracker: AutoEscalationTracker<string>;
+    baseTier: string;
+};
+export type ResolvedTier = {
+    provider: 'claude';
+    claudeTier: AgentTier;
+} | {
+    provider: 'free-tier';
+    resolved: ResolvedFreeTierProvider;
+};
+/**
+ * Resolve a tier name to the concrete handler: either a Claude tier (for the
+ * existing router) or a fully-resolved free-tier provider (env key read here).
+ */
+export declare function resolveTier(ladder: QeRoutingLadder, tier: string, env?: NodeJS.ProcessEnv): ResolvedTier;
+//# sourceMappingURL=ladder.d.ts.map

package/dist/routing/free-tier/ladder.js

@@ -0,0 +1,78 @@
+/**
+ * Free-tier escalation ladder (D7).
+ *
+ * Ties the configurable provider layer to the real `AutoEscalationTracker`:
+ * builds a tracker whose ladder starts at a FREE tier and escalates up the
+ * existing Claude tiers on failure (Ruv's Round-3 economics), and resolves any
+ * tier name to the concrete provider that should serve it.
+ */
+import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
+import { resolveFreeTierProvider } from './provider.js';
+/**
+ * A ready-to-use, opinionated default: a free local Ollama tier under the three
+ * Claude tiers. Override `bindings.local.config.model` / `.kind` to point at
+ * cloud Ollama, OpenRouter, or any compatible endpoint.
+ */
+export function defaultFreeTierLadder(model = 'qwen3:8b') {
+    return {
+        tierOrder: ['local', 'haiku', 'sonnet', 'opus'],
+        minTier: 'local',
+        maxTier: 'opus',
+        escalateAfterFailures: 2,
+        deEscalateAfterSuccesses: 5,
+        bindings: {
+            local: { provider: 'free-tier', config: { kind: 'local-ollama', model } },
+            haiku: { provider: 'claude', claudeTier: 'haiku' },
+            sonnet: { provider: 'claude', claudeTier: 'sonnet' },
+            opus: { provider: 'claude', claudeTier: 'opus' },
+        },
+    };
+}
+/** Validate a ladder: every tier in `tierOrder` must have a binding, bounds must exist. */
+export function validateLadder(ladder) {
+    if (ladder.tierOrder.length === 0)
+        throw new Error('free-tier ladder: tierOrder is empty');
+    for (const tier of ladder.tierOrder) {
+        if (!ladder.bindings[tier])
+            throw new Error(`free-tier ladder: no binding for tier "${tier}"`);
+    }
+    const min = ladder.minTier ?? ladder.tierOrder[0];
+    const max = ladder.maxTier ?? ladder.tierOrder[ladder.tierOrder.length - 1];
+    if (!ladder.tierOrder.includes(min))
+        throw new Error(`free-tier ladder: minTier "${min}" not in tierOrder`);
+    if (!ladder.tierOrder.includes(max))
+        throw new Error(`free-tier ladder: maxTier "${max}" not in tierOrder`);
+    if (ladder.tierOrder.indexOf(min) > ladder.tierOrder.indexOf(max)) {
+        throw new Error('free-tier ladder: minTier is above maxTier');
+    }
+}
+/**
+ * Build an `AutoEscalationTracker` over the ladder's string tiers. Agents start
+ * at the bottom (free) tier; consecutive failures escalate, successes de-escalate
+ * — bounded by min/maxTier. Reuses the unchanged, tested tracker engine.
+ */
+export function createFreeTierEscalation(ladder) {
+    validateLadder(ladder);
+    const tracker = new AutoEscalationTracker({
+        tierOrder: ladder.tierOrder,
+        minTier: ladder.minTier ?? ladder.tierOrder[0],
+        maxTier: ladder.maxTier ?? ladder.tierOrder[ladder.tierOrder.length - 1],
+        escalateAfterFailures: ladder.escalateAfterFailures ?? 2,
+        deEscalateAfterSuccesses: ladder.deEscalateAfterSuccesses ?? 5,
+    });
+    return { tracker, baseTier: ladder.tierOrder[0] };
+}
+/**
+ * Resolve a tier name to the concrete handler: either a Claude tier (for the
+ * existing router) or a fully-resolved free-tier provider (env key read here).
+ */
+export function resolveTier(ladder, tier, env = process.env) {
+    const binding = ladder.bindings[tier];
+    if (!binding)
+        throw new Error(`free-tier ladder: no binding for tier "${tier}"`);
+    if (binding.provider === 'claude') {
+        return { provider: 'claude', claudeTier: binding.claudeTier };
+    }
+    return { provider: 'free-tier', resolved: resolveFreeTierProvider(binding.config, env) };
+}
+//# sourceMappingURL=ladder.js.map

package/dist/routing/free-tier/provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Free-tier provider resolver + OpenAI-compatible chat (D7).
+ *
+ * Pure resolution (presets + env key) is split from the network call so the
+ * config logic is unit-testable without a server. The chat call targets the
+ * universal `/v1/chat/completions` shape (verified live against the M5 host
+ * Ollama on 2026-06-19) and is reasoning-model aware.
+ */
+import type { FreeTierKind, FreeTierProviderConfig, ResolvedFreeTierProvider } from './types.js';
+interface Preset {
+    baseUrl: string;
+    apiKeyEnv?: string;
+    /** True when this endpoint normally requires a key (→ missingKey flag). */
+    requiresKey: boolean;
+}
+/**
+ * Endpoint presets. `local-ollama` defaults to the Docker-Desktop host gateway
+ * (the M5 host) — override baseUrl to 'http://localhost:11434/v1' for a same-box
+ * Ollama. `openai-compatible` has no default URL (the caller must supply one).
+ */
+export declare const FREE_TIER_PRESETS: Record<FreeTierKind, Preset>;
+/**
+ * Merge a config with its preset, read the API key from the named env var, and
+ * produce a ready-to-call provider. Pure except for the single `process.env`
+ * read (injectable via `env` for testing). Throws only on a structural error
+ * (openai-compatible without a baseUrl); a missing key is flagged, not thrown,
+ * so the caller can decide (some local endpoints accept any/no key).
+ */
+export declare function resolveFreeTierProvider(cfg: FreeTierProviderConfig, env?: NodeJS.ProcessEnv): ResolvedFreeTierProvider;
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface FreeTierChatResult {
+    ok: boolean;
+    /** Assistant text (answer channel only when contentOnly). Empty on failure. */
+    content: string;
+    /** Reasoning channel, when the model exposes one separately. */
+    reasoning?: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    error?: string;
+    latencyMs: number;
+}
+/**
+ * One OpenAI-compatible chat completion. Never throws — a transport/timeout/HTTP
+ * error returns `{ ok:false, error }` so an escalation loop treats it as a tier
+ * failure (and escalates) rather than crashing.
+ */
+export declare function freeTierChat(provider: ResolvedFreeTierProvider, messages: ChatMessage[]): Promise<FreeTierChatResult>;
+/** Cheap liveness probe for a free-tier endpoint (Ollama /api/tags style or a tiny chat). */
+export declare function freeTierHealth(provider: ResolvedFreeTierProvider): Promise<boolean>;
+export {};
+//# sourceMappingURL=provider.d.ts.map

package/dist/routing/free-tier/provider.js

@@ -0,0 +1,111 @@
+/**
+ * Free-tier provider resolver + OpenAI-compatible chat (D7).
+ *
+ * Pure resolution (presets + env key) is split from the network call so the
+ * config logic is unit-testable without a server. The chat call targets the
+ * universal `/v1/chat/completions` shape (verified live against the M5 host
+ * Ollama on 2026-06-19) and is reasoning-model aware.
+ */
+/**
+ * Endpoint presets. `local-ollama` defaults to the Docker-Desktop host gateway
+ * (the M5 host) — override baseUrl to 'http://localhost:11434/v1' for a same-box
+ * Ollama. `openai-compatible` has no default URL (the caller must supply one).
+ */
+export const FREE_TIER_PRESETS = {
+    'local-ollama': { baseUrl: 'http://host.docker.internal:11434/v1', requiresKey: false },
+    'cloud-ollama': { baseUrl: 'https://ollama.com/v1', apiKeyEnv: 'OLLAMA_API_KEY', requiresKey: true },
+    openrouter: { baseUrl: 'https://openrouter.ai/api/v1', apiKeyEnv: 'OPENROUTER_API_KEY', requiresKey: true },
+    'openai-compatible': { baseUrl: '', requiresKey: false },
+};
+/**
+ * Merge a config with its preset, read the API key from the named env var, and
+ * produce a ready-to-call provider. Pure except for the single `process.env`
+ * read (injectable via `env` for testing). Throws only on a structural error
+ * (openai-compatible without a baseUrl); a missing key is flagged, not thrown,
+ * so the caller can decide (some local endpoints accept any/no key).
+ */
+export function resolveFreeTierProvider(cfg, env = process.env) {
+    const preset = FREE_TIER_PRESETS[cfg.kind];
+    if (!preset)
+        throw new Error(`free-tier: unknown provider kind "${cfg.kind}"`);
+    const baseUrl = (cfg.baseUrl ?? preset.baseUrl).replace(/\/$/, '');
+    if (!baseUrl) {
+        throw new Error(`free-tier: kind "${cfg.kind}" requires an explicit baseUrl`);
+    }
+    const keyEnvName = cfg.apiKeyEnv ?? preset.apiKeyEnv;
+    const apiKey = keyEnvName ? (env[keyEnvName] ?? '').trim() : '';
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey)
+        headers.Authorization = `Bearer ${apiKey}`;
+    // OpenRouter etiquette headers (harmless elsewhere).
+    if (cfg.kind === 'openrouter') {
+        headers['HTTP-Referer'] = 'https://github.com/proffesor-for-testing/agentic-qe';
+        headers['X-Title'] = 'agentic-qe';
+    }
+    return {
+        kind: cfg.kind,
+        model: cfg.model,
+        baseUrl,
+        headers,
+        timeoutMs: cfg.timeoutMs ?? 120_000,
+        maxTokens: cfg.maxTokens ?? 2048,
+        temperature: cfg.temperature ?? 0.2,
+        contentOnly: cfg.contentOnly ?? true,
+        missingKey: preset.requiresKey && !apiKey,
+    };
+}
+/**
+ * One OpenAI-compatible chat completion. Never throws — a transport/timeout/HTTP
+ * error returns `{ ok:false, error }` so an escalation loop treats it as a tier
+ * failure (and escalates) rather than crashing.
+ */
+export async function freeTierChat(provider, messages) {
+    const started = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), provider.timeoutMs);
+    try {
+        const res = await fetch(`${provider.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: provider.headers,
+            body: JSON.stringify({
+                model: provider.model,
+                messages,
+                max_tokens: provider.maxTokens,
+                temperature: provider.temperature,
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            return { ok: false, content: '', error: `HTTP ${res.status}: ${body.slice(0, 200)}`, latencyMs: Date.now() - started };
+        }
+        const j = (await res.json());
+        const msg = j.choices?.[0]?.message;
+        const content = (msg?.content ?? '').trim();
+        const reasoning = msg?.reasoning?.trim();
+        const text = provider.contentOnly || !reasoning ? content : `${reasoning}\n${content}`.trim();
+        return {
+            ok: text.length > 0,
+            content: text,
+            reasoning,
+            usage: j.usage
+                ? { promptTokens: j.usage.prompt_tokens, completionTokens: j.usage.completion_tokens, totalTokens: j.usage.total_tokens }
+                : undefined,
+            error: text.length === 0 ? 'empty content' : undefined,
+            latencyMs: Date.now() - started,
+        };
+    }
+    catch (e) {
+        return { ok: false, content: '', error: e.message, latencyMs: Date.now() - started };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Cheap liveness probe for a free-tier endpoint (Ollama /api/tags style or a tiny chat). */
+export async function freeTierHealth(provider) {
+    const r = await freeTierChat(provider, [{ role: 'user', content: 'ping' }]);
+    // A transport success (ok OR an "empty content" non-error reply) counts as alive.
+    return r.ok || r.error === 'empty content';
+}
+//# sourceMappingURL=provider.js.map