modelrig 0.0.1 → 0.1.0

package/dist/routes/serveability.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Load-time route serveability — Phase 4 resilience (architect-flagged
+ * change to the Phase-1 fail-fast guard).
+ *
+ * A declared candidate whose provider has no registered adapter (no API key
+ * in THIS environment) is INERT, not fatal: the gateway must not crash at
+ * boot because a bake-off challenger arm lacks a key here. This is the
+ * "safe but inert" behaviour the route-v3 commit assumed — true on the
+ * InferWealth cutover wrapper (it catches + falls back to legacy), but the
+ * standalone modelrig-server builds the rig eagerly at boot with no catch,
+ * so a keyless arm downed staging.
+ *
+ * Rule: warn per inert candidate and keep serving on the keyed ones; a route
+ * with ZERO serveable candidates is still a hard error (genuinely dead). The
+ * candidate-set UPPER bound is untouched — resolveCandidates still only
+ * yields declared candidates, and the run loop skips inert ones at dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inertCandidateFailure = inertCandidateFailure;
+exports.serveabilityWarnings = serveabilityWarnings;
+exports.checkServeability = checkServeability;
+const config_1 = require("../config");
+const loader_1 = require("./loader");
+function envVarFor(provider) {
+    return config_1.PROVIDER_KEY_ENV[provider] ?? `${provider.toUpperCase()}_API_KEY`;
+}
+/** Typed failure for an inert (keyless) candidate the run loop skips at
+ * dispatch — non-terminal config_auth so the loop advances to the next
+ * declared candidate; surfaced as the run's error only if EVERY candidate
+ * is inert. */
+function inertCandidateFailure(candidate, route) {
+    return {
+        class: "config_auth",
+        message: `provider "${candidate.provider}" has no adapter (declared by route "${route}") — ` +
+            `its API key is not configured; skipping this candidate`,
+        provider: candidate.provider,
+        model: candidate.model,
+        fixHint: `configure the ${candidate.provider} API key to enable this candidate`,
+    };
+}
+function serveabilityWarnings(bundles, hasAdapter) {
+    const warnings = [];
+    for (const bundle of bundles) {
+        const serveable = bundle.candidates.filter((c) => hasAdapter(c.provider));
+        if (serveable.length === 0) {
+            const providers = [...new Set(bundle.candidates.map((c) => c.provider))];
+            throw new loader_1.RouteConfigError(`route "${bundle.route}" has no serveable candidate — none of its declared providers ` +
+                `[${providers.join(", ")}] has an API key configured ` +
+                `(set ${providers.map(envVarFor).join(" or ")})`);
+        }
+        const inert = bundle.candidates.filter((c) => !hasAdapter(c.provider));
+        if (inert.length === 0)
+            continue;
+        const missingProviders = [...new Set(inert.map((c) => c.provider))];
+        warnings.push({
+            route: bundle.route,
+            inert,
+            missingProviders,
+            serveableCount: serveable.length,
+            message: `route "${bundle.route}": ${inert.length} candidate(s) inert (no API key) — ` +
+                `${inert.map((c) => `${c.provider}/${c.model}`).join(", ")}; serving on ` +
+                `${serveable.length} keyed candidate(s) until their keys are configured.`,
+            fixHint: `set ${missingProviders.map(envVarFor).join(", ")} to enable these candidates`,
+        });
+    }
+    return warnings;
+}
+/** String façade over {@link serveabilityWarnings} — one traversal, one
+ * source of wording. Throws identically on a zero-serveable route. */
+function checkServeability(bundles, hasAdapter) {
+    return serveabilityWarnings(bundles, hasAdapter).map((w) => w.message);
+}

