modelrig 0.1.0 → 0.3.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/raw.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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).
+ *  - CE-2: the raw lane exposes three more provider knobs — `grounding`
+ *    (native web grounding), `serviceTier`, and `reasoning` (thinking effort).
+ *    Each is ADDITIVE: absent ⇒ byte-identical dispatch. A DECLARED directive is
+ *    never silently dropped — `grounding`/`reasoning` on a provider that cannot
+ *    honor it are rejected fail-closed PRE-DISPATCH (`assertRawKnobsSupported`),
+ *    with no meter, no provider call, and no telemetry row. v1 support set for
+ *    both = { gemini }. `serviceTier` forwards to every adapter's tier path and
+ *    `meta.requestedTier` now reports the DECLARED tier (an honesty fix — it
+ *    previously hardcoded `"standard"`).
+ */
+import type { AdapterRequest, CandidateRef, ProviderId, ReasoningParams, ServiceTier, 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;
+    };
+    /** CE-2 F1 — native provider grounding on the raw lane (spec §3 F1). Object
+     * form so `"inject"` can join later without reshaping; v1 accepts ONLY
+     * `"native"`, which maps to `AdapterRequest.grounding = true`. GEMINI-ONLY in
+     * v1: declared on any other provider throws `RigFailureError`
+     * `invariant_violation` pre-dispatch (`assertRawKnobsSupported`). Interplay
+     * with `cache.key`: no code needed here — the gemini adapter's `cachedContent`
+     * path excludes tools (the googleSearch tool is expected to be baked into the
+     * customer's cache resource at creation). */
+    readonly grounding?: {
+        readonly mode: "native";
+    };
+    /** CE-2 F2 — service tier on the raw lane (spec §3 F2). Forwarded to
+     * `AdapterRequest.requestedTier` (default `"standard"`). ModelRig does NOT
+     * perform flex→standard degrade on the raw lane — a capacity rejection
+     * surfaces CLASSIFIED (`capacity_shed`) and the customer's own ladder retries
+     * at `"standard"`. `meta.servedTier`/`meta.requestedTier` report the truth. */
+    readonly serviceTier?: ServiceTier;
+    /** CE-2 F3 — reasoning/thinking effort on the raw lane (spec §3 F3). Absent ⇒
+     * byte-identical (gemini keeps its hardcoded `"high"`). GEMINI-ONLY in v1 (and
+     * only on a thinking-capable model): declared on any other provider throws
+     * pre-dispatch (`assertRawKnobsSupported`); declared on a non-thinking gemini
+     * model is rejected classified by the adapter (`geminiReasoningUnsupported`). */
+    readonly reasoning?: ReasoningParams;
+}
+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;
+}
+/**
+ * CE-2 fail-closed guard (spec §3 F1/F3). A DECLARED directive is NEVER silently
+ * dropped: `grounding`/`reasoning` on a provider that cannot honor it — or a
+ * `grounding.mode` other than the v1-supported `"native"` — throws
+ * `RigFailureError` `invariant_violation` (the existing TERMINAL class; no new
+ * FailureClass member, spec §3 rationale) BEFORE any adapter is built, any
+ * provider call is made, or any telemetry row is written. Exported so the guard
+ * is unit-testable without a network. Idempotent and side-effect-free.
+ */
+export declare function assertRawKnobsSupported(input: RawRunInput): void;
+/** 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAYH,OAAO,KAAK,EACV,cAAc,EAGd,YAAY,EAGZ,UAAU,EACV,eAAe,EACf,WAAW,EACX,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;IACxE;;;;;;;iDAO6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;IACjD;;;;mFAI+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;qFAIiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;+EAE2E;IAC3E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAkDD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAiChE;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CAiC3F;AAsJD;wDACwD;AACxD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CASrF;AAcD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CA6ClF"}