modelrig 0.0.1 → 0.2.0

package/dist/run/dispatch.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Dispatch helpers extracted from run.ts (G-1/G-5 Phase A). The run loop is at
+ * its LOC cap, so the tool-passthrough and streaming seams live here — the same
+ * move G-2 made when it pulled applyRunRequirements/candidateFilterFromOptions
+ * into resolve.ts. Pure/near-pure: request shaping, the stream-vs-buffered
+ * dispatch fork, and the tool-call RunResult builder.
+ *
+ * Tool *execution* is never ours (spec §4.4); these helpers normalize the
+ * protocol and surface it — nothing here runs a tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordSearchCostRow = recordSearchCostRow;
+exports.buildAdapterRequest = buildAdapterRequest;
+exports.buildRepairAdapterRequest = buildRepairAdapterRequest;
+exports.dispatchCandidate = dispatchCandidate;
+exports.emitToolCallResult = emitToolCallResult;
+const node_crypto_1 = require("node:crypto");
+const cache_stamp_1 = require("./cache-stamp");
+const cache_handle_1 = require("./cache-handle");
+/** Record the grounding-inject search's own telemetry row (WS3): a $-only line
+ * under the synthetic "search" provider. Extracted from run.ts to keep it under
+ * the LOC cap; behaviour is byte-identical to the prior inline recorder. */
+function recordSearchCostRow(telemetry, route, effectiveTags, servedVariant, searchProviderId, costUsd) {
+    telemetry.record({
+        id: (0, node_crypto_1.randomUUID)(),
+        ts: new Date().toISOString(),
+        route: route.route,
+        routeVersion: route.version,
+        provider: "search",
+        model: searchProviderId,
+        requestedTier: "standard",
+        servedTier: "standard",
+        tokensIn: 0,
+        tokensOut: 0,
+        tokensCached: 0,
+        tokensCacheWrite: 0,
+        tokensCacheWrite1h: 0,
+        costEstimateUsd: costUsd,
+        latencyMs: 0,
+        ttfbMs: null,
+        failureClass: null,
+        attemptsJson: "{}",
+        tagsJson: JSON.stringify(effectiveTags),
+        fingerprintCell: route.fingerprintCell,
+        servedVariant,
+        repairedBy: null,
+        pricingMissing: false,
+        cacheKey: null,
+        prefixFingerprint: null,
+    });
+}
+/** Build the primary-attempt AdapterRequest — adds the grounding hint and the
+ * unified tools/toolChoice passthrough (spec §4.4). */
+function buildAdapterRequest(parts) {
+    const { route, candidate, systemPrompt, userDirective, nativeGrounded, opts } = parts;
+    // Request-path caching, two layers with a strict precedence (CE-1 spec §2.2):
+    //   (1) a CUSTOMER-supplied handle (RunOptions.cache) for the matching
+    //       provider WINS — it is a real provider-native resource the customer
+    //       owns. On gemini this is a `cachedContents/<id>`; the gemini adapter
+    //       then drops systemInstruction+tools by design (they are BAKED INTO the
+    //       cache at creation, and the API rejects setting both — gemini.ts:145).
+    //       That is correct API behavior, not a bug; the teaching doc explains it.
+    //       The WS-C gemini exclusion is untouched — it covers GENERATED keys only.
+    //   (2) else the WS-C `cache: auto` generated stamp — same pure gate the
+    //       recorder uses, so wire and telemetry never disagree (gemini excluded
+    //       here by that gate, not by prose).
+    // Absent RunOptions.cache, (1) is null and this is byte-identical to main.
+    const customerCache = (0, cache_handle_1.customerCacheHandle)(opts.cache, candidate, parts.suppressCustomerCache === true);
+    const cacheStamp = (0, cache_stamp_1.cacheStampForCandidate)(route, candidate);
+    const cacheDirective = customerCache ?? cacheStamp.request;
+    return {
+        candidate,
+        systemPrompt,
+        userPrompt: userDirective,
+        outputSchema: route.outputSchema,
+        requestedTier: route.policy.tier,
+        timeoutMs: route.policy.timeoutMs,
+        ...(cacheDirective !== null ? { cache: cacheDirective } : {}),
+        ...(route.require.includes("grounded") && nativeGrounded ? { grounding: true } : {}),
+        // CE-6: the route's declared sampling rides every primary attempt. Absent ⇒
+        // no `sampling` key ⇒ adapters keep their constants/omissions (byte-identical).
+        ...(route.policy.sampling !== undefined ? { sampling: route.policy.sampling } : {}),
+        ...(opts.tools !== undefined ? { tools: opts.tools } : {}),
+        ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
+    };
+}
+/** Build the repair-attempt AdapterRequest (no tools — repair re-asks for the
+ * structured object, never a tool call). */
+function buildRepairAdapterRequest(route, candidate, systemPrompt, repairDirective) {
+    // No cache stamp (WS-C): a repair re-asks with a DIFFERENT prompt (error
+    // feedback / repair-model framing), so it does not share the route's cacheable
+    // prefix identity. Sending the primary fingerprint as a routing key here would
+    // point dissimilar prompts at the same cache slot (openai explicitly warns
+    // against that) and would misfile the row in WS-B's warm-set. The recorder
+    // (record-attempt.ts) skips repair rows symmetrically.
+    return {
+        candidate,
+        systemPrompt,
+        userPrompt: repairDirective,
+        outputSchema: route.outputSchema,
+        requestedTier: route.policy.tier,
+        timeoutMs: route.policy.timeoutMs,
+        // CE-6: repair / JSON-extractor followups inherit the route's sampling — one
+        // knob per route, not per rung (spec §3). A repair re-ask at a different
+        // temperature than the primary would be a silent behaviour split.
+        ...(route.policy.sampling !== undefined ? { sampling: route.policy.sampling } : {}),
+    };
+}
+/**
+ * Dispatch a candidate. When a delta sink is supplied AND the adapter can
+ * stream, drain its stream — forwarding raw text deltas to the sink — and
+ * return the terminal `AdapterResult` (identical to what `call()` returns, so
+ * the run loop's cost/validation/telemetry logic is unchanged). Otherwise
+ * buffered `call()`.
+ */
+async function dispatchCandidate(adapter, req, onDelta) {
+    if (onDelta === undefined || adapter.stream === undefined) {
+        return adapter.call(req);
+    }
+    let final = null;
+    for await (const ev of adapter.stream(req)) {
+        if (ev.kind === "delta") {
+            if (ev.text !== "")
+                onDelta({ text: ev.text });
+        }
+        else {
+            final = ev.result;
+        }
+    }
+    return (final ?? {
+        ok: false,
+        failure: {
+            class: "network",
+            message: "adapter stream ended without a terminal result",
+            provider: req.candidate.provider,
+            model: req.candidate.model,
+        },
+    });
+}
+/**
+ * Record a tool-call turn and build its RunResult (spec §4.4). A tool call is
+ * NOT a schema-validated JSON turn: it records a normal (non-failure) telemetry
+ * row, then returns a result with `validated: false`, `output: null` (the caller
+ * reads `meta.toolCalls`, runs the tool, and continues the exchange), and the
+ * normalized calls surfaced on the meta. Recording goes through run.ts's own
+ * `recordAttempt` so the ledger/tenancy stamping is identical to every other row.
+ */
+function emitToolCallResult(record, parts) {
+    const { route, candidate, result, costUsd, latencyMs, attemptsByClass, servedVariant } = parts;
+    const inferenceId = record({
+        candidate,
+        servedTier: result.usage.servedTier,
+        tokensIn: result.usage.tokensIn,
+        tokensOut: result.usage.tokensOut,
+        tokensCached: result.usage.tokensCached,
+        ...(result.usage.tokensCacheWrite !== undefined
+            ? { tokensCacheWrite: result.usage.tokensCacheWrite }
+            : {}),
+        ...(result.usage.tokensCacheWrite1h !== undefined
+            ? { tokensCacheWrite1h: result.usage.tokensCacheWrite1h }
+            : {}),
+        costUsd,
+        latencyMs,
+        ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+        failure: null,
+        pricingMissing: parts.pricingMissing,
+    });
+    return {
+        output: null,
+        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: false,
+            attemptsByClass,
+            servedVariant,
+            repairedBy: null,
+            toolCalls: result.toolCalls,
+        },
+    };
+}

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/raw.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The RAW LANE — HTTP gateway Phase C (spec §4.2). A zero-margin BYOK
+ * passthrough: the caller names a `provider/model` and supplies (server-side,
+ * fail-closed) their own provider key; we dispatch DIRECTLY through the matching
+ * adapter and meter the call at the provider's list price. There is NO route, NO
+ * capability gate, NO validation, NO repair, NO envelope — and, by contract, NO
+ * ModelRig margin on the hop (the never-price-the-hop rule; the cost recorded is
+ * exactly `attemptCost`'s list price, which is what the verified lane records
+ * too). This module is the SDK half; the server half (BYOK resolution + the
+ * `key_ownership` tag) lives in `modelrig-server`.
+ *
+ * WHY THIS IS AN SDK PRIMITIVE, not server code: `AdapterRequest.candidate` is a
+ * branded `CandidateRef` mintable only in `run/resolve.ts`, and adapters are
+ * constructed with their key baked in — both live here. The server resolves the
+ * BYOK key fail-closed and calls `rig.runRaw`/`rig.runRawStream`; it never
+ * touches an adapter or the brand.
+ *
+ * KNOWN LIMITATIONS (flagged for the architect, not hidden):
+ *  - The adapter contract is single `systemPrompt` + `userPrompt`, not a
+ *    `messages[]` array, so a multi-turn transcript is flattened by the caller
+ *    (see `modelrig-server`'s `deriveRawPrompts`).
+ *  - CE-6: the raw lane now forwards `temperature`/`topP` (via
+ *    `AdapterRequest.sampling`) when the caller supplies them; absent, they are
+ *    still dropped and the dispatch is byte-identical to pre-CE-6. `max_tokens`
+ *    maps to `maxOutputTokens` (unchanged).
+ */
+import type { AdapterRequest, CandidateRef, ProviderId, ToolChoice, ToolDefinition } from "../types/provider";
+import type { RunResult, RunTags } from "../types/route";
+import type { RunStreamHandle } from "./stream";
+import type { TelemetryStore } from "../types/telemetry";
+/** Raw-lane request. `systemPrompt`/`userPrompt` are already flattened from the
+ * OpenAI `messages[]` by the caller; `tags` carries the caller's dimensions
+ * (the server stamps `key_ownership` here). `lane: "raw"` is stamped by this
+ * module and cannot be overridden. */
+export interface RawRunInput {
+    readonly provider: ProviderId;
+    readonly model: string;
+    /** The caller's BYOK provider secret, resolved fail-closed server-side. Held
+     * in memory for this one call, then dropped (never logged, never stored). */
+    readonly apiKey: string;
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+    readonly tags?: RunTags;
+    readonly maxOutputTokens?: number;
+    /** CE-6 sampling on the raw lane (spec §2). `temperature`/`topP` are the raw
+     * lane's exposure of the same knobs `RoutePolicy.sampling` gives the routed
+     * lane; `maxOutputTokens` above already existed. Absent ⇒ byte-identical raw
+     * dispatch (the params were previously dropped, per the header note). */
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly timeoutMs?: number;
+    readonly tools?: readonly ToolDefinition[];
+    readonly toolChoice?: ToolChoice;
+    /** CE-1 customer cache-handle pass-through on the Lane-B seam (spec §1.3
+     * success metric: "…passes its existing cachedContent handle through
+     * rig.run/runRaw"). The raw lane has exactly ONE provider (`provider` above),
+     * so the handle is unconditionally for it — no provider matching. Forwarded
+     * verbatim to `AdapterRequest.cache`; ModelRig never manages the resource. The
+     * stamped row carries the customer key with a null `prefix_fingerprint` (the
+     * raw lane runs no WS-C stamping), so provenance reads `customer` by the
+     * derivation rule. */
+    readonly cache?: {
+        readonly key: string;
+        readonly ttlSeconds?: number;
+    };
+}
+export interface RawRunDeps {
+    readonly telemetry: TelemetryStore;
+    /** Mirrors RunDeps: the conservative per-MTok rate for an unpriced model.
+     * Used only to keep `attemptCost` honest — the raw lane has no envelope, so
+     * it never charges the unpriced fallback; a missing price records `$0`. */
+    readonly unpricedRateUsdPerMTok?: number;
+}
+/** Pure raw-lane request shaping — exported for unit tests (no network). */
+export declare function buildRawRequest(candidate: CandidateRef, input: RawRunInput): AdapterRequest;
+/** Buffered raw dispatch (spec §4.2). Records telemetry, returns the RunResult,
+ * or throws `RigFailureError` on an adapter failure. */
+export declare function runRaw(deps: RawRunDeps, input: RawRunInput): Promise<RunResult>;
+/**
+ * Streaming raw dispatch (spec §4.3, "raw lane: true streaming, deltas passed
+ * through"). Drains the adapter's own stream when it has one, forwarding raw
+ * text deltas, and emits a single terminal `final` RunResult; adapters without
+ * `stream` (anthropic/gemini) fall back to a buffered `call()` with no deltas.
+ * There is NO terminal-validation event — that is a structured-route concept;
+ * the raw lane has no schema and the streamed bytes ARE the answer.
+ */
+export declare function runRawStream(deps: RawRunDeps, input: RawRunInput): RunStreamHandle;
+//# sourceMappingURL=raw.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../../src/run/raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAYH,OAAO,KAAK,EACV,cAAc,EAGd,YAAY,EAGZ,UAAU,EACV,UAAU,EACV,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAW,SAAS,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;sCAGsC;AACtC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;iFAC6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;6EAGyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;;;0BAOsB;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;+EAE2E;IAC3E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AA0CD,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CAyB3F;AA+ID;wDACwD;AACxD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAMrF;AAcD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CAyClF"}