package/dist/routes/template.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Template renderer — spec §3, plan §4.
+ * Supports {{var}} substitution and capability-conditional blocks:
+ *   {{#if capability.grounded_native}}...{{/if}}
+ *   {{#unless capability.structured_native}}...{{/unless}}
+ * Deliberately hand-rolled and tiny — NO external template engine (jinja-class
+ * engines are a documented CVE surface; see litellm-vendoring-strategy.md §3).
+ */
+import type { CapabilityFlag } from "../types/provider";
+export interface RenderContext {
+    readonly variables: Record<string, unknown>;
+    readonly capabilities: ReadonlySet<CapabilityFlag>;
+}
+export declare function renderTemplate(template: string, ctx: RenderContext): string;
+/** Distinct {{var}} names referenced anywhere in the template (loader
+ * validation: every reference must be a declared variable). */
+export declare function scanTemplateVariables(template: string): readonly string[];
+//# sourceMappingURL=template.d.ts.map

package/dist/routes/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/routes/template.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;CACpD;AAuFD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED;+DAC+D;AAC/D,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAIzE"}

package/dist/routes/template.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Template renderer — spec §3, plan §4.
+ * Supports {{var}} substitution and capability-conditional blocks:
+ *   {{#if capability.grounded_native}}...{{/if}}
+ *   {{#unless capability.structured_native}}...{{/unless}}
+ * Deliberately hand-rolled and tiny — NO external template engine (jinja-class
+ * engines are a documented CVE surface; see litellm-vendoring-strategy.md §3).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = renderTemplate;
+exports.scanTemplateVariables = scanTemplateVariables;
+const provider_1 = require("../types/provider");
+const CAPABILITY_FLAGS = new Set(provider_1.ALL_CAPABILITY_FLAGS);
+const OPEN_TAG = /\{\{#(if|unless)\s+capability\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const CLOSE_TAG = /\{\{\/(if|unless)\}\}/g;
+const VAR_TAG = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+function scanTags(template) {
+    const tags = [];
+    for (const m of template.matchAll(OPEN_TAG)) {
+        tags.push({
+            kind: "open",
+            block: m[1],
+            flag: m[2],
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+    }
+    for (const m of template.matchAll(CLOSE_TAG)) {
+        tags.push({ kind: "close", block: m[1], start: m.index, end: m.index + m[0].length });
+    }
+    return tags.sort((a, b) => a.start - b.start);
+}
+/** Pass 1: resolve conditional blocks (flat only — nesting is rejected). */
+function resolveConditionals(template, capabilities) {
+    const tags = scanTags(template);
+    let out = "";
+    let cursor = 0;
+    let open = null;
+    for (const tag of tags) {
+        if (tag.kind === "open") {
+            if (open) {
+                throw new Error(`template error: nested {{#${tag.block}}} block at index ${tag.start} — nesting is not supported in Phase 1`);
+            }
+            if (tag.flag === undefined || !CAPABILITY_FLAGS.has(tag.flag)) {
+                throw new Error(`template error: unknown capability flag "${tag.flag ?? ""}" at index ${tag.start}`);
+            }
+            out += template.slice(cursor, tag.start);
+            open = tag;
+            cursor = tag.end;
+        }
+        else {
+            if (!open) {
+                throw new Error(`template error: unmatched {{/${tag.block}}} at index ${tag.start}`);
+            }
+            if (open.block !== tag.block) {
+                throw new Error(`template error: {{#${open.block}}} at index ${open.start} closed by {{/${tag.block}}} at index ${tag.start}`);
+            }
+            const present = capabilities.has(open.flag);
+            const keep = open.block === "if" ? present : !present;
+            if (keep)
+                out += template.slice(open.end, tag.start);
+            open = null;
+            cursor = tag.end;
+        }
+    }
+    if (open) {
+        throw new Error(`template error: unclosed {{#${open.block}}} block at index ${open.start}`);
+    }
+    return out + template.slice(cursor);
+}
+/** Pass 2: substitute {{var}} from ctx.variables; missing variables throw. */
+function substituteVariables(template, variables) {
+    return template.replace(VAR_TAG, (_match, name) => {
+        if (!(name in variables)) {
+            throw new Error(`template error: missing variable "${name}"`);
+        }
+        const value = variables[name];
+        if (typeof value === "string")
+            return value;
+        return JSON.stringify(value);
+    });
+}
+function renderTemplate(template, ctx) {
+    return substituteVariables(resolveConditionals(template, ctx.capabilities), ctx.variables);
+}
+/** Distinct {{var}} names referenced anywhere in the template (loader
+ * validation: every reference must be a declared variable). */
+function scanTemplateVariables(template) {
+    const names = new Set();
+    for (const m of template.matchAll(VAR_TAG))
+        names.add(m[1]);
+    return [...names];
+}

package/dist/run/cost.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Attempt cost accounting — extracted from run.ts (addendum A1 pushed it
+ * past the 700-LOC cap). One rule, applied at every dispatch/settlement
+ * site: a model with no pricing entry NEVER costs $0 against an active
+ * envelope — the envelope is charged a conservative per-token rate instead,
+ * while telemetry keeps the honest $0 with `pricing_missing` flagged.
+ */
+import type { AdapterUsage, ProviderId } from "../types/provider";
+export declare const ESTIMATE_CHARS_PER_TOKEN = 4;
+export declare const ESTIMATE_MAX_OUTPUT_TOKENS = 64000;
+/** Addendum A1 conservative default — above the priciest frontier output
+ * rate, so an unpriced model can only OVER-charge an envelope, never ride
+ * free. Override via MODELRIG_UNPRICED_RATE_USD_PER_MTOK / RigConfig. */
+export declare const DEFAULT_UNPRICED_RATE_USD_PER_MTOK = 100;
+export interface AttemptCost {
+    /** What telemetry records — honest $0 when pricing is missing. */
+    readonly costUsd: number;
+    /** What an active envelope is charged — conservative when unpriced. */
+    readonly envelopeChargeUsd: number;
+    readonly pricingMissing: boolean;
+}
+export declare function attemptCost(provider: ProviderId, model: string, usage: AdapterUsage, unpricedRatePerTok: number): AttemptCost;
+/** Pre-dispatch upper-bound estimate for the envelope precheck: prompt
+ * length + the full output bound, at real pricing or the conservative rate. */
+export declare function dispatchEstimateUsd(provider: ProviderId, model: string, promptChars: number, unpricedRatePerTok: number): number;
+//# sourceMappingURL=cost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/run/cost.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;yEAEyE;AACzE,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,YAAY,EACnB,kBAAkB,EAAE,MAAM,GACzB,WAAW,CAWb;AAED;+EAC+E;AAC/E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAOR"}

package/dist/run/cost.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Attempt cost accounting — extracted from run.ts (addendum A1 pushed it
+ * past the 700-LOC cap). One rule, applied at every dispatch/settlement
+ * site: a model with no pricing entry NEVER costs $0 against an active
+ * envelope — the envelope is charged a conservative per-token rate instead,
+ * while telemetry keeps the honest $0 with `pricing_missing` flagged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_UNPRICED_RATE_USD_PER_MTOK = exports.ESTIMATE_MAX_OUTPUT_TOKENS = exports.ESTIMATE_CHARS_PER_TOKEN = void 0;
+exports.attemptCost = attemptCost;
+exports.dispatchEstimateUsd = dispatchEstimateUsd;
+const pricing_1 = require("../registry/pricing");
+exports.ESTIMATE_CHARS_PER_TOKEN = 4;
+exports.ESTIMATE_MAX_OUTPUT_TOKENS = 64000;
+/** Addendum A1 conservative default — above the priciest frontier output
+ * rate, so an unpriced model can only OVER-charge an envelope, never ride
+ * free. Override via MODELRIG_UNPRICED_RATE_USD_PER_MTOK / RigConfig. */
+exports.DEFAULT_UNPRICED_RATE_USD_PER_MTOK = 100;
+function attemptCost(provider, model, usage, unpricedRatePerTok) {
+    const pricing = (0, pricing_1.getPricing)(provider, model);
+    if (pricing === null) {
+        return {
+            costUsd: 0,
+            envelopeChargeUsd: (usage.tokensIn + usage.tokensOut) * unpricedRatePerTok,
+            pricingMissing: true,
+        };
+    }
+    const costUsd = (0, pricing_1.estimateCostUsd)(pricing, usage.tokensIn, usage.tokensOut, usage.tokensCached);
+    return { costUsd, envelopeChargeUsd: costUsd, pricingMissing: false };
+}
+/** Pre-dispatch upper-bound estimate for the envelope precheck: prompt
+ * length + the full output bound, at real pricing or the conservative rate. */
+function dispatchEstimateUsd(provider, model, promptChars, unpricedRatePerTok) {
+    const promptTokens = Math.ceil(promptChars / exports.ESTIMATE_CHARS_PER_TOKEN);
+    const pricing = (0, pricing_1.getPricing)(provider, model);
+    if (pricing === null) {
+        return (promptTokens + exports.ESTIMATE_MAX_OUTPUT_TOKENS) * unpricedRatePerTok;
+    }
+    return (0, pricing_1.estimateCostUsd)(pricing, promptTokens, exports.ESTIMATE_MAX_OUTPUT_TOKENS, 0);
+}

package/dist/run/envelope.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Per-run budget envelopes v0 — spec §2. Hard stop only in Phase 1
+ * (degrade-before-die routes arrive in Phase 3). Backed by the telemetry
+ * store's envelopes table so envelopes survive process restarts within a run.
+ */
+import type { TelemetryStore } from "../types/telemetry";
+import type { RigFailure } from "../types/failures";
+export interface EnvelopeGuard {
+    /**
+     * Check + reserve before a dispatch. Returns null when spend may proceed,
+     * or a budget_exhausted RigFailure when the envelope is breached.
+     */
+    precheck(estimatedNextCallUsd: number): RigFailure | null;
+    /** Record actual cost after a dispatch completes. */
+    settle(actualUsd: number): void;
+}
+/** Default per-envelope budget when the caller doesn't specify one (small on
+ * purpose — a hard stop that surprises is safer than silent unbounded spend). */
+export declare const DEFAULT_ENVELOPE_BUDGET_USD = 25;
+export declare function createEnvelopeGuard(store: TelemetryStore, envelopeKey: string, budgetUsd?: number): EnvelopeGuard;
+//# sourceMappingURL=envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/run/envelope.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC1D,qDAAqD;IACrD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;iFACiF;AACjF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,aAAa,CAoCf"}

package/dist/run/envelope.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Per-run budget envelopes v0 — spec §2. Hard stop only in Phase 1
+ * (degrade-before-die routes arrive in Phase 3). Backed by the telemetry
+ * store's envelopes table so envelopes survive process restarts within a run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ENVELOPE_BUDGET_USD = void 0;
+exports.createEnvelopeGuard = createEnvelopeGuard;
+/** Default per-envelope budget when the caller doesn't specify one (small on
+ * purpose — a hard stop that surprises is safer than silent unbounded spend). */
+exports.DEFAULT_ENVELOPE_BUDGET_USD = 25;
+function createEnvelopeGuard(store, envelopeKey, budgetUsd) {
+    // Open-or-get: the first opener's budget wins; a pre-existing row (earlier
+    // step of the same run, or an operator-seeded envelope) is never resized.
+    store.openEnvelope(envelopeKey, budgetUsd ?? exports.DEFAULT_ENVELOPE_BUDGET_USD);
+    function exhaustedFailure(row) {
+        return {
+            class: "budget_exhausted",
+            message: `envelope "${envelopeKey}" exhausted: spent $${row.spentUsd.toFixed(4)} ` +
+                `of $${row.budgetUsd} budget`,
+            fixHint: "raise the envelope budget or investigate runaway retries for this run",
+        };
+    }
+    return {
+        precheck(estimatedNextCallUsd) {
+            const row = store.getEnvelope(envelopeKey);
+            if (row === null) {
+                // openEnvelope above guarantees a row; a vanished row means the store
+                // was externally mutated — fail closed rather than spend blind.
+                return {
+                    class: "budget_exhausted",
+                    message: `envelope "${envelopeKey}" row missing at precheck — failing closed`,
+                };
+            }
+            if (row.status === "exhausted" || row.spentUsd + estimatedNextCallUsd > row.budgetUsd) {
+                return exhaustedFailure(row);
+            }
+            return null;
+        },
+        settle(actualUsd) {
+            store.accrue(envelopeKey, actualUsd);
+        },
+    };
+}

package/dist/run/grounding.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Grounding-inject rung — Phase 3 spec WS3, plan §4. For candidates WITHOUT
+ * grounded_native on a `require: grounded` route: pre-dispatch search via a
+ * SearchProvider → results injected into the rendered system prompt →
+ * citations normalized to url_citation annotations in RunMeta. Search costs
+ * accrue to the envelope and telemetry.
+ *
+ * The Tavily-style provider ports the PATTERN from InferWealth's production
+ * websearch provider (query-length cap, basic/advanced depth, result shape)
+ * — logic only, no cross-package imports; key arrives via config.
+ */
+export interface SearchResultItem {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+    readonly publishedDate?: string;
+}
+export interface SearchResponse {
+    readonly results: readonly SearchResultItem[];
+    /** What this search cost — accrued to the envelope + telemetry. */
+    readonly costUsd: number;
+}
+export interface SearchProvider {
+    readonly id: string;
+    search(query: string, opts?: {
+        readonly maxResults?: number;
+    }): Promise<SearchResponse>;
+}
+/** Ported cap: the Tavily API hard-rejects queries over 400 chars. */
+export declare const SEARCH_QUERY_MAX_CHARS = 400;
+export declare function capSearchQuery(query: string): string;
+export interface TavilySearchConfig {
+    readonly apiKey: string;
+    /** Flat per-search cost (Tavily bills credits, not tokens) — default one
+     * basic-depth credit at the pay-as-you-go rate. */
+    readonly costPerSearchUsd?: number;
+    readonly searchDepth?: "basic" | "advanced";
+    readonly baseUrl?: string;
+    /** Injectable for tests; defaults to global fetch. */
+    readonly fetchFn?: typeof fetch;
+}
+export declare function createTavilySearchProvider(config: TavilySearchConfig): SearchProvider;
+/** The injected block — appended to the rendered system prompt, before json
+ * coaching. Sources are numbered so outputs can cite by URL. */
+export declare function searchInjectionBlock(results: readonly SearchResultItem[], retrievedAt: string): string;
+/** Normalized citation annotation (spec WS3) — RunMeta carries these. */
+export interface UrlCitation {
+    readonly type: "url_citation";
+    readonly url: string;
+    readonly title?: string;
+}
+/** Extract URLs cited in the model's output and normalize to url_citation
+ * annotations, enriching with titles from the injected sources. Deduped,
+ * trailing punctuation stripped (same normalization as the probe suite). */
+export declare function extractCitations(outputText: string, sources: readonly SearchResultItem[]): UrlCitation[];
+//# sourceMappingURL=grounding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/run/grounding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACzF;AAED,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;uDACmD;IACnD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAaD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,CAoCrF;AAED;gEACgE;AAChE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAYtG;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;4EAE4E;AAC5E,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,gBAAgB,EAAE,GACnC,WAAW,EAAE,CAYf"}

package/dist/run/grounding.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Grounding-inject rung — Phase 3 spec WS3, plan §4. For candidates WITHOUT
+ * grounded_native on a `require: grounded` route: pre-dispatch search via a
+ * SearchProvider → results injected into the rendered system prompt →
+ * citations normalized to url_citation annotations in RunMeta. Search costs
+ * accrue to the envelope and telemetry.
+ *
+ * The Tavily-style provider ports the PATTERN from InferWealth's production
+ * websearch provider (query-length cap, basic/advanced depth, result shape)
+ * — logic only, no cross-package imports; key arrives via config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEARCH_QUERY_MAX_CHARS = void 0;
+exports.capSearchQuery = capSearchQuery;
+exports.createTavilySearchProvider = createTavilySearchProvider;
+exports.searchInjectionBlock = searchInjectionBlock;
+exports.extractCitations = extractCitations;
+/** Ported cap: the Tavily API hard-rejects queries over 400 chars. */
+exports.SEARCH_QUERY_MAX_CHARS = 400;
+function capSearchQuery(query) {
+    return query.length <= exports.SEARCH_QUERY_MAX_CHARS ? query : query.slice(0, exports.SEARCH_QUERY_MAX_CHARS);
+}
+const TAVILY_BASE_URL = "https://api.tavily.com";
+const DEFAULT_COST_PER_SEARCH_USD = 0.008;
+const DEFAULT_MAX_RESULTS = 5;
+function createTavilySearchProvider(config) {
+    const fetchFn = config.fetchFn ?? fetch;
+    const base = (config.baseUrl ?? TAVILY_BASE_URL).replace(/\/$/, "");
+    const costUsd = config.costPerSearchUsd ?? DEFAULT_COST_PER_SEARCH_USD;
+    return {
+        id: "tavily",
+        async search(query, opts) {
+            const response = await fetchFn(`${base}/search`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    query: capSearchQuery(query),
+                    search_depth: config.searchDepth ?? "basic",
+                    max_results: opts?.maxResults ?? DEFAULT_MAX_RESULTS,
+                    include_answer: false,
+                }),
+            });
+            if (!response.ok) {
+                throw new Error(`tavily search → ${response.status} ${await response.text().catch(() => "")}`);
+            }
+            const body = (await response.json());
+            const results = (body.results ?? [])
+                .filter((r) => typeof r.url === "string" && r.url !== "")
+                .map((r) => ({
+                title: r.title ?? "",
+                url: r.url,
+                snippet: r.content ?? "",
+                ...(r.published_date !== undefined ? { publishedDate: r.published_date } : {}),
+            }));
+            return { results, costUsd };
+        },
+    };
+}
+/** The injected block — appended to the rendered system prompt, before json
+ * coaching. Sources are numbered so outputs can cite by URL. */
+function searchInjectionBlock(results, retrievedAt) {
+    const lines = results.map((r, i) => `${i + 1}. ${r.title || "(untitled)"} — ${r.url}` +
+        (r.publishedDate !== undefined ? ` (published ${r.publishedDate})` : "") +
+        (r.snippet !== "" ? `\n   ${r.snippet}` : ""));
+    return (`\n\n---\nWEB SEARCH RESULTS (retrieved ${retrievedAt}). Ground your answer in these ` +
+        "sources and cite the URLs of the sources you actually rely on:\n" +
+        lines.join("\n"));
+}
+const URL_PATTERN = /https?:\/\/[^\s"'<>)\]\\]+/g;
+/** Extract URLs cited in the model's output and normalize to url_citation
+ * annotations, enriching with titles from the injected sources. Deduped,
+ * trailing punctuation stripped (same normalization as the probe suite). */
+function extractCitations(outputText, sources) {
+    const raw = outputText.match(URL_PATTERN) ?? [];
+    const urls = [...new Set(raw.map((u) => u.replace(/[.,;:]+$/, "")))];
+    const titleByUrl = new Map(sources.map((s) => [s.url, s.title]));
+    return urls.map((url) => {
+        const title = titleByUrl.get(url);
+        return {
+            type: "url_citation",
+            url,
+            ...(title !== undefined && title !== "" ? { title } : {}),
+        };
+    });
+}

package/dist/run/repair.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Repair rung (ladder rung 4) — Phase 3 spec WS2, plan §4. Pure pieces only:
+ * the repair-attempt state machine and the two repair prompts. Dispatch,
+ * cost, and telemetry stay in run.ts (repair calls are ordinary attempts with
+ * `repaired_by` stamped).
+ *
+ * Budget model (plan §4): repair draws from its OWN budget (RepairPolicy.
+ * maxRepairs) — a policy key, NOT a failure class. It never consumes the
+ * content_invalid budget and vice versa (non-fungibility extends to repair).
+ */
+import type { RepairPolicy, CandidateSpec } from "../types/route";
+export type RepairStep = {
+    readonly kind: "same_model";
+} | {
+    readonly kind: "repair_model";
+    readonly model: CandidateSpec;
+};
+export interface RepairLedger {
+    /** The next repair step to take, or null when the budget is spent (or
+     * repair is not configured). Each call consumes one unit. */
+    next(): RepairStep | null;
+    /** Repair attempts consumed so far. */
+    used(): number;
+}
+/** Attempt 1 = same model with error feedback; attempt 2 = the designated
+ * repair model (only when configured — loader guarantees maxRepairs=2 has
+ * repairModel). */
+export declare function createRepairLedger(policy: RepairPolicy | undefined): RepairLedger;
+/** Appended to the ORIGINAL system prompt for the same-model repair retry:
+ * the model sees exactly what failed validation and why. */
+export declare function repairFeedbackBlock(errors: readonly string[]): string;
+/** Full system prompt for the designated repair model: it never sees the
+ * original task — only {invalid output, errors, schema}. Fixed by design
+ * (plan §4); the repair model's job is mechanical correction, not re-answering. */
+export declare function repairModelPrompt(invalidOutput: string, errors: readonly string[], schema: object): string;
+//# sourceMappingURL=repair.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../src/run/repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B;iEAC6D;IAC7D,IAAI,IAAI,UAAU,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,IAAI,IAAI,MAAM,CAAC;CAChB;AAED;;mBAEmB;AACnB,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,CAejF;AAED;4DAC4D;AAC5D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAUrE;AAED;;mFAEmF;AACnF,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,MAAM,GACb,MAAM,CAYR"}

package/dist/run/repair.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Repair rung (ladder rung 4) — Phase 3 spec WS2, plan §4. Pure pieces only:
+ * the repair-attempt state machine and the two repair prompts. Dispatch,
+ * cost, and telemetry stay in run.ts (repair calls are ordinary attempts with
+ * `repaired_by` stamped).
+ *
+ * Budget model (plan §4): repair draws from its OWN budget (RepairPolicy.
+ * maxRepairs) — a policy key, NOT a failure class. It never consumes the
+ * content_invalid budget and vice versa (non-fungibility extends to repair).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRepairLedger = createRepairLedger;
+exports.repairFeedbackBlock = repairFeedbackBlock;
+exports.repairModelPrompt = repairModelPrompt;
+/** Attempt 1 = same model with error feedback; attempt 2 = the designated
+ * repair model (only when configured — loader guarantees maxRepairs=2 has
+ * repairModel). */
+function createRepairLedger(policy) {
+    let used = 0;
+    return {
+        next() {
+            if (policy === undefined || used >= policy.maxRepairs)
+                return null;
+            used += 1;
+            if (used === 1)
+                return { kind: "same_model" };
+            return policy.repairModel !== undefined
+                ? { kind: "repair_model", model: policy.repairModel }
+                : null;
+        },
+        used() {
+            return used;
+        },
+    };
+}
+/** Appended to the ORIGINAL system prompt for the same-model repair retry:
+ * the model sees exactly what failed validation and why. */
+function repairFeedbackBlock(errors) {
+    return ("\n\n---\nREPAIR PASS: Your previous response FAILED JSON Schema validation with these " +
+        `errors:\n${errors.map((e) => `- ${e}`).join("\n")}\n` +
+        "Produce the COMPLETE corrected JSON object now. Fix every listed error, keep all fields " +
+        "that were already valid, and output ONLY the JSON object — no commentary, no fences. " +
+        "CHARACTER LIMITS ARE EXACT: if an error says a string has too many characters, rewrite " +
+        "that string DRASTICALLY shorter — aim near the midpoint of the schema's minLength and " +
+        "maxLength for that field; your length estimates run long, so when unsure, cut more.");
+}
+/** Full system prompt for the designated repair model: it never sees the
+ * original task — only {invalid output, errors, schema}. Fixed by design
+ * (plan §4); the repair model's job is mechanical correction, not re-answering. */
+function repairModelPrompt(invalidOutput, errors, schema) {
+    return ("You are a JSON repair specialist. You receive a JSON document that FAILED validation " +
+        "against a JSON Schema, plus the validation errors. Emit the corrected document.\n\n" +
+        "RULES: Output ONLY a single valid JSON object — no markdown fences, no commentary. " +
+        "Preserve every value that does not violate the schema; change ONLY what the errors " +
+        "require. Do not invent facts: where a required field is missing and its value cannot be " +
+        "derived from the invalid document, use the most conservative schema-valid completion.\n\n" +
+        `THE JSON SCHEMA:\n${JSON.stringify(schema)}\n\n` +
+        `THE VALIDATION ERRORS:\n${errors.map((e) => `- ${e}`).join("\n")}\n\n` +
+        `THE INVALID DOCUMENT:\n${invalidOutput}`);
+}

package/dist/run/resolve.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Candidate resolution — plan §4. THE ONLY constructor of CandidateRef in the
+ * codebase (the candidate-set invariant is enforced here structurally).
+ * Phase 1 selection: first candidate whose static capability flags satisfy
+ * route.require, ordered by prefer:[cost] via the pricing snapshot; on a
+ * retryable failure the run loop asks for the next candidate.
+ */
+import type { RouteBundle } from "../types/route";
+import type { CandidateRef, CapabilityFlag, ProviderId } from "../types/provider";
+/** Static capability stub — replaced by the probed registry in Phase 2. */
+export type CapabilityLookup = (provider: ProviderId, model: string) => ReadonlySet<CapabilityFlag>;
+export interface CandidateIterator {
+    /** Next eligible candidate, or null when the set is exhausted. */
+    next(): CandidateRef | null;
+}
+export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean): CandidateIterator;
+/**
+ * Mint a CandidateRef for a SPECIFIC declared candidate (the repair rung's
+ * designated repair model — loader-validated to be in the route's candidate
+ * list; re-checked here). Same brand site, same sanctioned-cast scope.
+ */
+export declare function resolveDeclaredCandidate(route: RouteBundle, spec: {
+    readonly provider: ProviderId;
+    readonly model: string;
+}): CandidateRef | null;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElF,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,KACV,WAAW,CAAC,cAAc,CAAC,CAAC;AAEjC,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,IAAI,YAAY,GAAG,IAAI,CAAC;CAC7B;AAuCD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,gBAAgB,EAC9B,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EACtE,eAAe,UAAQ,GACtB,iBAAiB,CA6BnB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9D,YAAY,GAAG,IAAI,CAMrB"}