pi-smart-router 0.1.0

package/dist/domain/matching/hydra-matcher.js

@@ -0,0 +1,275 @@
+/**
+ * HyDRA embedding matcher — T048, FR-005.
+ *
+ * Embeds prompt text via ONNX (Xenova/all-MiniLM-L6-v2 384-dim),
+ * projects to requirement dimensions [reasoning, code_gen, tool_use],
+ * and scores fleet candidates with a shortfall gate.
+ *
+ * Shortfall gate (data-model §Validation): candidate excluded when
+ * any capability dimension shortfall > 0 (quality parity).
+ *
+ * Budget: 80–120 ms (configurable, default 100 ms).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { DEFAULT_OPERATOR_CONFIG } from '../../config/defaults.js';
+import { buildHydraInput } from './hydra-input.js';
+import { createOnnxTextEmbedder, EMBEDDING_DIM, } from './embedding-provider.js';
+import { scoreMultiObjective, } from '../scoring/multi-objective.js';
+const DEFAULT_BUDGET_MS = 100;
+const MIN_BUDGET_MS = 80;
+const MAX_BUDGET_MS = 120;
+export const DEFAULT_HYDRA_PROJECTION_WEIGHTS_PATH = resolve('config', 'hydra-projection-weights.json');
+export const HYDRA_PROJECTION_OUTPUT_DIM = 3;
+export const HydraProjectionWeightsSchema = z.object({
+    version: z.literal(1),
+    embedding_dim: z.literal(EMBEDDING_DIM),
+    weights: z
+        .array(z.array(z.number().finite()).length(EMBEDDING_DIM))
+        .length(HYDRA_PROJECTION_OUTPUT_DIM),
+    bias: z.array(z.number().finite()).length(HYDRA_PROJECTION_OUTPUT_DIM),
+});
+export class HydraProjectionWeightsLoaderError extends Error {
+    name = 'HydraProjectionWeightsLoaderError';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+function formatZodIssues(error) {
+    return error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('\n');
+}
+export function parseHydraProjectionWeightsJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new HydraProjectionWeightsLoaderError(`Failed to parse JSON: ${message}`, {
+            cause: err,
+        });
+    }
+    const result = HydraProjectionWeightsSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new HydraProjectionWeightsLoaderError(`Invalid HyDRA projection weights artifact:\n${formatZodIssues(result.error)}`, { cause: result.error });
+    }
+    return result.data;
+}
+/**
+ * Load HyDRA projection weights from disk. Returns null when the artifact is
+ * missing; throws only when the file exists but is invalid.
+ */
+export function loadHydraProjectionWeights(options) {
+    const filePath = options?.filePath ?? DEFAULT_HYDRA_PROJECTION_WEIGHTS_PATH;
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new HydraProjectionWeightsLoaderError(`Failed to read weights file: ${message}`, {
+            cause: err,
+        });
+    }
+    return parseHydraProjectionWeightsJson(raw);
+}
+/** Resolve projection weights — missing artifacts fall back to placeholder projection. */
+export function resolveHydraProjectionWeights(options) {
+    try {
+        return loadHydraProjectionWeights(options);
+    }
+    catch (err) {
+        console.warn('HyDRA projection weights artifact invalid; using placeholder projection', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}
+// ─── Scoring helpers ─────────────────────────────────────────────────────────
+function dimensionShortfall(requirement, capability) {
+    return Math.max(0, requirement - capability);
+}
+function computeShortfall(requirement, capabilities) {
+    const reasoning = dimensionShortfall(requirement.reasoning, capabilities.reasoning);
+    const codeGen = dimensionShortfall(requirement.code_gen, capabilities.code_gen);
+    const toolUse = dimensionShortfall(requirement.tool_use, capabilities.tool_use);
+    return {
+        perDimension: { reasoning, code_gen: codeGen, tool_use: toolUse },
+        max: Math.max(reasoning, codeGen, toolUse),
+        total: reasoning + codeGen + toolUse,
+    };
+}
+function cosineSimilarity(a, b) {
+    const dot = a.reasoning * b.reasoning + a.code_gen * b.code_gen + a.tool_use * b.tool_use;
+    const magA = Math.sqrt(a.reasoning ** 2 + a.code_gen ** 2 + a.tool_use ** 2);
+    const magB = Math.sqrt(b.reasoning ** 2 + b.code_gen ** 2 + b.tool_use ** 2);
+    if (magA === 0 || magB === 0)
+        return 0;
+    return dot / (magA * magB);
+}
+// ─── Projection helpers (384-dim → 3 requirement dimensions) ─────────────────
+function sigmoid(x) {
+    return 1 / (1 + Math.exp(-x));
+}
+function meanSlice(embedding, start, end) {
+    let sum = 0;
+    for (let i = start; i < end; i++) {
+        sum += embedding[i] ?? 0;
+    }
+    return sum / (end - start);
+}
+function projectToRequirementsPlaceholder(embedding) {
+    const third = Math.floor(EMBEDDING_DIM / 3);
+    return {
+        reasoning: sigmoid(meanSlice(embedding, 0, third)),
+        code_gen: sigmoid(meanSlice(embedding, third, 2 * third)),
+        tool_use: sigmoid(meanSlice(embedding, 2 * third, EMBEDDING_DIM)),
+    };
+}
+function linearProjection(embedding, weights) {
+    const logits = [];
+    for (let dim = 0; dim < HYDRA_PROJECTION_OUTPUT_DIM; dim++) {
+        const row = weights.weights[dim];
+        let sum = weights.bias[dim] ?? 0;
+        for (let i = 0; i < EMBEDDING_DIM; i++) {
+            sum += (embedding[i] ?? 0) * (row[i] ?? 0);
+        }
+        logits.push(sum);
+    }
+    return [logits[0], logits[1], logits[2]];
+}
+function projectToRequirementsLearned(embedding, weights) {
+    const [reasoningLogit, codeGenLogit, toolUseLogit] = linearProjection(embedding, weights);
+    return {
+        reasoning: sigmoid(reasoningLogit),
+        code_gen: sigmoid(codeGenLogit),
+        tool_use: sigmoid(toolUseLogit),
+    };
+}
+/**
+ * Project a 384-dim embedding to 3 requirement dimensions.
+ *
+ * Uses learned linear projection (sigmoid(embedding @ W + b)) when weights are
+ * provided; otherwise falls back to deterministic mean-pooled-thirds placeholder.
+ */
+export function projectToRequirements(embedding, weights) {
+    if (embedding.length !== EMBEDDING_DIM) {
+        throw new Error(`Embedding shape mismatch: expected ${EMBEDDING_DIM}, got ${embedding.length}`);
+    }
+    if (weights) {
+        return projectToRequirementsLearned(embedding, weights);
+    }
+    return projectToRequirementsPlaceholder(embedding);
+}
+// ─── HyDRA embedding adapter ─────────────────────────────────────────────────
+/**
+ * Adapts a shared TextEmbedder for HyDRA requirement extraction.
+ * dispose() delegates to the underlying embedder for shared lifecycle.
+ */
+export function wrapHydraEmbeddingProvider(embedder, projectionWeights) {
+    return {
+        async extractRequirements(text) {
+            const embedding = await embedder.embed(text);
+            return projectToRequirements(embedding, projectionWeights);
+        },
+        async dispose() {
+            await embedder.dispose();
+        },
+    };
+}
+// ─── HydraMatcher ────────────────────────────────────────────────────────────
+export class HydraMatcher {
+    provider;
+    budgetMs;
+    frugality;
+    projectionWeights;
+    constructor(provider, config) {
+        const budget = config.budgetMs ?? DEFAULT_BUDGET_MS;
+        if (budget < MIN_BUDGET_MS || budget > MAX_BUDGET_MS) {
+            throw new Error(`HyDRA budget must be ${MIN_BUDGET_MS}–${MAX_BUDGET_MS}ms, got ${budget}ms`);
+        }
+        this.provider = provider;
+        this.budgetMs = budget;
+        this.frugality = config.frugality ?? DEFAULT_OPERATOR_CONFIG.frugality;
+        this.projectionWeights = resolveHydraProjectionWeights(config.projectionWeightsPath ? { filePath: config.projectionWeightsPath } : undefined);
+    }
+    /** Whether learned projection weights were loaded at init. */
+    usesLearnedProjection() {
+        return this.projectionWeights !== null;
+    }
+    async match(request, fleet) {
+        const start = performance.now();
+        const requirements = await this.provider.extractRequirements(buildHydraInput(request));
+        this.validateRequirements(requirements);
+        const healthyFleet = fleet.filter((m) => m.healthy !== false);
+        const candidates = [];
+        for (const model of healthyFleet) {
+            const elapsed = performance.now() - start;
+            if (elapsed > this.budgetMs) {
+                break;
+            }
+            const shortfall = computeShortfall(requirements, model.capabilities);
+            const hasShortfall = shortfall.max > 0;
+            const score = hasShortfall
+                ? 0
+                : cosineSimilarity(requirements, model.capabilities);
+            candidates.push({
+                model_id: model.id,
+                score,
+                shortfall: shortfall.max,
+                rejected_reason: hasShortfall ? 'shortfall_gate' : null,
+            });
+        }
+        const shortfallByModel = new Map(candidates.map((c) => [c.model_id, c.shortfall]));
+        const multiObjective = scoreMultiObjective(candidates, healthyFleet, this.frugality);
+        const toCandidateScore = (scored) => ({
+            model_id: scored.model_id,
+            score: scored.composite_score,
+            shortfall: shortfallByModel.get(scored.model_id) ?? 0,
+            rejected_reason: scored.rejected_reason,
+        });
+        const rankedCandidates = multiObjective.candidates.map(toCandidateScore);
+        const selected = multiObjective.selected
+            ? toCandidateScore(multiObjective.selected)
+            : null;
+        const elapsedMs = performance.now() - start;
+        return {
+            selected,
+            candidates: rankedCandidates,
+            requirements,
+            elapsedMs,
+            budgetExceeded: elapsedMs > this.budgetMs,
+        };
+    }
+    async dispose() {
+        await this.provider.dispose();
+    }
+    validateRequirements(req) {
+        const dims = [
+            'reasoning',
+            'code_gen',
+            'tool_use',
+        ];
+        for (const key of dims) {
+            const value = req[key];
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new Error(`Invalid requirement dimension '${key}': ${String(value)}`);
+            }
+        }
+    }
+}
+/**
+ * Creates an EmbeddingProvider backed by the shared ONNX text embedder.
+ * For multi-matcher setups, create one TextEmbedder via createOnnxTextEmbedder
+ * and pass wrapHydraEmbeddingProvider(embedder) to HyDRA while sharing embed().
+ */
+export async function createOnnxEmbeddingProvider(artifactCachePath, options) {
+    const embedder = await createOnnxTextEmbedder(artifactCachePath);
+    const projectionWeights = resolveHydraProjectionWeights(options?.projectionWeightsPath ? { filePath: options.projectionWeightsPath } : undefined);
+    return wrapHydraEmbeddingProvider(embedder, projectionWeights);
+}
+//# sourceMappingURL=hydra-matcher.js.map

package/dist/domain/matching/hydra-matcher.js.map

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

package/dist/domain/pinning/cache-economics.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cache-warmup economics — FR-008 rule #4, SC-006.
+ *
+ * Decides whether switching providers justifies the cache-warmup penalty.
+ * A provider switch invalidates upstream KV-cache, so the router must
+ * compare the warmup cost against projected savings from the candidate
+ * model before breaking a pin.
+ *
+ * When warmup cost exceeds projected savings the pin holds (User Story 4,
+ * scenario 4).
+ */
+import type { ModelProfile, SessionPin } from '../types/index.js';
+export interface CacheEconomicsConfig {
+    /**
+     * Multiplier applied to estimated_input_tokens to approximate
+     * the token cost of re-prompting a cold provider cache.
+     * Default: 1.15 (15 % warmup overhead).
+     */
+    readonly warmupCostMultiplier?: number;
+    /**
+     * Minimum per-1M-token savings required to justify a provider switch.
+     * Prevents switching for negligible price differences.
+     * Default: 0.10 (USD).
+     */
+    readonly minSavingsThreshold?: number;
+    /**
+     * Number of remaining turns to amortize savings over.
+     * Higher values favor switching; lower values favor keeping the pin.
+     * Default: 5.
+     */
+    readonly projectedRemainingTurns?: number;
+}
+export interface CacheEconomicsResult {
+    readonly shouldSwitch: boolean;
+    readonly warmupCostUsd: number;
+    readonly projectedSavingsUsd: number;
+    readonly reason: string;
+}
+/**
+ * Evaluate whether switching from the currently-pinned model to a candidate
+ * on a different provider is justified by projected cost savings.
+ *
+ * Returns `shouldSwitch: false` when:
+ * - Candidate is on the same provider (no cache penalty).
+ *   Caller should handle same-provider switches without this check.
+ * - Warmup cost exceeds projected savings.
+ * - Savings fall below the minimum threshold.
+ *
+ * Returns `shouldSwitch: true` only when projected savings meaningfully
+ * exceed the cache-warmup penalty.
+ */
+export declare function evaluateCacheEconomics(pin: SessionPin, pinnedModel: ModelProfile, candidate: ModelProfile, estimatedInputTokens: number, config?: CacheEconomicsConfig): CacheEconomicsResult;
+//# sourceMappingURL=cache-economics.d.ts.map

package/dist/domain/pinning/cache-economics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-economics.d.ts","sourceRoot":"","sources":["../../../src/domain/pinning/cache-economics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIlE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,YAAY,EACzB,SAAS,EAAE,YAAY,EACvB,oBAAoB,EAAE,MAAM,EAC5B,MAAM,CAAC,EAAE,oBAAoB,GAC5B,oBAAoB,CAsDtB"}

package/dist/domain/pinning/cache-economics.js

@@ -0,0 +1,72 @@
+/**
+ * Cache-warmup economics — FR-008 rule #4, SC-006.
+ *
+ * Decides whether switching providers justifies the cache-warmup penalty.
+ * A provider switch invalidates upstream KV-cache, so the router must
+ * compare the warmup cost against projected savings from the candidate
+ * model before breaking a pin.
+ *
+ * When warmup cost exceeds projected savings the pin holds (User Story 4,
+ * scenario 4).
+ */
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+const DEFAULT_WARMUP_COST_MULTIPLIER = 1.15;
+const DEFAULT_MIN_SAVINGS_THRESHOLD = 0.10;
+const DEFAULT_PROJECTED_REMAINING_TURNS = 5;
+// ─── Evaluation ───────────────────────────────────────────────────────────────
+/**
+ * Evaluate whether switching from the currently-pinned model to a candidate
+ * on a different provider is justified by projected cost savings.
+ *
+ * Returns `shouldSwitch: false` when:
+ * - Candidate is on the same provider (no cache penalty).
+ *   Caller should handle same-provider switches without this check.
+ * - Warmup cost exceeds projected savings.
+ * - Savings fall below the minimum threshold.
+ *
+ * Returns `shouldSwitch: true` only when projected savings meaningfully
+ * exceed the cache-warmup penalty.
+ */
+export function evaluateCacheEconomics(pin, pinnedModel, candidate, estimatedInputTokens, config) {
+    const warmupMultiplier = config?.warmupCostMultiplier ?? DEFAULT_WARMUP_COST_MULTIPLIER;
+    const minSavings = config?.minSavingsThreshold ?? DEFAULT_MIN_SAVINGS_THRESHOLD;
+    const remainingTurns = config?.projectedRemainingTurns ?? DEFAULT_PROJECTED_REMAINING_TURNS;
+    if (pinnedModel.provider === candidate.provider) {
+        return {
+            shouldSwitch: false,
+            warmupCostUsd: 0,
+            projectedSavingsUsd: 0,
+            reason: 'same_provider_no_cache_penalty',
+        };
+    }
+    const tokenCountM = estimatedInputTokens / 1_000_000;
+    const warmupTokens = estimatedInputTokens * (warmupMultiplier - 1);
+    const warmupCostUsd = (warmupTokens / 1_000_000) * candidate.pricing.fallback_cost_per_1m;
+    const perTurnSavings = (pinnedModel.pricing.fallback_cost_per_1m -
+        candidate.pricing.fallback_cost_per_1m) *
+        tokenCountM;
+    const projectedSavingsUsd = perTurnSavings * remainingTurns;
+    if (projectedSavingsUsd < minSavings) {
+        return {
+            shouldSwitch: false,
+            warmupCostUsd,
+            projectedSavingsUsd,
+            reason: 'savings_below_threshold',
+        };
+    }
+    if (warmupCostUsd >= projectedSavingsUsd) {
+        return {
+            shouldSwitch: false,
+            warmupCostUsd,
+            projectedSavingsUsd,
+            reason: 'warmup_exceeds_savings',
+        };
+    }
+    return {
+        shouldSwitch: true,
+        warmupCostUsd,
+        projectedSavingsUsd,
+        reason: 'switch_justified',
+    };
+}
+//# sourceMappingURL=cache-economics.js.map

package/dist/domain/pinning/cache-economics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-economics.js","sourceRoot":"","sources":["../../../src/domain/pinning/cache-economics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoCH,iFAAiF;AAEjF,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAC5C,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAC3C,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAE5C,iFAAiF;AAEjF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAe,EACf,WAAyB,EACzB,SAAuB,EACvB,oBAA4B,EAC5B,MAA6B;IAE7B,MAAM,gBAAgB,GACpB,MAAM,EAAE,oBAAoB,IAAI,8BAA8B,CAAC;IACjE,MAAM,UAAU,GACd,MAAM,EAAE,mBAAmB,IAAI,6BAA6B,CAAC;IAC/D,MAAM,cAAc,GAClB,MAAM,EAAE,uBAAuB,IAAI,iCAAiC,CAAC;IAEvE,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ,EAAE,CAAC;QAChD,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,CAAC;YAChB,mBAAmB,EAAE,CAAC;YACtB,MAAM,EAAE,gCAAgC;SACzC,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,oBAAoB,GAAG,SAAS,CAAC;IAErD,MAAM,YAAY,GAAG,oBAAoB,GAAG,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC;IACnE,MAAM,aAAa,GACjB,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,oBAAoB,CAAC;IAEtE,MAAM,cAAc,GAClB,CAAC,WAAW,CAAC,OAAO,CAAC,oBAAoB;QACvC,SAAS,CAAC,OAAO,CAAC,oBAAoB,CAAC;QACzC,WAAW,CAAC;IAEd,MAAM,mBAAmB,GAAG,cAAc,GAAG,cAAc,CAAC;IAE5D,IAAI,mBAAmB,GAAG,UAAU,EAAE,CAAC;QACrC,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,aAAa;YACb,mBAAmB;YACnB,MAAM,EAAE,yBAAyB;SAClC,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,IAAI,mBAAmB,EAAE,CAAC;QACzC,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,aAAa;YACb,mBAAmB;YACnB,MAAM,EAAE,wBAAwB;SACjC,CAAC;IACJ,CAAC;IAED,OAAO;QACL,YAAY,EAAE,IAAI;QAClB,aAAa;QACb,mBAAmB;QACnB,MAAM,EAAE,kBAAkB;KAC3B,CAAC;AACJ,CAAC"}

package/dist/domain/pinning/loop-escalation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Loop escalation — FR-014, FR-008 rule #3.
+ *
+ * Detects bounded repeated identical tool failures and signals
+ * session pin escalation to a frontier-capable tier.
+ *
+ * Escalation fires once per session; no tier oscillation (FR-008).
+ * Threshold defaults to 3 identical tool failures (operator configurable).
+ *
+ * Design: pure evaluation function — caller (pipeline stage) is
+ * responsible for applying pin state updates via SessionPinner.
+ */
+import type { ModelProfile, RoutingRequest, SessionPin } from '../types/index.js';
+export interface LoopEscalationConfig {
+    readonly threshold: number;
+}
+export interface LoopEscalationResult {
+    readonly shouldEscalate: boolean;
+    readonly updatedPin: SessionPin | null;
+    readonly escalationTarget: ModelProfile | null;
+    readonly reason: string;
+}
+/**
+ * Extract a tool-failure signature from the request's messages.
+ * Returns null when the request does not carry a tool failure.
+ *
+ * Only inspects tool_result turns — other turn types cannot
+ * carry observational failure signals (FR-014: no post-generation judging).
+ */
+export declare function extractToolFailureSignature(request: RoutingRequest): string | null;
+/**
+ * Evaluate whether the session should escalate to a higher tier.
+ *
+ * Pure function — does not mutate pin state. Returns `updatedPin`
+ * when the caller should persist new failure-tracking state.
+ *
+ * Caller applies updates via `SessionPinner.loadPin()`, and on
+ * escalation via `breakPin()` + `recordPin()`.
+ */
+export declare function evaluateLoopEscalation(pin: SessionPin | null, request: RoutingRequest, fleet: readonly ModelProfile[], config: LoopEscalationConfig): LoopEscalationResult;
+//# sourceMappingURL=loop-escalation.d.ts.map

package/dist/domain/pinning/loop-escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-escalation.d.ts","sourceRoot":"","sources":["../../../src/domain/pinning/loop-escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIlF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAgBD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAclF;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,UAAU,GAAG,IAAI,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAkEtB"}

package/dist/domain/pinning/loop-escalation.js

@@ -0,0 +1,137 @@
+/**
+ * Loop escalation — FR-014, FR-008 rule #3.
+ *
+ * Detects bounded repeated identical tool failures and signals
+ * session pin escalation to a frontier-capable tier.
+ *
+ * Escalation fires once per session; no tier oscillation (FR-008).
+ * Threshold defaults to 3 identical tool failures (operator configurable).
+ *
+ * Design: pure evaluation function — caller (pipeline stage) is
+ * responsible for applying pin state updates via SessionPinner.
+ */
+// ─── Failure signature extraction ─────────────────────────────────────────────
+const FAILURE_PATTERNS = [
+    'error',
+    'fail',
+    'exception',
+    'timed out',
+    'timeout',
+    'econnrefused',
+    'enotfound',
+    'econnreset',
+    'epipe',
+];
+/**
+ * Extract a tool-failure signature from the request's messages.
+ * Returns null when the request does not carry a tool failure.
+ *
+ * Only inspects tool_result turns — other turn types cannot
+ * carry observational failure signals (FR-014: no post-generation judging).
+ */
+export function extractToolFailureSignature(request) {
+    const msgs = request.messages;
+    if (!msgs || msgs.length === 0)
+        return null;
+    for (let i = msgs.length - 1; i >= 0; i--) {
+        const msg = msgs[i];
+        if (msg.role === 'tool') {
+            if (looksLikeFailure(msg.content)) {
+                return computeSignature(msg.content);
+            }
+            return null;
+        }
+    }
+    return null;
+}
+function looksLikeFailure(content) {
+    const lower = content.toLowerCase();
+    return FAILURE_PATTERNS.some((p) => lower.includes(p));
+}
+/** Deterministic djb2 hash of normalised error content. */
+function computeSignature(content) {
+    const normalized = content.trim().slice(0, 256).toLowerCase();
+    let h = 5381;
+    for (let i = 0; i < normalized.length; i++) {
+        h = ((h << 5) + h + normalized.charCodeAt(i)) | 0;
+    }
+    return `tf:${(h >>> 0).toString(16)}`;
+}
+// ─── Evaluation ───────────────────────────────────────────────────────────────
+/**
+ * Evaluate whether the session should escalate to a higher tier.
+ *
+ * Pure function — does not mutate pin state. Returns `updatedPin`
+ * when the caller should persist new failure-tracking state.
+ *
+ * Caller applies updates via `SessionPinner.loadPin()`, and on
+ * escalation via `breakPin()` + `recordPin()`.
+ */
+export function evaluateLoopEscalation(pin, request, fleet, config) {
+    if (!pin) {
+        return noEscalation('no_pin');
+    }
+    if (pin.pin_reason === 'loop_escalation') {
+        return noEscalation('already_escalated');
+    }
+    if (request.turn_type !== 'tool_result') {
+        return noEscalation('not_tool_result');
+    }
+    const signature = extractToolFailureSignature(request);
+    if (!signature) {
+        if (pin.consecutive_tool_failures > 0) {
+            return {
+                shouldEscalate: false,
+                updatedPin: {
+                    ...pin,
+                    consecutive_tool_failures: 0,
+                    last_tool_failure_signature: null,
+                    updated_at: new Date().toISOString(),
+                },
+                escalationTarget: null,
+                reason: 'success_reset',
+            };
+        }
+        return noEscalation('no_failure');
+    }
+    const isIdentical = pin.last_tool_failure_signature === signature;
+    const newCount = isIdentical ? pin.consecutive_tool_failures + 1 : 1;
+    const updated = {
+        ...pin,
+        consecutive_tool_failures: newCount,
+        last_tool_failure_signature: signature,
+        updated_at: new Date().toISOString(),
+    };
+    if (newCount >= config.threshold) {
+        const target = selectEscalationTarget(fleet, pin.pinned_model_id);
+        if (target) {
+            return {
+                shouldEscalate: true,
+                updatedPin: updated,
+                escalationTarget: target,
+                reason: 'threshold_exceeded',
+            };
+        }
+        return {
+            shouldEscalate: false,
+            updatedPin: updated,
+            escalationTarget: null,
+            reason: 'no_frontier_available',
+        };
+    }
+    return {
+        shouldEscalate: false,
+        updatedPin: updated,
+        escalationTarget: null,
+        reason: 'below_threshold',
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function noEscalation(reason) {
+    return { shouldEscalate: false, updatedPin: null, escalationTarget: null, reason };
+}
+/** Select the best healthy frontier-cloud model that differs from the current pin. */
+function selectEscalationTarget(fleet, currentModelId) {
+    return (fleet.find((m) => m.tier === 'frontier-cloud' && m.id !== currentModelId && m.healthy !== false) ?? null);
+}
+//# sourceMappingURL=loop-escalation.js.map

package/dist/domain/pinning/loop-escalation.js.map

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