@blockrun/clawrouter 0.12.95 → 0.12.97

package/dist/router/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Smart Router Types
+ *
+ * Four classification tiers — REASONING is distinct from COMPLEX because
+ * reasoning tasks need different models (o3, gemini-pro) than general
+ * complex tasks (gpt-4o, sonnet-4).
+ *
+ * Scoring uses weighted float dimensions with sigmoid confidence calibration.
+ */
+export type Tier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+export type ScoringResult = {
+    score: number;
+    tier: Tier | null;
+    confidence: number;
+    signals: string[];
+    agenticScore?: number;
+    dimensions?: Array<{
+        name: string;
+        score: number;
+        signal: string | null;
+    }>;
+};
+export type RoutingDecision = {
+    model: string;
+    tier: Tier;
+    confidence: number;
+    method: "rules" | "llm";
+    reasoning: string;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+    agenticScore?: number;
+    /** Which tier configs were used (auto/eco/premium/agentic) — avoids re-derivation in proxy */
+    tierConfigs?: Record<Tier, TierConfig>;
+    /** Which routing profile was applied */
+    profile?: "auto" | "eco" | "premium" | "agentic";
+};
+export interface RouterStrategy {
+    readonly name: string;
+    route(prompt: string, systemPrompt: string | undefined, maxOutputTokens: number, options: RouterOptions): RoutingDecision;
+}
+export type RouterOptions = {
+    config: RoutingConfig;
+    modelPricing: Map<string, import("./selector.js").ModelPricing>;
+    routingProfile?: "eco" | "auto" | "premium";
+    hasTools?: boolean;
+};
+export type TierConfig = {
+    primary: string;
+    fallback: string[];
+};
+export type ScoringConfig = {
+    tokenCountThresholds: {
+        simple: number;
+        complex: number;
+    };
+    codeKeywords: string[];
+    reasoningKeywords: string[];
+    simpleKeywords: string[];
+    technicalKeywords: string[];
+    creativeKeywords: string[];
+    imperativeVerbs: string[];
+    constraintIndicators: string[];
+    outputFormatKeywords: string[];
+    referenceKeywords: string[];
+    negationKeywords: string[];
+    domainSpecificKeywords: string[];
+    agenticTaskKeywords: string[];
+    dimensionWeights: Record<string, number>;
+    tierBoundaries: {
+        simpleMedium: number;
+        mediumComplex: number;
+        complexReasoning: number;
+    };
+    confidenceSteepness: number;
+    confidenceThreshold: number;
+};
+export type ClassifierConfig = {
+    llmModel: string;
+    llmMaxTokens: number;
+    llmTemperature: number;
+    promptTruncationChars: number;
+    cacheTtlMs: number;
+};
+export type OverridesConfig = {
+    maxTokensForceComplex: number;
+    structuredOutputMinTier: Tier;
+    ambiguousDefaultTier: Tier;
+    /**
+     * When enabled, prefer models optimized for agentic workflows.
+     * Agentic models continue autonomously with multi-step tasks
+     * instead of stopping and waiting for user input.
+     */
+    agenticMode?: boolean;
+};
+/**
+ * Time-windowed promotion that temporarily overrides tier routing.
+ * Active promotions are auto-applied; expired ones are ignored at runtime.
+ */
+export type Promotion = {
+    /** Human-readable label (e.g. "GLM-5 Launch Promo") */
+    name: string;
+    /** ISO date string, promotion starts (inclusive). e.g. "2026-04-01" */
+    startDate: string;
+    /** ISO date string, promotion ends (exclusive). e.g. "2026-04-15" */
+    endDate: string;
+    /** Partial tier overrides — merged into the active tier configs (primary/fallback) */
+    tierOverrides: Partial<Record<Tier, Partial<TierConfig>>>;
+    /** Which profiles this applies to. Default: all profiles. */
+    profiles?: Array<"auto" | "eco" | "premium" | "agentic">;
+};
+export type RoutingConfig = {
+    version: string;
+    classifier: ClassifierConfig;
+    scoring: ScoringConfig;
+    tiers: Record<Tier, TierConfig>;
+    /** Tier configs for agentic mode - models that excel at multi-step tasks */
+    agenticTiers?: Record<Tier, TierConfig>;
+    /** Tier configs for eco profile - ultra cost-optimized (blockrun/eco) */
+    ecoTiers?: Record<Tier, TierConfig>;
+    /** Tier configs for premium profile - best quality (blockrun/premium) */
+    premiumTiers?: Record<Tier, TierConfig>;
+    /** Time-windowed promotions that temporarily override tier routing */
+    promotions?: Promotion[];
+    overrides: OverridesConfig;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/router/types.d.ts.map

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

package/dist/router/types.js

@@ -0,0 +1,11 @@
+/**
+ * Smart Router Types
+ *
+ * Four classification tiers — REASONING is distinct from COMPLEX because
+ * reasoning tasks need different models (o3, gemini-pro) than general
+ * complex tasks (gpt-4o, sonnet-4).
+ *
+ * Scoring uses weighted float dimensions with sigmoid confidence calibration.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/router/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/router/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/session.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Session Persistence Store
+ *
+ * Tracks model selections per session to prevent model switching mid-task.
+ * When a session is active, the router will continue using the same model
+ * instead of re-routing each request.
+ */
+export type SessionEntry = {
+    model: string;
+    tier: string;
+    createdAt: number;
+    lastUsedAt: number;
+    requestCount: number;
+    recentHashes: string[];
+    strikes: number;
+    escalated: boolean;
+    sessionCostMicros: bigint;
+};
+export type SessionConfig = {
+    /** Enable session persistence (default: false) */
+    enabled: boolean;
+    /** Session timeout in ms (default: 30 minutes) */
+    timeoutMs: number;
+    /** Header name for session ID (default: X-Session-ID) */
+    headerName: string;
+};
+export declare const DEFAULT_SESSION_CONFIG: SessionConfig;
+/**
+ * Session persistence store for maintaining model selections.
+ */
+export declare class SessionStore {
+    private sessions;
+    private config;
+    private cleanupInterval;
+    constructor(config?: Partial<SessionConfig>);
+    /**
+     * Get the pinned model for a session, if any.
+     */
+    getSession(sessionId: string): SessionEntry | undefined;
+    /**
+     * Pin a model to a session.
+     */
+    setSession(sessionId: string, model: string, tier: string): void;
+    /**
+     * Touch a session to extend its timeout.
+     */
+    touchSession(sessionId: string): void;
+    /**
+     * Clear a specific session.
+     */
+    clearSession(sessionId: string): void;
+    /**
+     * Clear all sessions.
+     */
+    clearAll(): void;
+    /**
+     * Get session stats for debugging.
+     */
+    getStats(): {
+        count: number;
+        sessions: Array<{
+            id: string;
+            model: string;
+            age: number;
+        }>;
+    };
+    /**
+     * Clean up expired sessions.
+     */
+    private cleanup;
+    /**
+     * Record a request content hash and detect repetitive patterns.
+     * Returns true if escalation should be triggered (3+ consecutive similar requests).
+     */
+    recordRequestHash(sessionId: string, hash: string): boolean;
+    /**
+     * Escalate session to next tier. Returns the new model/tier or null if already at max.
+     */
+    escalateSession(sessionId: string, tierConfigs: Record<string, {
+        primary: string;
+        fallback: string[];
+    }>): {
+        model: string;
+        tier: string;
+    } | null;
+    /**
+     * Add cost to a session's running total for maxCostPerRun tracking.
+     * Cost is in USDC 6-decimal units (micros).
+     * Creates a cost-tracking-only entry if none exists (e.g., explicit model requests
+     * that never go through the routing path).
+     */
+    addSessionCost(sessionId: string, additionalMicros: bigint): void;
+    /**
+     * Get the total accumulated cost for a session in USD.
+     */
+    getSessionCostUsd(sessionId: string): number;
+    /**
+     * Stop the cleanup interval.
+     */
+    close(): void;
+}
+/**
+ * Generate a session ID from request headers or create a default.
+ */
+export declare function getSessionId(headers: Record<string, string | string[] | undefined>, headerName?: string): string | undefined;
+/**
+ * Derive a stable session ID from message content when no explicit session
+ * header is provided. Uses the first user message as the conversation anchor —
+ * same opening message = same session ID across all subsequent turns.
+ *
+ * This prevents model-switching mid-conversation even when OpenClaw doesn't
+ * send an x-session-id header (which is the default OpenClaw behaviour).
+ */
+export declare function deriveSessionId(messages: Array<{
+    role: string;
+    content: unknown;
+}>): string | undefined;
+/**
+ * Generate a short hash fingerprint from request content.
+ * Captures: last user message text + tool call names (if any).
+ * Normalizes whitespace to avoid false negatives from minor formatting diffs.
+ */
+export declare function hashRequestContent(lastUserContent: string, toolCallNames?: string[]): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IAErB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IAEnB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,aAIpC,CAAC;AAEF;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAwC;IACxD,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,eAAe,CAA+C;gBAE1D,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM;IAS/C;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAoBvD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IA+BhE;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAYrC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;IAU1F;;OAEG;IACH,OAAO,CAAC,OAAO;IASf;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAmB3D;;OAEG;IACH,eAAe,CACb,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GACnE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAoBzC;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAoBjE;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAM5C;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,UAAU,GAAE,MAA0C,GACrD,MAAM,GAAG,SAAS,CASpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,GAClD,MAAM,GAAG,SAAS,CAUpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAO5F"}

package/dist/session.js

@@ -0,0 +1,256 @@
+/**
+ * Session Persistence Store
+ *
+ * Tracks model selections per session to prevent model switching mid-task.
+ * When a session is active, the router will continue using the same model
+ * instead of re-routing each request.
+ */
+import { createHash } from "node:crypto";
+export const DEFAULT_SESSION_CONFIG = {
+    enabled: true,
+    timeoutMs: 30 * 60 * 1000, // 30 minutes
+    headerName: "x-session-id",
+};
+/**
+ * Session persistence store for maintaining model selections.
+ */
+export class SessionStore {
+    sessions = new Map();
+    config;
+    cleanupInterval = null;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_SESSION_CONFIG, ...config };
+        // Start cleanup interval (every 5 minutes)
+        if (this.config.enabled) {
+            this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+        }
+    }
+    /**
+     * Get the pinned model for a session, if any.
+     */
+    getSession(sessionId) {
+        if (!this.config.enabled || !sessionId) {
+            return undefined;
+        }
+        const entry = this.sessions.get(sessionId);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if session has expired
+        const now = Date.now();
+        if (now - entry.lastUsedAt > this.config.timeoutMs) {
+            this.sessions.delete(sessionId);
+            return undefined;
+        }
+        return entry;
+    }
+    /**
+     * Pin a model to a session.
+     */
+    setSession(sessionId, model, tier) {
+        if (!this.config.enabled || !sessionId) {
+            return;
+        }
+        const existing = this.sessions.get(sessionId);
+        const now = Date.now();
+        if (existing) {
+            existing.lastUsedAt = now;
+            existing.requestCount++;
+            // Update model if different (e.g., fallback)
+            if (existing.model !== model) {
+                existing.model = model;
+                existing.tier = tier;
+            }
+        }
+        else {
+            this.sessions.set(sessionId, {
+                model,
+                tier,
+                createdAt: now,
+                lastUsedAt: now,
+                requestCount: 1,
+                recentHashes: [],
+                strikes: 0,
+                escalated: false,
+                sessionCostMicros: 0n,
+            });
+        }
+    }
+    /**
+     * Touch a session to extend its timeout.
+     */
+    touchSession(sessionId) {
+        if (!this.config.enabled || !sessionId) {
+            return;
+        }
+        const entry = this.sessions.get(sessionId);
+        if (entry) {
+            entry.lastUsedAt = Date.now();
+            entry.requestCount++;
+        }
+    }
+    /**
+     * Clear a specific session.
+     */
+    clearSession(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    /**
+     * Clear all sessions.
+     */
+    clearAll() {
+        this.sessions.clear();
+    }
+    /**
+     * Get session stats for debugging.
+     */
+    getStats() {
+        const now = Date.now();
+        const sessions = Array.from(this.sessions.entries()).map(([id, entry]) => ({
+            id: id.slice(0, 8) + "...",
+            model: entry.model,
+            age: Math.round((now - entry.createdAt) / 1000),
+        }));
+        return { count: this.sessions.size, sessions };
+    }
+    /**
+     * Clean up expired sessions.
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [id, entry] of this.sessions) {
+            if (now - entry.lastUsedAt > this.config.timeoutMs) {
+                this.sessions.delete(id);
+            }
+        }
+    }
+    /**
+     * Record a request content hash and detect repetitive patterns.
+     * Returns true if escalation should be triggered (3+ consecutive similar requests).
+     */
+    recordRequestHash(sessionId, hash) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return false;
+        const prev = entry.recentHashes;
+        if (prev.length > 0 && prev[prev.length - 1] === hash) {
+            entry.strikes++;
+        }
+        else {
+            entry.strikes = 0;
+        }
+        entry.recentHashes.push(hash);
+        if (entry.recentHashes.length > 3) {
+            entry.recentHashes.shift();
+        }
+        return entry.strikes >= 2 && !entry.escalated;
+    }
+    /**
+     * Escalate session to next tier. Returns the new model/tier or null if already at max.
+     */
+    escalateSession(sessionId, tierConfigs) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return null;
+        const TIER_ORDER = ["SIMPLE", "MEDIUM", "COMPLEX", "REASONING"];
+        const currentIdx = TIER_ORDER.indexOf(entry.tier);
+        if (currentIdx < 0 || currentIdx >= TIER_ORDER.length - 1)
+            return null;
+        const nextTier = TIER_ORDER[currentIdx + 1];
+        const nextConfig = tierConfigs[nextTier];
+        if (!nextConfig)
+            return null;
+        entry.model = nextConfig.primary;
+        entry.tier = nextTier;
+        entry.strikes = 0;
+        entry.escalated = true;
+        return { model: nextConfig.primary, tier: nextTier };
+    }
+    /**
+     * Add cost to a session's running total for maxCostPerRun tracking.
+     * Cost is in USDC 6-decimal units (micros).
+     * Creates a cost-tracking-only entry if none exists (e.g., explicit model requests
+     * that never go through the routing path).
+     */
+    addSessionCost(sessionId, additionalMicros) {
+        let entry = this.sessions.get(sessionId);
+        if (!entry) {
+            const now = Date.now();
+            entry = {
+                model: "",
+                tier: "DIRECT",
+                createdAt: now,
+                lastUsedAt: now,
+                requestCount: 0,
+                recentHashes: [],
+                strikes: 0,
+                escalated: false,
+                sessionCostMicros: 0n,
+            };
+            this.sessions.set(sessionId, entry);
+        }
+        entry.sessionCostMicros += additionalMicros;
+    }
+    /**
+     * Get the total accumulated cost for a session in USD.
+     */
+    getSessionCostUsd(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return 0;
+        return Number(entry.sessionCostMicros) / 1_000_000;
+    }
+    /**
+     * Stop the cleanup interval.
+     */
+    close() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+}
+/**
+ * Generate a session ID from request headers or create a default.
+ */
+export function getSessionId(headers, headerName = DEFAULT_SESSION_CONFIG.headerName) {
+    const value = headers[headerName] || headers[headerName.toLowerCase()];
+    if (typeof value === "string" && value.length > 0) {
+        return value;
+    }
+    if (Array.isArray(value) && value.length > 0) {
+        return value[0];
+    }
+    return undefined;
+}
+/**
+ * Derive a stable session ID from message content when no explicit session
+ * header is provided. Uses the first user message as the conversation anchor —
+ * same opening message = same session ID across all subsequent turns.
+ *
+ * This prevents model-switching mid-conversation even when OpenClaw doesn't
+ * send an x-session-id header (which is the default OpenClaw behaviour).
+ */
+export function deriveSessionId(messages) {
+    const firstUser = messages.find((m) => m.role === "user");
+    if (!firstUser)
+        return undefined;
+    const content = typeof firstUser.content === "string" ? firstUser.content : JSON.stringify(firstUser.content);
+    // 8-char hex prefix of SHA-256 — short enough for logs, collision-resistant
+    // enough for session tracking within a single gateway instance.
+    return createHash("sha256").update(content).digest("hex").slice(0, 8);
+}
+/**
+ * Generate a short hash fingerprint from request content.
+ * Captures: last user message text + tool call names (if any).
+ * Normalizes whitespace to avoid false negatives from minor formatting diffs.
+ */
+export function hashRequestContent(lastUserContent, toolCallNames) {
+    const normalized = lastUserContent.replace(/\s+/g, " ").trim().slice(0, 500);
+    const toolSuffix = toolCallNames?.length ? `|tools:${toolCallNames.sort().join(",")}` : "";
+    return createHash("sha256")
+        .update(normalized + toolSuffix)
+        .digest("hex")
+        .slice(0, 12);
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/session.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session.test.d.ts.map

package/dist/session.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.test.d.ts","sourceRoot":"","sources":["../src/session.test.ts"],"names":[],"mappings":""}