@metrxbot/sdk 0.2.0 → 0.2.2

package/dist/routing-policy-cache.js

@@ -0,0 +1,96 @@
+/**
+ * Policy cache for the SDK cascade router (spec §5.6).
+ *
+ * - One fetch caches the whole org's policy set (GET /api/v1/routing/policies).
+ * - TTL 5 min (matches the server's max-age) with ETag revalidation.
+ * - Stale tolerance ≤ 60 min: a kill-switch flip must propagate; past the
+ *   bound the cache reports "unknown" and every caller falls back to
+ *   pass-through (seam F2).
+ * - Lazy + non-blocking: the first call triggers a background load and
+ *   returns "unknown" — cold start is pass-through, never a blocked request
+ *   (seam F1).
+ *
+ * NEVER throws. All fetch failures degrade to "unknown" → pass-through.
+ */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_STALE_MAX_MS = 60 * 60 * 1000;
+export class PolicyCache {
+    byKey = new Map();
+    etag = null;
+    loaded = false;
+    loadedAt = 0;
+    loading = null;
+    fetcher;
+    ttlMs;
+    staleMaxMs;
+    now;
+    constructor(opts) {
+        this.fetcher = opts.fetcher;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.staleMaxMs = opts.staleMaxMs ?? DEFAULT_STALE_MAX_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Non-blocking lookup.
+     * - `undefined` → policy state UNKNOWN (never loaded, or stale past the
+     *   bound) — caller must pass through.
+     * - `null` → the org's policies ARE loaded and this agent has no row —
+     *   pass-through by design (no row = not allow-listed).
+     * - a policy row otherwise.
+     */
+    get(agentKey) {
+        if (!this.loaded) {
+            // Cold: kick off the first load, serve pass-through now (F1).
+            this.refresh();
+            return undefined;
+        }
+        const age = this.now() - this.loadedAt;
+        if (age > this.staleMaxMs) {
+            // Too stale to trust — a kill-switch flip may not have propagated (F2).
+            this.refresh();
+            return undefined;
+        }
+        if (age > this.ttlMs) {
+            // Stale-but-tolerable: serve, refresh in the background.
+            this.refresh();
+        }
+        return this.byKey.get(normalizeAgentKey(agentKey)) ?? null;
+    }
+    /** Await any in-flight load — for tests and graceful shutdown. */
+    async settle() {
+        if (this.loading)
+            await this.loading.catch(() => undefined);
+    }
+    refresh() {
+        if (this.loading)
+            return; // single-flight
+        this.loading = this.fetcher(this.etag)
+            .then((result) => {
+            if (result.notModified) {
+                this.loadedAt = this.now();
+                return;
+            }
+            const next = new Map();
+            for (const p of result.policies) {
+                if (p && typeof p.agent_key === 'string') {
+                    next.set(normalizeAgentKey(p.agent_key), p);
+                }
+            }
+            this.byKey = next;
+            this.etag = result.etag ?? null;
+            this.loaded = true;
+            this.loadedAt = this.now();
+        })
+            .catch(() => {
+            // F1: fetch failure never surfaces; state stays as-is (or unknown).
+        })
+            .finally(() => {
+            this.loading = null;
+        });
+    }
+}
+/** Normalization rule shared with policy writes (spec §5.1 M8). */
+export function normalizeAgentKey(key) {
+    return key.trim().toLowerCase();
+}
+//# sourceMappingURL=routing-policy-cache.js.map

package/dist/routing-policy-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-policy-cache.js","sourceRoot":"","sources":["../src/routing-policy-cache.ts"],"names":[],"mappings":"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"}

package/dist/routing.d.ts

@@ -0,0 +1,188 @@
+/**
+ * SDK cascade routing module — `runWithPolicy()` (spec
+ * docs/roi-engine-cascade-sdk-phase1-spec.md §5, Phase 1 S2).
+ *
+ * Bring-your-own-caller: the customer supplies the function that calls their
+ * provider with THEIR keys; this module supplies policy consultation, the
+ * confidence gate, escalation, holdout randomization, and evidence emission.
+ *
+ * THE INVARIANT (throw-parity, §5.7): no code path in runWithPolicy throws an
+ * error that the customer's own `callModel(prodModel)` would not have thrown.
+ * Policy fetch, gate, candidate calls, and every emit fail OPEN; only the
+ * production-model call's own errors propagate.
+ *
+ * Streaming is OUT OF SCOPE for v1 (§5.1 H7): this contract handles complete
+ * responses only — keep streaming call sites on their original path.
+ */
+import type { MetrxbotClient } from './client';
+/** Bump with package.json (atomic-version rule). Server can force pass-through
+ * for known-bad versions via routing_policies.min_sdk_version (F10).
+ * 0.2.2 = the FIRST published version carrying WS1 (task-keyed holdout draw,
+ * #260) — required for `randomization_unit:'task'` policies to draw causal arms.
+ * The npm-published 0.2.1 predates WS1; min_sdk_version must be '0.2.2'+ to gate. */
+export declare const SDK_VERSION = "0.2.2";
+/**
+ * WS1 (Phase 3): deterministic map of a string to a uniform value in [0, 1).
+ * FNV-1a (32-bit) — stable across runs/processes and well-distributed, so the
+ * empirical treatment fraction over many task ids matches `holdout_pct`. Used to
+ * make the holdout arm a function of the TASK id (whole-task treatment) so
+ * multi-request tasks are arm-consistent — the prerequisite for task-level
+ * causal value evidence (Phase 3 D10). Mirrors the gateway's deterministicBucket
+ * (apps/gateway/src/model-routing.ts) but returns a unit float, not a %-bucket.
+ */
+export declare function hashToUnit(input: string): number;
+export interface ModelCallResult {
+    output: string;
+    costMicrocents?: number;
+    /** Server-side cost fallback via model_registry pricing when cost is absent. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    raw?: unknown;
+}
+/**
+ * Call-context handed to the customer's `ModelCaller`/`checkerCaller` on every
+ * provider call (v0.2.1, additive). Lets caller-side instrumentation (a) stamp
+ * `requestId`/`experimentId`/`arm` on the provider call so cascade cost SUMs
+ * join across `llm_events ↔ optimization_decisions ↔ quality`, and (b) detect
+ * the background shadow candidate (`phase === 'shadow_candidate'`) and suppress
+ * it from a cost dashboard.
+ *
+ * `phase` marks which leg of routing is making the call:
+ *   - `primary`          served production call (pass-through, shadow served,
+ *                        cascade control arm)
+ *   - `candidate`        cascade treatment candidate (the cheaper model)
+ *   - `escalation`       cascade treatment fell back to the production model
+ *   - `shadow_candidate` background dual-call in shadow_sample (never served)
+ *   - `checker`          any `checkerCaller` invocation (gate + post-response judging)
+ */
+export interface ModelCallContext {
+    requestId: string;
+    experimentId?: string;
+    arm?: 'control' | 'treatment';
+    phase: 'primary' | 'candidate' | 'escalation' | 'shadow_candidate' | 'checker';
+}
+export interface ModelCaller {
+    /**
+     * `model === undefined` ⇒ "call your own default" — the day-0 pass-through
+     * contract (§5.1 M2). The input is passed through verbatim and is never
+     * serialized to Metrx.
+     *
+     * `ctx` (v0.2.1) is an OPTIONAL third argument — existing two-arg callers
+     * keep working unchanged. It is purely informational: it never changes what
+     * the router serves and passing it introduces no new throw path (§5.7).
+     */
+    (model: string | undefined, input: unknown, ctx?: ModelCallContext): Promise<ModelCallResult>;
+}
+export interface ClientJudge {
+    (args: {
+        input: unknown;
+        output: string;
+        model: string;
+    }): Promise<{
+        score: number;
+        judgeModel: string;
+    }>;
+}
+export interface RunWithPolicyOptions {
+    agentKey: string;
+    /** The customer's own provider call — their client, their keys. */
+    callModel: ModelCaller;
+    /**
+     * Caller for the cross-family checker model. REQUIRED for shadow/cascade
+     * when the checker family is one the primary caller can't reach (e.g. an
+     * all-Anthropic customer with a non-Anthropic checker — §5.3 C3).
+     */
+    checkerCaller?: ModelCaller;
+    input: unknown;
+    /** Optional custom scorer; default = the G4 checker via checkerCaller. */
+    judge?: ClientJudge;
+    requestId?: string;
+}
+export interface RunWithPolicyResult {
+    output: string;
+    /** undefined on no-policy pass-through (the customer's own default ran). */
+    servedModel: string | undefined;
+    escalated: boolean;
+    arm?: 'control' | 'treatment';
+    /** Cascade experiment id — attach to telemetry events (with the arm) so the
+     * contamination guard can exclude routed calls from baselines. */
+    experimentId?: string;
+    requestId: string;
+    /** What the policy said: pass_through | shadow_sample | cascade | disabled. */
+    mode: string;
+}
+export interface RouterConfig {
+    apiKey: string;
+    apiUrl: string;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    random?: () => number;
+    /** Hard local kill switch (F10); also honors METRX_ROUTING_DISABLED=true. */
+    disabled?: boolean;
+    policyTtlMs?: number;
+    policyStaleMaxMs?: number;
+}
+export declare class MetrxRouter {
+    private readonly cfg;
+    private readonly cache;
+    private readonly now;
+    private readonly random;
+    private readonly fetchImpl;
+    private readonly breakers;
+    private readonly background;
+    constructor(cfg: RouterConfig);
+    /** Await all in-flight background work (emits, shadow calls, judging).
+     * For tests and graceful shutdown — never required for correctness. */
+    flush(): Promise<void>;
+    run(opts: RunWithPolicyOptions): Promise<RunWithPolicyResult>;
+    private passThrough;
+    private runShadowSample;
+    /**
+     * WS1 (Phase 3): the holdout-arm uniform draw.
+     *
+     * DEFAULT (`gate_config.randomization_unit` unset or `'request'`): a per-request
+     * Bernoulli via `this.random()` — BYTE-IDENTICAL to pre-Phase-3 behaviour. This
+     * is the live cascade path for every policy, so it must not change unless the
+     * policy explicitly opts in.
+     *
+     * TASK unit (`gate_config.randomization_unit === 'task'`): a DETERMINISTIC
+     * function of the current task id, so every request inside one `task()` lands on
+     * the same arm (whole-task treatment) → multi-request tasks are arm-consistent →
+     * task-level value evidence becomes causal (Phase 3 D10). Salted with
+     * `experiment_id` so a judge/experiment rotation re-randomizes assignments.
+     *
+     * Falls back to the per-request draw when there is no task context OR no
+     * `experiment_id` (M2 — never silently salt with a literal 'null'): those
+     * requests stay the Phase-2 non-actionable stratum, no throw, no regression.
+     */
+    private holdoutUniform;
+    private runCascade;
+    private judgeOutput;
+    private emitDecision;
+    private emitPair;
+    private emitQuality;
+    private fireAndForget;
+    /** F8/F9: background work never throws into the request path. */
+    private spawnBackground;
+    private breakerFor;
+    private breakerOpen;
+    private recordCandidateError;
+    private recordEscalation;
+    private makePolicyFetcher;
+}
+export declare function routerFor(client: MetrxbotClient, overrides?: Partial<RouterConfig>): MetrxRouter;
+/**
+ * Run one request under the agent's routing policy. Day 0 (no policy rows):
+ * behaves exactly like `opts.callModel(undefined, opts.input)`.
+ */
+export declare function runWithPolicy(client: MetrxbotClient, opts: RunWithPolicyOptions): Promise<RunWithPolicyResult>;
+/**
+ * Loose semver-ish comparison. Returns true when a < b, false when a >= b,
+ * and `undefined` when either side is unparseable — the caller treats
+ * "unknown" as pass-through (fail toward doing nothing).
+ */
+export declare function semverLt(a: string, b: string): boolean | undefined;
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"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"}