modelrig 0.0.1 → 0.2.0

package/dist/run/run.js

@@ -0,0 +1,540 @@
+"use strict";
+/**
+ * The run loop — spec §4, plan §4/step 6. State machine:
+ *   resolve → render → (envelope check) → dispatch → validate
+ *     → retry per failure class | advance candidate | fail typed | succeed
+ *   → record telemetry on every INFERENCE exit path (RouteConfigError exits
+ *     record nothing by design — config errors precede any dispatch; C1
+ *     ruling 2 / finding F3).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const loader_1 = require("../routes/loader");
+const serveability_1 = require("../routes/serveability");
+const template_1 = require("../routes/template");
+const cost_1 = require("./cost");
+const pricing_1 = require("../registry/pricing");
+const failures_1 = require("../types/failures");
+const manifest_1 = require("../routes/manifest");
+const resolve_1 = require("./resolve");
+const envelope_1 = require("./envelope");
+const retry_1 = require("./retry");
+const repair_1 = require("./repair");
+const grounding_1 = require("./grounding");
+const validate_1 = require("./validate");
+const dispatch_1 = require("./dispatch");
+const record_attempt_1 = require("./record-attempt");
+const run_context_1 = require("../artifacts/run-context");
+const capture_write_1 = require("./capture-write");
+/** Look up a named variant; null = default (base config). Unknown names are
+ * config errors — the caller asked for something the bundle doesn't define. */
+function resolveVariant(route, name) {
+    if (name === undefined || name === "default")
+        return null;
+    const variant = route.variants.find((v) => v.name === name);
+    if (variant === undefined) {
+        throw new loader_1.RouteConfigError(`route "${route.route}" has no variant "${name}" — defined: [${route.variants
+            .map((v) => v.name)
+            .join(", ")}]`);
+    }
+    return variant;
+}
+/** The variant-effective view of a route: narrowed candidates, overridden
+ * json rung, overridden template. Loader validation guarantees variant
+ * candidates ⊆ declared candidates, so the candidate-set invariant holds. */
+function effectiveRoute(route, variant) {
+    if (variant === null)
+        return route;
+    return Object.freeze({
+        ...route,
+        candidates: variant.candidates ?? route.candidates,
+        systemTemplate: variant.promptOverride ?? route.systemTemplate,
+        policy: Object.freeze({
+            ...route.policy,
+            json: variant.json ?? route.policy.json,
+        }),
+    });
+}
+/** Phase 1 prompt convention: the bundle's system template carries the whole
+ * task (constitution, data, step instructions); the user turn is a terse
+ * trigger. Providers treat long system prompts + short user turns well, and
+ * it keeps the single-template bundle contract of spec §3. */
+const USER_DIRECTIVE = "Produce the required output now, following the system instructions exactly.";
+/** User turn for repair calls (WS2) — same terse-trigger convention. */
+const REPAIR_DIRECTIVE = "Produce the corrected JSON object now, following the system instructions exactly.";
+/** Schema coaching for the json_mode rung — ported from the production
+ * DeepSeek provider's schema-in-prompt guidance (minLength-is-a-FLOOR etc.). */
+function jsonModeCoaching(schema) {
+    return ("\n\n---\nOUTPUT FORMAT (STRICT): Respond with a SINGLE valid JSON object and nothing else — " +
+        'no markdown fences, no introductory text, no sign-off. Your response MUST start with "{" and ' +
+        'end with "}". Sanitize every nested string so embedded quotes/brackets do not break the root ' +
+        "JSON escaping. The object MUST conform to this JSON Schema — match key names and types " +
+        "EXACTLY, include ALL required fields, and do not add commentary fields. CRITICAL: where the " +
+        "schema sets a minLength on a narrative/prose field, that is a FLOOR, not a target — write " +
+        "thorough, non-repetitive analysis that comfortably EXCEEDS the minimum (do not pad with " +
+        "repetition; add real substance). When unsure how long to make a prose field, write more, " +
+        `not less:\n\n${JSON.stringify(schema)}`);
+}
+/** prefer:[cost] ordering metric — combined input+output USD per million
+ * tokens from the pricing snapshot; null (unknown) sorts last in resolve. */
+function costPerMTok(provider, model) {
+    const pricing = (0, pricing_1.getPricing)(provider, model);
+    if (pricing === null)
+        return null;
+    return (pricing.inputUsdPerTok + pricing.outputUsdPerTok) * 1000000;
+}
+const DEFAULT_SLEEP = (ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
+async function run(deps, routeName, opts) {
+    const baseRoute = deps.routes.get(routeName);
+    const variant = resolveVariant(baseRoute, opts.variant);
+    const servedVariant = variant?.name ?? null;
+    const route = (0, resolve_1.applyRunRequirements)(effectiveRoute(baseRoute, variant), opts.zeroRetention === true);
+    const effectiveTags = route.require.includes("zero_retention") ? { ...opts.tags, zdr_enforced: "true" } : opts.tags;
+    // Data-hygiene warning (spec WS5): once per process per dimension.
+    (0, manifest_1.warnMissingRequiredDimensions)(deps.manifest ?? null, opts.tags);
+    const ledger = (0, retry_1.createRetryLedger)(route.policy);
+    const sleep = deps.sleep ?? DEFAULT_SLEEP;
+    const guard = opts.budget
+        ? (0, envelope_1.createEnvelopeGuard)(deps.telemetry, opts.budget.envelope, 
+        // A per-run budget (the mirror lane's per-org cap) overrides the rig
+        // default when THIS run first opens the envelope (open-or-get).
+        opts.budget.budgetUsd ?? deps.envelopeBudgetUsd)
+        : null;
+    // Addendum A1: per-token conservative rate for models without pricing —
+    // used for envelope precheck/settlement ONLY (telemetry stays honest-zero).
+    const unpricedRatePerTok = (deps.unpricedRateUsdPerMTok ?? cost_1.DEFAULT_UNPRICED_RATE_USD_PER_MTOK) / 1000000;
+    const declared = new Set(route.candidates.map((c) => `${c.provider} ${c.model}`));
+    // Auto-step (E2 chunk A, spec §1.4): with an active run context, each attempt
+    // exit that records an inference also records a ground-truth step referencing
+    // it (attempt-per-row, ruling c). Inert without a run.start on this path.
+    const runCtx = (0, run_context_1.getActiveRunContext)();
+    const autoStepKey = runCtx !== null ? runCtx.nextStepKey(route.route) : null;
+    // Capture-WRITE gate (settings-plane §1.5, closes gate 5): the control-plane
+    // capture flag wins over the YAML flag, the task's scrub setting is honored,
+    // and capture OFF is a no-op writer (byte-identical). See ./capture-write.ts.
+    const captureAttempt = (0, capture_write_1.buildCaptureWriter)(deps.settings ?? null, deps.captures, route, opts.input);
+    const droppedCacheHandle = new Set(); // CE-1 retry-drop (spec §2.2)
+    // Per-attempt telemetry recorder (extracted to ./record-attempt.ts — WS-A,
+    // to keep run.ts under the LOC cap and shrink the run-loop conflict surface).
+    const recordAttempt = (0, record_attempt_1.createRecordAttempt)({
+        telemetry: deps.telemetry,
+        route,
+        ledger,
+        effectiveTags,
+        servedVariant,
+        runCtx,
+        autoStepKey,
+        cache: opts.cache,
+        droppedCacheHandle,
+    });
+    function failRun(candidate, failure, latencyMs) {
+        recordAttempt({
+            candidate,
+            servedTier: route.policy.tier,
+            tokensIn: 0,
+            tokensOut: 0,
+            tokensCached: 0,
+            costUsd: 0,
+            latencyMs,
+            failure,
+        });
+        throw new failures_1.RigFailureError(failure);
+    }
+    // Repair rung (WS2): variant repair config wins over the route's; its own
+    // budget, never fungible with the content_invalid class budget.
+    const repairLedger = (0, repair_1.createRepairLedger)(variant?.repair ?? baseRoute.repair);
+    /** One repair dispatch. Returns {done} on schema-valid output, {invalid}
+     * with the newest output+errors for chaining, or null when the dispatch
+     * itself failed (adapter failure / unmintable repair candidate). */
+    async function attemptRepair(step, original, originalSystemPrompt, invalidText, errors) {
+        let repairCandidate;
+        let systemPrompt;
+        if (step.kind === "same_model") {
+            repairCandidate = original;
+            systemPrompt = originalSystemPrompt + (0, repair_1.repairFeedbackBlock)(errors);
+        }
+        else {
+            // Brand stays in resolve.ts; loader validated repairModel ⊆ declared.
+            const minted = (0, resolve_1.resolveDeclaredCandidate)(route, step.model);
+            if (minted === null)
+                return null;
+            repairCandidate = minted;
+            systemPrompt = (0, repair_1.repairModelPrompt)(invalidText, errors, route.outputSchema);
+        }
+        const repairedBy = `${repairCandidate.provider}/${repairCandidate.model}`;
+        const adapter = deps.adapters.get(repairCandidate.provider);
+        if (adapter === undefined)
+            return null;
+        if (guard !== null) {
+            // A1: unpriced repair models fail closed exactly like primaries.
+            const breach = guard.precheck((0, cost_1.dispatchEstimateUsd)(repairCandidate.provider, repairCandidate.model, systemPrompt.length + REPAIR_DIRECTIVE.length, unpricedRatePerTok));
+            if (breach !== null) {
+                failRun(repairCandidate, breach, 0);
+            }
+        }
+        const started = Date.now();
+        const result = await adapter.call((0, dispatch_1.buildRepairAdapterRequest)(route, repairCandidate, systemPrompt, REPAIR_DIRECTIVE));
+        const latencyMs = Date.now() - started;
+        if (!result.ok) {
+            let cost = 0;
+            let repairFailurePricingMissing = false;
+            if (result.usage !== undefined) {
+                const settled = (0, cost_1.attemptCost)(repairCandidate.provider, repairCandidate.model, result.usage, unpricedRatePerTok);
+                cost = settled.costUsd;
+                repairFailurePricingMissing = settled.pricingMissing;
+                guard?.settle(settled.envelopeChargeUsd);
+            }
+            recordAttempt({
+                candidate: repairCandidate,
+                servedTier: result.usage?.servedTier ?? route.policy.tier,
+                tokensIn: result.usage?.tokensIn ?? 0,
+                tokensOut: result.usage?.tokensOut ?? 0,
+                tokensCached: result.usage?.tokensCached ?? 0,
+                tokensCacheWrite: result.usage?.tokensCacheWrite ?? 0,
+                tokensCacheWrite1h: result.usage?.tokensCacheWrite1h ?? 0,
+                costUsd: cost,
+                latencyMs,
+                ...(result.usage?.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+                failure: result.failure,
+                repairedBy,
+                pricingMissing: repairFailurePricingMissing,
+            });
+            if (failures_1.TERMINAL_CLASSES.has(result.failure.class)) {
+                throw new failures_1.RigFailureError(result.failure);
+            }
+            return null;
+        }
+        const { costUsd, envelopeChargeUsd, pricingMissing: repairPricingMissing, } = (0, cost_1.attemptCost)(repairCandidate.provider, repairCandidate.model, result.usage, unpricedRatePerTok);
+        guard?.settle(envelopeChargeUsd);
+        const outcome = (0, validate_1.validateOutput)(route, result.text);
+        const failure = outcome.valid
+            ? null
+            : {
+                class: "content_invalid",
+                message: `repair output failed schema validation: ${outcome.errors.join("; ")}`,
+                provider: repairCandidate.provider,
+                model: repairCandidate.model,
+            };
+        const inferenceId = recordAttempt({
+            candidate: repairCandidate,
+            servedTier: result.usage.servedTier,
+            tokensIn: result.usage.tokensIn,
+            tokensOut: result.usage.tokensOut,
+            tokensCached: result.usage.tokensCached,
+            tokensCacheWrite: result.usage.tokensCacheWrite ?? 0,
+            tokensCacheWrite1h: result.usage.tokensCacheWrite1h ?? 0,
+            costUsd,
+            latencyMs,
+            ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+            failure,
+            repairedBy,
+            pricingMissing: repairPricingMissing,
+        });
+        captureAttempt(inferenceId, result.text);
+        if (!outcome.valid) {
+            return { invalid: { text: result.text, errors: outcome.errors } };
+        }
+        return {
+            done: {
+                output: outcome.parsed,
+                meta: {
+                    inferenceId,
+                    route: route.route,
+                    routeVersion: route.version,
+                    provider: repairCandidate.provider,
+                    model: repairCandidate.model,
+                    requestedTier: route.policy.tier,
+                    servedTier: result.usage.servedTier,
+                    tokensIn: result.usage.tokensIn,
+                    tokensOut: result.usage.tokensOut,
+                    tokensCached: result.usage.tokensCached,
+                    costEstimateUsd: costUsd,
+                    latencyMs,
+                    validated: true,
+                    attemptsByClass: ledger.snapshot(),
+                    servedVariant,
+                    repairedBy,
+                    ...(injectedSources !== null
+                        ? { citations: (0, grounding_1.extractCitations)(result.text, injectedSources) }
+                        : {}),
+                },
+            },
+        };
+    }
+    const searchAvailable = deps.search !== undefined && deps.search !== null;
+    const iter = (0, resolve_1.resolveCandidates)(route, deps.capabilities, costPerMTok, searchAvailable, (0, resolve_1.candidateFilterFromOptions)(opts));
+    let candidate = iter.next();
+    if (candidate === null) {
+        throw new loader_1.RouteConfigError(`route "${route.route}" has no eligible candidate — none of the declared candidates ` +
+            `satisfy require=[${route.require.join(", ")}] with json=${route.policy.json}${(0, resolve_1.filterSummary)(opts)}`);
+    }
+    let lastFailure = null;
+    // Grounding-inject (WS3): one search per run, cached across candidates and
+    // retries; cost accrues to the envelope and its own telemetry row.
+    let searchResponse = null;
+    let injectedSources = null;
+    while (candidate !== null) {
+        // Runtime layer of the candidate-set invariant: even a compromised
+        // iterator cannot reach an adapter with a pair outside the declared list.
+        // Runs BEFORE the adapter lookup so a corrupted pair with an unregistered
+        // provider still fails as invariant_violation (with a telemetry row),
+        // never as a plain config error.
+        if (!declared.has(`${candidate.provider} ${candidate.model}`)) {
+            failRun(candidate, {
+                class: "invariant_violation",
+                message: `candidate (${candidate.provider}, ${candidate.model}) is not in route ` +
+                    `"${route.route}"'s declared candidate list — refusing to dispatch`,
+                provider: candidate.provider,
+                model: candidate.model,
+            }, 0);
+        }
+        const adapter = deps.adapters.get(candidate.provider);
+        if (adapter === undefined) {
+            // Phase 4 resilience: a keyless declared candidate is INERT — skip to
+            // the next (the invariant guard above already OK'd the pair); nothing
+            // dispatched, so nothing billed. All-inert surfaces via the final throw.
+            lastFailure = (0, serveability_1.inertCandidateFailure)(candidate, route.route);
+            candidate = iter.next();
+            continue;
+        }
+        // Render against the SERVING candidate's capability flags.
+        const flags = deps.capabilities(candidate.provider, candidate.model);
+        let systemPrompt = (0, template_1.renderTemplate)(route.systemTemplate, {
+            variables: opts.input,
+            capabilities: flags,
+        });
+        // Variant augmentation (WS1): appended after capability-conditionals,
+        // before json coaching — promptAppend first, then the reasoning scaffold.
+        if (variant?.promptAppend !== undefined) {
+            systemPrompt += `\n\n${variant.promptAppend}`;
+        }
+        if (variant?.scaffold !== undefined) {
+            systemPrompt += `\n\n${variant.scaffold}`;
+        }
+        // Grounding-inject rung (WS3): only when the route requires grounded AND
+        // this candidate lacks native grounding. Search failures are ordinary
+        // `network` failures — retried per budget, never silently ungrounded.
+        const nativeGrounded = flags.has("grounded_native");
+        injectedSources = null;
+        if (route.require.includes("grounded") && !nativeGrounded && deps.search) {
+            if (searchResponse === null) {
+                const query = route.groundingQuery !== undefined
+                    ? (0, template_1.renderTemplate)(route.groundingQuery, { variables: opts.input, capabilities: flags })
+                    : (0, grounding_1.capSearchQuery)(systemPrompt);
+                try {
+                    searchResponse = await deps.search.search(query);
+                    guard?.settle(searchResponse.costUsd);
+                    (0, dispatch_1.recordSearchCostRow)(deps.telemetry, route, effectiveTags, servedVariant, deps.search.id, searchResponse.costUsd);
+                }
+                catch (err) {
+                    const failure = {
+                        class: "network",
+                        message: `grounding search failed: ${err instanceof Error ? err.message : String(err)}`,
+                        fixHint: "check the search provider key/config (RigConfig.search)",
+                        cause: err,
+                    };
+                    recordAttempt({
+                        candidate,
+                        servedTier: route.policy.tier,
+                        tokensIn: 0,
+                        tokensOut: 0,
+                        tokensCached: 0,
+                        costUsd: 0,
+                        latencyMs: 0,
+                        failure,
+                    });
+                    lastFailure = failure;
+                    if (ledger.consume("network")) {
+                        await sleep(ledger.delayMs("network"));
+                        continue;
+                    }
+                    candidate = iter.next();
+                    continue;
+                }
+            }
+            systemPrompt += (0, grounding_1.searchInjectionBlock)(searchResponse.results, new Date().toISOString());
+            injectedSources = searchResponse.results;
+        }
+        // json_mode rung (route-level) or a candidate without native strict
+        // enforcement: coach the schema into the prompt (ajv still arbitrates).
+        const useJsonModeCoaching = route.outputSchema !== null &&
+            (route.policy.json === "json_mode" || !flags.has("structured_native"));
+        if (useJsonModeCoaching) {
+            systemPrompt += jsonModeCoaching(route.outputSchema);
+        }
+        // Envelope precheck BEFORE dispatch — upper-bound estimate from the
+        // pricing snapshot (prompt-length input + full output budget).
+        if (guard !== null) {
+            // A1: an unpriced model must never precheck at $0 (fail closed).
+            const breach = guard.precheck((0, cost_1.dispatchEstimateUsd)(candidate.provider, candidate.model, systemPrompt.length + USER_DIRECTIVE.length, unpricedRatePerTok));
+            if (breach !== null) {
+                failRun(candidate, breach, 0);
+            }
+        }
+        // CE-1 (spec §2.2, run/cache-handle.ts): `suppressed` drops the customer handle after a cache_invalid.
+        const candidateKey = `${candidate.provider} ${candidate.model}`;
+        const suppressed = droppedCacheHandle.has(candidateKey);
+        // buildAdapterRequest carries the grounding hint + unified tools passthrough
+        // (spec §4.4); dispatchCandidate streams deltas when a sink is wired, else
+        // buffers via call() — the returned result is identical either way.
+        const request = (0, dispatch_1.buildAdapterRequest)({
+            route,
+            candidate,
+            systemPrompt,
+            userDirective: USER_DIRECTIVE,
+            nativeGrounded,
+            opts,
+            suppressCustomerCache: suppressed,
+        });
+        const started = Date.now();
+        const result = await (0, dispatch_1.dispatchCandidate)(adapter, request, deps.onStreamDelta);
+        const latencyMs = Date.now() - started;
+        if (result.ok) {
+            const { costUsd, envelopeChargeUsd, pricingMissing } = (0, cost_1.attemptCost)(candidate.provider, candidate.model, result.usage, unpricedRatePerTok);
+            guard?.settle(envelopeChargeUsd);
+            // Tool-call turn (spec §4.4): the model asked to call a tool — NOT a
+            // schema-validated JSON turn. Record it and surface the normalized calls.
+            if (result.toolCalls !== undefined && result.toolCalls.length > 0) {
+                return (0, dispatch_1.emitToolCallResult)(recordAttempt, {
+                    route,
+                    candidate,
+                    result,
+                    costUsd,
+                    latencyMs,
+                    attemptsByClass: ledger.snapshot(),
+                    servedVariant,
+                    pricingMissing,
+                });
+            }
+            const outcome = (0, validate_1.validateOutput)(route, result.text);
+            if (outcome.valid) {
+                const inferenceId = recordAttempt({
+                    candidate,
+                    servedTier: result.usage.servedTier,
+                    tokensIn: result.usage.tokensIn,
+                    tokensOut: result.usage.tokensOut,
+                    tokensCached: result.usage.tokensCached,
+                    tokensCacheWrite: result.usage.tokensCacheWrite ?? 0,
+                    tokensCacheWrite1h: result.usage.tokensCacheWrite1h ?? 0,
+                    costUsd,
+                    latencyMs,
+                    ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+                    failure: null,
+                    pricingMissing,
+                });
+                captureAttempt(inferenceId, result.text);
+                const meta = {
+                    inferenceId,
+                    route: route.route,
+                    routeVersion: route.version,
+                    provider: candidate.provider,
+                    model: candidate.model,
+                    requestedTier: route.policy.tier,
+                    servedTier: result.usage.servedTier,
+                    tokensIn: result.usage.tokensIn,
+                    tokensOut: result.usage.tokensOut,
+                    tokensCached: result.usage.tokensCached,
+                    costEstimateUsd: costUsd,
+                    latencyMs,
+                    validated: true,
+                    attemptsByClass: ledger.snapshot(),
+                    servedVariant,
+                    repairedBy: null,
+                    ...(injectedSources !== null
+                        ? { citations: (0, grounding_1.extractCitations)(result.text, injectedSources) }
+                        : {}),
+                };
+                return { output: outcome.parsed, meta };
+            }
+            // Schema-invalid output — a real (billed) attempt that failed.
+            const failure = {
+                class: "content_invalid",
+                message: `output failed schema validation: ${outcome.errors.join("; ")}`,
+                provider: candidate.provider,
+                model: candidate.model,
+            };
+            const invalidId = recordAttempt({
+                candidate,
+                servedTier: result.usage.servedTier,
+                tokensIn: result.usage.tokensIn,
+                tokensOut: result.usage.tokensOut,
+                tokensCached: result.usage.tokensCached,
+                tokensCacheWrite: result.usage.tokensCacheWrite ?? 0,
+                tokensCacheWrite1h: result.usage.tokensCacheWrite1h ?? 0,
+                costUsd,
+                latencyMs,
+                ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+                failure,
+                pricingMissing,
+            });
+            captureAttempt(invalidId, result.text);
+            lastFailure = failure;
+            // Repair rung (WS2): consumed BEFORE any content_invalid retry, from
+            // its own budget. Chain: same-model error feedback, then the
+            // designated repair model on the newest invalid output.
+            if (route.outputSchema !== null) {
+                let latestText = result.text;
+                let latestErrors = outcome.errors;
+                let repairStep = repairLedger.next();
+                while (repairStep !== null) {
+                    const repairOutcome = await attemptRepair(repairStep, candidate, systemPrompt, latestText, latestErrors);
+                    if (repairOutcome?.done !== undefined) {
+                        return repairOutcome.done;
+                    }
+                    if (repairOutcome?.invalid !== undefined) {
+                        latestText = repairOutcome.invalid.text;
+                        latestErrors = repairOutcome.invalid.errors;
+                    }
+                    repairStep = repairLedger.next();
+                }
+            }
+            if (ledger.consume("content_invalid")) {
+                continue; // retry the SAME candidate until the class budget is spent
+            }
+            candidate = iter.next(); // then advance within the declared set
+            continue;
+        }
+        // Adapter-level typed failure. F1: refusals/truncations that BILLED
+        // tokens carry usage — settle the envelope and record the real spend.
+        const failure = result.failure;
+        let failureCostUsd = 0;
+        let failurePricingMissing = false;
+        if (result.usage !== undefined) {
+            const settled = (0, cost_1.attemptCost)(candidate.provider, candidate.model, result.usage, unpricedRatePerTok);
+            failureCostUsd = settled.costUsd;
+            failurePricingMissing = settled.pricingMissing;
+            guard?.settle(settled.envelopeChargeUsd);
+        }
+        recordAttempt({
+            candidate,
+            servedTier: result.usage?.servedTier ?? route.policy.tier,
+            tokensIn: result.usage?.tokensIn ?? 0,
+            tokensOut: result.usage?.tokensOut ?? 0,
+            tokensCached: result.usage?.tokensCached ?? 0,
+            tokensCacheWrite: result.usage?.tokensCacheWrite ?? 0,
+            tokensCacheWrite1h: result.usage?.tokensCacheWrite1h ?? 0,
+            costUsd: failureCostUsd,
+            latencyMs,
+            ...(result.usage?.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+            failure,
+            pricingMissing: failurePricingMissing,
+        });
+        if (failures_1.TERMINAL_CLASSES.has(failure.class)) {
+            throw new failures_1.RigFailureError(failure);
+        }
+        lastFailure = failure;
+        // CE-1 retry-drop (spec §2.2): a cache_invalid that carried the handle drops it on retry.
+        const carriedHandle = failure.class === "cache_invalid" && !suppressed && opts.cache?.provider === candidate.provider;
+        if (carriedHandle)
+            droppedCacheHandle.add(candidateKey);
+        if (ledger.consume(failure.class)) {
+            await sleep(ledger.delayMs(failure.class));
+            continue; // retry the SAME candidate
+        }
+        candidate = iter.next(); // class budget spent — advance candidate
+    }
+    throw new failures_1.RigFailureError(lastFailure ?? {
+        class: "network",
+        message: `route "${route.route}": all candidates exhausted with no recorded failure`,
+    });
+}

package/dist/run/stream.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Streaming surface on the run path — G-1/G-5 Phase A (http-gateway spec §4.3).
+ *
+ * `runStream` wraps the existing `run()` loop with a delta side-channel: as the
+ * serving adapter streams, raw text tokens are emitted as `delta` events; when
+ * the run resolves, its terminal `RunResult` is emitted as the `final` event.
+ * Crucially the SAME pipeline (resolve → dispatch → validate → repair →
+ * telemetry) drives both streamed and buffered runs — streaming is purely a
+ * side-channel, so validation, repair, ZDR (G-3) and routing controls (G-2)
+ * all apply unchanged. `rig.run()` is left exactly as it was.
+ *
+ * The structured-route caveat (spec §4.3): streamed `delta` bytes are the
+ * model's RAW pre-validation output. The `final` event is authoritative — it
+ * carries the schema-validated (and, if repair fired, repaired) object plus
+ * `meta.validated` / `meta.repairedBy`. Callers wanting validated-only output
+ * pass `buffered: true` (no deltas, just the final) — the SDK mirror of the
+ * endpoint's `x-modelrig-stream: buffered`.
+ *
+ * ModelRig never executes a tool (spec §4.4); a tool-call turn surfaces on the
+ * final event's `meta.toolCalls` exactly as it does through `run()`.
+ */
+import type { RunDeps } from "./run";
+import type { RunOptions, RunResult } from "../types/route";
+export type RunStreamEvent = {
+    readonly type: "delta";
+    readonly text: string;
+} | {
+    readonly type: "final";
+    readonly result: RunResult;
+};
+export interface RunStreamOptions extends RunOptions {
+    /** Buffered mode (spec §4.3): suppress token deltas and emit only the
+     * terminal (validated) result. Default false = stream-then-final. */
+    readonly buffered?: boolean;
+}
+export interface RunStreamHandle {
+    /** Async-iterable of `delta` events then a single `final`. Re-throws the
+     * run's error if it failed (after any deltas already emitted). */
+    readonly events: AsyncIterable<RunStreamEvent>;
+    /** The terminal RunResult, or a rejection with the run's typed failure.
+     * Resolves with the same object carried by the `final` event. */
+    readonly result: Promise<RunResult>;
+}
+/**
+ * Drive a route with token streaming. Returns an async-iterable of events plus
+ * a `result` promise for callers that only want the terminal value.
+ */
+export declare function runStream(deps: RunDeps, routeName: string, opts: RunStreamOptions): RunStreamHandle;
+//# sourceMappingURL=stream.d.ts.map

package/dist/run/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/run/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE5D,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD;yEACqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B;sEACkE;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C;qEACiE;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CA6DjB"}