@kognai/clawrouter-x402 0.1.0

package/dist/clawrouter-x402/src/clawrouter-v2.js

@@ -0,0 +1,811 @@
+"use strict";
+/**
+ * clawrouter-v2.ts — ClawRouter Universal LLM Gateway v2.0
+ *
+ * THE SINGLE DOOR every LLM call passes through (ClawRouter Spec v2.0).
+ * Execution Protocol Section 17: ClawRouter Mandatory Gateway Rule.
+ *
+ * Routing Matrix:
+ *   T0 NANO    → qwen3:0.6b (local)     — classification, templating
+ *   T1 LOCAL   → qwen3:4b (local)       — QA, supervision, aggregation
+ *   T2 POWER   → qwen3:14b (local)      — primary execution engine
+ *   T2.5 EXEC  → Gemini Flash (API)     — cloud-quality, no constitutional
+ *   T3 APEX    → Claude Sonnet (API)    — constitutional judge only
+ *
+ * Rules:
+ *   - constitutional_flag=true → always T3 APEX
+ *   - Local tiers (T0/T1/T2) → Ollama direct ($0)
+ *   - Cloud tiers (T2.5/T3) → OpenClaw gateway at :18789
+ *   - QCG pre-compression for cloud tiers when context > 5000 tokens
+ *   - NO agent holds API keys — keys only in ClawRouter/.env
+ *
+ * @see ~/Documents/Kognai/Master Documents/clawrouter_spec_v2.docx
+ * @see ~/Documents/Kognai/Master Documents/execution_protocol_sections_17_18.docx
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCostLog = getCostLog;
+exports.getDailyCostDigest = getDailyCostDigest;
+exports.getMeterStats = getMeterStats;
+exports.routeCall = routeCall;
+exports.callLLM = callLLM;
+exports.clawRouterHealthCheck = clawRouterHealthCheck;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const wallet_state_1 = require("../../orchestrator-core/src/lib/wallet-state");
+const acp_1 = require("../../orchestrator-core/src/lib/acp");
+// ── Config ────────────────────────────────────────────────────────────────────
+const _rawOllamaHost = process.env.OLLAMA_HOST || 'http://127.0.0.1:11434'; // SEC1: loopback-only default
+const OLLAMA_BASE = _rawOllamaHost.startsWith('http') ? _rawOllamaHost : `http://${_rawOllamaHost}`;
+const CLAWROUTER_GATEWAY = process.env.CLAWROUTER_GATEWAY_URL || 'http://127.0.0.1:18789/v1'; // SEC3: loopback-only default
+const OLLAMA_TIMEOUT_MS = 480_000; // 8 min for local models — qwen3:14b needs time for large file generation
+const CLOUD_TIMEOUT_MS = 300_000; // 5 min for cloud API calls
+const QCG_TOKEN_THRESHOLD = 5000; // QCG pre-compression trigger
+// ── x402 Payment Config (USDC on Base mainnet) ──────────────────────────────
+const X402_WALLET_KEY = process.env.X402_WALLET_KEY || '';
+const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const BASE_CHAIN_ID = 8453;
+const USDC_DOMAIN = {
+    name: 'USD Coin',
+    version: '2',
+    chainId: BASE_CHAIN_ID,
+    verifyingContract: USDC_ADDRESS,
+};
+// ── Tier Models ───────────────────────────────────────────────────────────────
+const TIER_MODELS = {
+    // Text tiers
+    T0_NANO: 'qwen3:0.6b',
+    T1_LOCAL: 'qwen3:4b',
+    T2_POWER: 'qwen3:14b',
+    T2_5_THINK: 'qwen3:14b', // T2.5-LOCAL: thinking mode (TICKET-007-CLAWROUTER-THINK)
+    T2_5_EXEC: 'google/gemini-2.5-flash', // via OpenClaw gateway
+    T2_5_MIMO: 'mimo-v2-pro', // A/B test candidate (CR-AMD-001)
+    T3_APEX: 'anthropic/claude-sonnet-4-20250514', // via OpenClaw gateway
+};
+// T2.5-LOCAL: thinking mode config (TICKET-007-CLAWROUTER-THINK)
+const THINKING_MODE_ENABLED = process.env.THINKING_MODE_LOCAL_ENABLED === 'true';
+const THINKING_MODE_THRESHOLD = parseFloat(process.env.THINKING_MODE_THRESHOLD || '0.85');
+// Markers that indicate the model is uncertain — trigger escalation to T3 APEX
+const UNCERTAINTY_MARKERS = [
+    /\b(I am not sure|I cannot determine|I don't have enough|requires human judgment|uncertain|ambiguous)\b/i,
+    /\b(cannot confidently|low confidence|unclear|insufficient context)\b/i,
+];
+const costLog = [];
+const MAX_COST_LOG = 5000;
+function getCostLog() { return costLog; }
+function getDailyCostDigest() {
+    const today = new Date().toISOString().slice(0, 10);
+    const todayEntries = costLog.filter(e => e.timestamp.startsWith(today));
+    const by_tier = {};
+    const by_agent = {};
+    let total_usd = 0;
+    let tokens_saved = 0;
+    for (const e of todayEntries) {
+        total_usd += e.cost_usd;
+        tokens_saved += e.tokens_saved;
+        by_tier[e.tier] = (by_tier[e.tier] || 0) + e.cost_usd;
+        by_agent[e.agent_id] = (by_agent[e.agent_id] || 0) + e.cost_usd;
+    }
+    return { total_usd, by_tier, by_agent, tokens_saved_by_qcg: tokens_saved, call_count: todayEntries.length };
+}
+// ── Routing Matrix ────────────────────────────────────────────────────────────
+function resolveTextTier(req) {
+    // Constitutional flag: T2.5-LOCAL (thinking mode) when enabled and not apex; T3 APEX otherwise
+    if (req.constitutional_flag) {
+        if (THINKING_MODE_ENABLED && req.complexity !== 'apex') {
+            return { tier: 'T2.5-LOCAL', model: TIER_MODELS.T2_5_THINK, local: true };
+        }
+        return { tier: 'T3', model: TIER_MODELS.T3_APEX, local: false };
+    }
+    switch (req.complexity) {
+        case 'nano':
+            return { tier: 'T0', model: TIER_MODELS.T0_NANO, local: true };
+        case 'local':
+            return { tier: 'T1', model: TIER_MODELS.T1_LOCAL, local: true };
+        case 'exec': {
+            // CR-AMD-001 A/B test: 50/50 MiMo-V2-Pro vs Gemini Flash when active
+            const abActive = process.env.MIMO_AB_TEST_ACTIVE === 'true';
+            const useMimo = abActive && Math.random() < 0.5;
+            const model = useMimo ? TIER_MODELS.T2_5_MIMO : TIER_MODELS.T2_5_EXEC;
+            if (abActive)
+                logABTest(req.agent_id || 'unknown', model);
+            return { tier: 'T2.5', model, local: false };
+        }
+        case 'apex':
+            return { tier: 'T3', model: TIER_MODELS.T3_APEX, local: false };
+        case 'power':
+        default:
+            // Default unspecified complexity → T2 POWER (local)
+            return { tier: 'T2', model: TIER_MODELS.T2_POWER, local: true };
+    }
+}
+// CR-AMD-001: A/B test logging for MiMo-V2-Pro vs Gemini Flash
+const AB_LOG_PATH = require('path').join(__dirname, '../../logs/clawrouter/ab-test-mimo.jsonl');
+function logABTest(agentId, model) {
+    try {
+        const entry = JSON.stringify({ timestamp: new Date().toISOString(), agent_id: agentId, model, tier: 'T2.5' });
+        fs.appendFileSync(AB_LOG_PATH, entry + '\n');
+    }
+    catch { /* non-blocking */ }
+}
+function resolveCreativeTier(req) {
+    // Creative routing — Phase 2A. Stubs for now, returns model_unavailable for uninstalled.
+    switch (req.modality) {
+        case 'image':
+            return req.quality === 'high'
+                ? { tier: 'C2', model: 'flux-dev', local: false }
+                : { tier: 'C1', model: 'flux-schnell', local: true };
+        case 'video':
+            return { tier: 'C3', model: 'wan2.1', local: true };
+        case 'speech':
+            if (req.quality === 'emotional')
+                return { tier: 'C4', model: 'mimo-v2-tts', local: false };
+            return req.quality === 'high'
+                ? { tier: 'C4', model: 'elevenlabs', local: false }
+                : { tier: 'C4', model: 'kokoro', local: true };
+        case 'music':
+            return { tier: 'C5', model: 'musicgen', local: true };
+        case 'transcription':
+            return { tier: 'C6', model: 'whisper', local: true };
+        case 'visual_understanding':
+            return { tier: 'C7', model: 'qwen2.5-vl', local: true };
+        default:
+            return { tier: 'C1', model: 'flux-schnell', local: true };
+    }
+}
+// ── HTTP Helpers ───────────────────────────────────────────────────────────────
+function httpRequest(url, body, method = 'POST', extraHeaders = {}, timeoutMs = CLOUD_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const isHttps = parsed.protocol === 'https:';
+        const lib = isHttps ? https : http;
+        const req = lib.request({
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttps ? 443 : 80),
+            path: parsed.pathname + parsed.search,
+            method,
+            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body), ...extraHeaders },
+        }, (res) => {
+            let data = '';
+            res.on('data', (c) => (data += c));
+            res.on('end', () => resolve({ status: res.statusCode || 0, data, headers: res.headers }));
+        });
+        req.on('error', reject);
+        req.setTimeout(timeoutMs, () => { req.destroy(); reject(new Error(`ClawRouter timeout (${timeoutMs / 1000}s)`)); });
+        req.write(body);
+        req.end();
+    });
+}
+// ── Ollama Direct Call (Local Tiers) ──────────────────────────────────────────
+async function callOllamaLocal(model, prompt, systemPrompt, maxTokens = 4096) {
+    const body = JSON.stringify({
+        model,
+        prompt,
+        system: systemPrompt,
+        stream: false,
+        think: false, // Disable qwen3 thinking mode — outputs to separate key, breaks JSON parsing
+        options: { num_predict: maxTokens, temperature: 0.1 },
+    });
+    const res = await httpRequest(`${OLLAMA_BASE}/api/generate`, body, 'POST', {}, OLLAMA_TIMEOUT_MS);
+    if (res.status !== 200)
+        throw new Error(`Ollama ${model} returned ${res.status}: ${res.data.slice(0, 300)}`);
+    const json = JSON.parse(res.data);
+    // Strip any residual <think>...</think> tags from qwen3 response
+    let content = json.response || '';
+    content = content.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+    return {
+        content,
+        input_tokens: json.prompt_eval_count || 0,
+        output_tokens: json.eval_count || 0,
+    };
+}
+// ── Ollama Thinking Mode Call (T2.5-LOCAL, TICKET-007-CLAWROUTER-THINK) ─────────
+async function callOllamaThink(model, prompt, systemPrompt, maxTokens = 4096) {
+    const body = JSON.stringify({
+        model,
+        prompt,
+        system: systemPrompt,
+        stream: false,
+        think: true, // Enable qwen3 thinking mode
+        options: { num_predict: maxTokens, temperature: 0.1 },
+    });
+    const res = await httpRequest(`${OLLAMA_BASE}/api/generate`, body, 'POST', {}, OLLAMA_TIMEOUT_MS);
+    if (res.status !== 200)
+        throw new Error(`Ollama think ${model} returned ${res.status}: ${res.data.slice(0, 300)}`);
+    const json = JSON.parse(res.data);
+    // Ollama returns thinking content in json.thinking (separate from json.response)
+    const thinking = json.thinking || '';
+    let content = json.response || '';
+    // Also strip any inline <think> tags in case model mixes formats
+    content = content.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+    return {
+        content, thinking,
+        input_tokens: json.prompt_eval_count || 0,
+        output_tokens: json.eval_count || 0,
+    };
+}
+// ── Anthropic Direct API Fallback (when OpenClaw gateway is unavailable) ────────
+/**
+ * Call Anthropic API directly — fallback when OpenClaw gateway returns non-200/non-402.
+ * Uses ANTHROPIC_API_KEY from .env. Only called for anthropic/* models.
+ * Anthropic Messages API: https://docs.anthropic.com/en/api/messages
+ */
+async function callAnthropicDirect(model, messages, maxTokens = 4096) {
+    const apiKey = process.env.ANTHROPIC_API_KEY || '';
+    if (!apiKey)
+        throw new Error('ANTHROPIC_API_KEY not set — cannot call Anthropic API directly');
+    // Anthropic Messages API: system message is top-level, not in messages array
+    const systemMsg = messages.find(m => m.role === 'system')?.content;
+    const userMsgs = messages.filter(m => m.role !== 'system');
+    const bodyObj = {
+        model,
+        max_tokens: maxTokens,
+        messages: userMsgs,
+    };
+    if (systemMsg)
+        bodyObj.system = systemMsg;
+    const body = JSON.stringify(bodyObj);
+    const res = await httpRequest('https://api.anthropic.com/v1/messages', body, 'POST', {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+    }, CLOUD_TIMEOUT_MS);
+    if (res.status !== 200) {
+        throw new Error(`Anthropic direct API returned ${res.status}: ${res.data.slice(0, 300)}`);
+    }
+    const json = JSON.parse(res.data);
+    return {
+        content: json.content?.[0]?.text || '',
+        input_tokens: json.usage?.input_tokens || 0,
+        output_tokens: json.usage?.output_tokens || 0,
+        cost_usd: 0, // billing handled outside (no gateway metering on direct path)
+    };
+}
+// ── x402 Payment Signing (EIP-3009 TransferWithAuthorization) ─────────────────
+/**
+ * Sign an x402 payment for a cloud LLM call.
+ * Uses viem to sign EIP-3009 TransferWithAuthorization on USDC (Base mainnet).
+ * Returns base64-encoded X-PAYMENT header value.
+ */
+async function signX402Payment(payTo, amountAtomic) {
+    if (!X402_WALLET_KEY) {
+        throw new Error('x402: gateway requires payment but X402_WALLET_KEY not set in .env');
+    }
+    // Dynamic imports — viem is already a project dependency
+    const { privateKeyToAccount } = require('viem/accounts');
+    const { createWalletClient, http: viemHttp } = require('viem');
+    const { base } = require('viem/chains');
+    const account = privateKeyToAccount(X402_WALLET_KEY);
+    const walletClient = createWalletClient({
+        account,
+        chain: base,
+        transport: viemHttp('https://mainnet.base.org'),
+    });
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    const validBefore = now + BigInt(3600); // 1 hour validity
+    const nonce = `0x${crypto.randomBytes(32).toString('hex')}`;
+    const signature = await walletClient.signTypedData({
+        domain: USDC_DOMAIN,
+        types: {
+            TransferWithAuthorization: [
+                { name: 'from', type: 'address' },
+                { name: 'to', type: 'address' },
+                { name: 'value', type: 'uint256' },
+                { name: 'validAfter', type: 'uint256' },
+                { name: 'validBefore', type: 'uint256' },
+                { name: 'nonce', type: 'bytes32' },
+            ],
+        },
+        primaryType: 'TransferWithAuthorization',
+        message: {
+            from: account.address,
+            to: payTo,
+            value: BigInt(amountAtomic),
+            validAfter: now,
+            validBefore,
+            nonce,
+        },
+    });
+    const paymentPayload = {
+        x402Version: 1,
+        scheme: 'exact',
+        network: 'base',
+        payload: {
+            signature,
+            authorization: {
+                from: account.address,
+                to: payTo,
+                value: String(amountAtomic),
+                validAfter: String(now),
+                validBefore: String(validBefore),
+                nonce,
+            },
+        },
+    };
+    const xPayment = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
+    const costUsd = amountAtomic / 1_000_000; // atomic USDC (6 decimals) → USD
+    return { xPayment, costUsd };
+}
+// ── OpenClaw Gateway Call (Cloud Tiers — x402 payment flow) ──────────────────
+/**
+ * Call cloud LLM via OpenClaw gateway with x402 payment signing.
+ *
+ * Flow:
+ *   1. POST /chat/completions → may return 200 (free) or 402 (payment required)
+ *   2. If 402: parse payment requirements (amount, payTo)
+ *   3. Sign EIP-3009 TransferWithAuthorization with CEO wallet
+ *   4. Retry POST with X-PAYMENT header (base64-encoded signed proof)
+ *   5. Return response + actual cost in USD
+ */
+// ── x402 on-chain metering (Option B) ────────────────────────────────────────
+//
+// When X402_METER_ENABLED=true, every cloud-tier call broadcasts a small
+// EIP-3009 USDC transfer from the x402 signer (X402_WALLET_KEY) to a
+// metering wallet. Makes ClawRouter's spend visible on Basescan in real
+// time — one tx per cloud call. Serialized to avoid nonce conflicts.
+// Fire-and-forget from the caller's perspective.
+const METER_RECIPIENT = (process.env.X402_METER_RECIPIENT || '0x260E18591371A6E7A3da0AC5f9d47Ff06508B61F');
+const METER_AMOUNT_ATOMIC = parseInt(process.env.X402_METER_AMOUNT_ATOMIC || '1000', 10); // default 0.001 USDC
+const METER_MIN_INTERVAL_MS = parseInt(process.env.X402_METER_MIN_INTERVAL_MS || '2000', 10);
+const USDC_CONTRACT = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+let _meterQueue = Promise.resolve();
+let _meterLastAt = 0;
+let _meterStats = { settled: 0, failed: 0, totalAtomicSettled: 0 };
+async function meterX402Settle(costUsd, tier, model, agentId) {
+    // Chain on the previous settle to serialize broadcasts (avoid nonce races).
+    _meterQueue = _meterQueue.then(async () => {
+        try {
+            if (!X402_WALLET_KEY)
+                return;
+            // Throttle so we don't flood the chain
+            const sinceLast = Date.now() - _meterLastAt;
+            if (sinceLast < METER_MIN_INTERVAL_MS) {
+                await new Promise(r => setTimeout(r, METER_MIN_INTERVAL_MS - sinceLast));
+            }
+            // Pick amount: floor METER_AMOUNT_ATOMIC, scale up if real cost was bigger,
+            // hard cap so demo doesn't accidentally burn through the wallet.
+            const scaled = Math.max(METER_AMOUNT_ATOMIC, Math.floor(costUsd * 1_000_000));
+            const amount = BigInt(Math.min(scaled, 5000)); // hard cap 0.005 USDC per call
+            const { privateKeyToAccount } = require('viem/accounts');
+            const { createWalletClient, createPublicClient, http: viemHttp, parseAbi } = require('viem');
+            const { base } = require('viem/chains');
+            const account = privateKeyToAccount(X402_WALLET_KEY);
+            const wallet = createWalletClient({ account, chain: base, transport: viemHttp('https://mainnet.base.org') });
+            const pub = createPublicClient({ chain: base, transport: viemHttp('https://mainnet.base.org') });
+            // Build EIP-3009 TransferWithAuthorization, then submit via
+            // USDC.transferWithAuthorization (this IS the x402 settle path —
+            // identical to what a facilitator would do, just self-relayed).
+            const now = BigInt(Math.floor(Date.now() / 1000));
+            const message = {
+                from: account.address,
+                to: METER_RECIPIENT,
+                value: amount,
+                validAfter: now - 60n,
+                validBefore: now + 3600n,
+                nonce: (`0x${crypto.randomBytes(32).toString('hex')}`),
+            };
+            const signature = await account.signTypedData({
+                domain: USDC_DOMAIN,
+                types: {
+                    TransferWithAuthorization: [
+                        { name: 'from', type: 'address' },
+                        { name: 'to', type: 'address' },
+                        { name: 'value', type: 'uint256' },
+                        { name: 'validAfter', type: 'uint256' },
+                        { name: 'validBefore', type: 'uint256' },
+                        { name: 'nonce', type: 'bytes32' },
+                    ],
+                },
+                primaryType: 'TransferWithAuthorization',
+                message,
+            });
+            const sig = signature.slice(2);
+            const r = `0x${sig.slice(0, 64)}`;
+            const s = `0x${sig.slice(64, 128)}`;
+            const v = parseInt(sig.slice(128, 130), 16);
+            const abi = parseAbi([
+                'function transferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce,uint8 v,bytes32 r,bytes32 s)',
+            ]);
+            const hash = await wallet.writeContract({
+                address: USDC_CONTRACT,
+                abi,
+                functionName: 'transferWithAuthorization',
+                args: [message.from, message.to, message.value, message.validAfter, message.validBefore, message.nonce, v, r, s],
+            });
+            _meterLastAt = Date.now();
+            _meterStats.settled += 1;
+            _meterStats.totalAtomicSettled += Number(amount);
+            // Append to a meter log alongside ceo-wallet ledger
+            try {
+                const dir = path.join(process.cwd(), 'logs', 'clawrouter');
+                if (!fs.existsSync(dir))
+                    fs.mkdirSync(dir, { recursive: true });
+                const file = path.join(dir, `x402-meter-${new Date().toISOString().slice(0, 10)}.jsonl`);
+                fs.appendFileSync(file, JSON.stringify({
+                    ts: new Date().toISOString(),
+                    tx_hash: hash,
+                    basescan: `https://basescan.org/tx/${hash}`,
+                    from: message.from, to: message.to,
+                    amount_atomic: Number(amount), amount_usdc: Number(amount) / 1e6,
+                    tier, model, agent_id: agentId, cost_usd: costUsd,
+                }) + '\n');
+            }
+            catch { /* non-fatal */ }
+            console.log(`[x402-meter] ${hash} · ${Number(amount) / 1e6} USDC → ${METER_RECIPIENT} · tier=${tier}`);
+        }
+        catch (e) {
+            _meterStats.failed += 1;
+            console.warn(`[x402-meter] settle failed: ${e?.message || e}`);
+        }
+    });
+}
+function getMeterStats() { return { ..._meterStats, recipient: METER_RECIPIENT, enabled: process.env.X402_METER_ENABLED === 'true' }; }
+// Founder directive 2026-05-26 (spec-pure): three-layer fallback so the
+// swarm never halts on external billing failures. Spec order:
+//   OpenClaw upstream → local fallback → direct Anthropic
+// Rationale: local is free & sovereign, so prefer it on OpenClaw failure.
+// Direct Anthropic is the LAST resort because it burns the founder's
+// personal balance (which is the only thing keeping the lights on when
+// OpenClaw's upstream credit is drained). Returns null only if every
+// layer fails, letting the caller throw the original error.
+async function tryLocalThenDirect(originalModel, messages, maxTokens, reason) {
+    // Layer 1: local sovereign via Ollama. DeepSeek-R1 first (best for code),
+    // Qwen3 14B as secondary, Qwen3 32B as tertiary. Stitch the messages
+    // into a single prompt the local helper expects.
+    const sysMsg = messages.find(m => m.role === 'system')?.content;
+    const userPrompt = messages.filter(m => m.role !== 'system').map(m => m.content).join('\n');
+    const LOCAL_ORDER = ['deepseek-r1:14b', 'qwen3:14b', 'qwen3:32b'];
+    for (const localModel of LOCAL_ORDER) {
+        try {
+            console.warn(`[ClawRouter] ${reason} — falling back to local ${localModel}`);
+            const r = await callOllamaLocal(localModel, userPrompt, sysMsg, maxTokens);
+            return { content: r.content, input_tokens: r.input_tokens, output_tokens: r.output_tokens, cost_usd: 0 };
+        }
+        catch (e) {
+            console.warn(`[ClawRouter] local ${localModel} failed: ${(e?.message || '').slice(0, 150)}`);
+        }
+    }
+    // Layer 2: direct Anthropic (last resort — only for Claude-family models,
+    // costs founder's personal balance).
+    const anthropicKey = process.env.ANTHROPIC_API_KEY || '';
+    if (anthropicKey) {
+        const directModel = originalModel.startsWith('anthropic/')
+            ? originalModel.replace('anthropic/', '')
+            : (originalModel === 'openclaw/main' || originalModel === 'openclaw')
+                ? 'claude-sonnet-4-6'
+                : originalModel;
+        if (/^claude[-/]/i.test(directModel) || directModel.startsWith('claude-')) {
+            try {
+                console.warn(`[ClawRouter] ${reason} — last-resort direct Anthropic API (${directModel})`);
+                return await callAnthropicDirect(directModel, messages, maxTokens);
+            }
+            catch (e) {
+                console.warn(`[ClawRouter] direct Anthropic also failed: ${(e?.message || '').slice(0, 200)}`);
+            }
+        }
+    }
+    return null;
+}
+async function callCloudGateway(model, messages, maxTokens = 4096) {
+    const chatUrl = `${CLAWROUTER_GATEWAY}/chat/completions`;
+    // Sprint-1556 fix: OpenClaw v2026.5.12 only accepts the `openclaw/<agentId>`
+    // model format. Legacy provider/model literals (anthropic/claude-X,
+    // deepseek/deepseek-chat, google/gemini-X, etc.) return 400 with "Invalid
+    // model" which the orchestrator wraps as a stub and commits — exactly the
+    // failure mode that produced the 2026-05-17→18 stub cascade. Translate
+    // anything that isn't already `openclaw/*` to `openclaw/main` so it routes
+    // through the main agent's configured fallback chain. The ORIGINAL model is
+    // preserved as `originalModel` so the Anthropic-direct fallback below still
+    // triggers correctly when the gateway misbehaves.
+    const originalModel = model;
+    const gatewayModel = (model.startsWith('openclaw/') || model === 'openclaw') ? model : 'openclaw/main';
+    const body = JSON.stringify({ model: gatewayModel, messages, max_tokens: maxTokens });
+    // Step 1: Initial request (may return 402 requiring x402 payment)
+    let res = await httpRequest(chatUrl, body);
+    let paidAmountUsd = 0;
+    // Step 2: If 402, sign x402 payment and retry
+    if (res.status === 402) {
+        if (!X402_WALLET_KEY) {
+            throw new Error(`ClawRouter gateway returned 402 (payment required) but X402_WALLET_KEY not set. ` +
+                `Fund the CEO wallet and add the private key to .env.`);
+        }
+        try {
+            const paymentReq = JSON.parse(res.data);
+            // The gateway uses HTTP 402 for two distinct conditions that must NOT
+            // be conflated:
+            //   (1) x402 protocol payment required — body has accepts.payTo+amount
+            //   (2) upstream provider credit exhausted (Anthropic/OpenAI) bubbled
+            //       through with their original error in body.error
+            // Detect (2) first so the orchestrator's credit-exhaustion fallback can
+            // fire on the actual upstream message (per scripts/orchestrate-agents-v2.ts
+            // isCreditExhaustion matcher: 'credit balance is too low', 'insufficient_quota', etc).
+            const upstreamErr = paymentReq.error;
+            if (upstreamErr) {
+                const upstreamMsg = String(upstreamErr.message || '');
+                const upstreamType = String(upstreamErr.type || '');
+                const looksLikeCreditExhaustion = (upstreamType === 'insufficient_quota' ||
+                    upstreamType === 'insufficient_credit' ||
+                    /credit balance is too low|insufficient (?:quota|credit|balance)|billing[_ ]hard[_ ]limit|quota exceeded/i.test(upstreamMsg));
+                if (looksLikeCreditExhaustion) {
+                    // Founder directive 2026-05-26 (spec-pure): three-layer fallback.
+                    // Order: OpenClaw upstream → local (free, sovereign) → direct
+                    // Anthropic (last-resort, burns founder balance). See
+                    // tryLocalThenDirect() for rationale.
+                    const direct = await tryLocalThenDirect(originalModel, messages, maxTokens, upstreamMsg || upstreamType);
+                    if (direct)
+                        return direct;
+                    throw new Error(`upstream provider credit exhausted: ${upstreamMsg || upstreamType}`);
+                }
+            }
+            // OpenClaw 402 format: { accepts: { amount, payTo, ... } } or flat { amount, payTo }
+            const accepts = paymentReq.accepts || paymentReq;
+            const amountAtomic = parseInt(accepts.maxAmountRequired || accepts.amount || '10000', 10);
+            const payTo = accepts.payTo || '';
+            if (!payTo)
+                throw new Error('x402: gateway returned 402 but no payTo address in response');
+            const { xPayment, costUsd } = await signX402Payment(payTo, amountAtomic);
+            paidAmountUsd = costUsd;
+            // Step 3: Retry with signed payment
+            res = await httpRequest(chatUrl, body, 'POST', { 'X-PAYMENT': xPayment });
+        }
+        catch (e) {
+            if (e.message?.includes('x402'))
+                throw e;
+            throw new Error(`x402 payment signing failed: ${e.message}`);
+        }
+    }
+    if (res.status !== 200) {
+        // Log response body on 4xx/5xx so the gateway's actual error is recoverable
+        // for future debugging — losing the message body was hiding root causes.
+        const bodyExcerpt = (res.data || '').slice(0, 500).replace(/\s+/g, ' ');
+        console.warn(`[ClawRouter] gateway ${res.status} for ${originalModel} (sent as ${gatewayModel}) — body: ${bodyExcerpt}`);
+        // Spec-pure three-layer fallback: local DeepSeek/Qwen first (free,
+        // sovereign), direct Anthropic last-resort (Claude family only, burns
+        // founder balance). Note: tryLocalThenDirect checks originalModel, not
+        // model — model has been rewritten to gatewayModel (always
+        // openclaw/main after the sprint-1556 translation).
+        const direct = await tryLocalThenDirect(originalModel, messages, maxTokens, `gateway ${res.status}`);
+        if (direct)
+            return direct;
+        throw new Error(`ClawRouter gateway returned ${res.status}: ${bodyExcerpt}`);
+    }
+    const json = JSON.parse(res.data);
+    // Cost: prefer actual payment amount, fall back to response header
+    const costHeader = res.headers['x-payment-amount'];
+    const cost_usd = paidAmountUsd > 0
+        ? paidAmountUsd
+        : (costHeader ? Number(costHeader) / 1_000_000 : 0);
+    return {
+        content: json.choices?.[0]?.message?.content || '',
+        input_tokens: json.usage?.prompt_tokens || 0,
+        output_tokens: json.usage?.completion_tokens || 0,
+        cost_usd,
+    };
+}
+// ── QCG Stub (AMD-12 — to be wired with full QCG pre-flight) ─────────────────
+function applyQCGCompression(payload, contextTokens) {
+    // TODO: Wire full QCG pre-flight compression here
+    // For now: pass-through, no compression applied
+    // When implemented: read data sources → compress → return compressed brief
+    return { compressed: false, tokensSaved: 0, payload };
+}
+// ── MAIN ENTRY POINT ──────────────────────────────────────────────────────────
+/**
+ * Route an LLM call through ClawRouter v2.0.
+ * This is the ONLY function any agent should call for LLM inference.
+ *
+ * @example
+ *   const result = await routeCall({
+ *     task_type: 'code_review',
+ *     tier_class: 'text',
+ *     complexity: 'power',
+ *     context_tokens: 3000,
+ *     constitutional_flag: false,
+ *     agent_id: 'cto-agent',
+ *     payload: { system: '...', prompt: '...' }
+ *   });
+ */
+async function routeCall(req) {
+    const timestamp = new Date().toISOString();
+    // 1. Resolve tier & model
+    let route = req.tier_class === 'creative'
+        ? resolveCreativeTier(req)
+        : resolveTextTier(req);
+    // 1a. Per-agent spend gate (TICKET-215 Wave C-b) — only agents declared with the
+    // `llm_call_cloud` ACP capability may incur paid cloud routing. This is how spend
+    // is scoped to authorized Kognai agents/swarm; everyone else falls back to local.
+    // FAIL-OPEN for UNREGISTERED agents (getAgent falsy) so unknown callers — incl. the
+    // orchestrator itself — never regress. Scoped to text tiers (clean local fallback).
+    // Kill switch / rollout via X402_SPEND_GATE: off | shadow | enforce (default shadow
+    // = log only; flip to `enforce` to actually downgrade after reviewing shadow logs).
+    if (!route.local && req.tier_class === 'text') {
+        const gateMode = (process.env.X402_SPEND_GATE || 'shadow').toLowerCase();
+        if (gateMode !== 'off' && (0, acp_1.getAgent)(req.agent_id) && !(0, acp_1.checkCapability)(req.agent_id, 'llm_call_cloud').allowed) {
+            console.warn(`[ClawRouter] spend-gate(${gateMode}): agent "${req.agent_id}" lacks llm_call_cloud — ` +
+                `${route.tier} ${gateMode === 'enforce' ? 'downgraded → T2 local' : 'WOULD be downgraded'}`);
+            if (gateMode === 'enforce') {
+                route = { tier: 'T2', model: TIER_MODELS.T2_POWER, local: true };
+            }
+        }
+    }
+    // 1b. CEO Wallet freeze guard — block cloud calls when budget exhausted (§17.5)
+    if (!route.local) {
+        const wallet = (0, wallet_state_1.getWalletState)();
+        if (wallet.isFrozen) {
+            throw new Error(`ClawRouter FROZEN: CEO wallet at ${wallet.burnPct.toFixed(1)}% ` +
+                `($${wallet.spentThisMonth.toFixed(2)}/$${wallet.monthlyBudget}). ` +
+                `Cloud tier ${route.tier} blocked. Fund wallet or use local tiers.`);
+        }
+    }
+    // 2. QCG pre-compression for cloud tiers
+    let qcgResult = { compressed: false, tokensSaved: 0, payload: req.payload };
+    if (!route.local && req.context_tokens > QCG_TOKEN_THRESHOLD) {
+        qcgResult = applyQCGCompression(req.payload, req.context_tokens);
+    }
+    // 3. Build messages array
+    const payload = qcgResult.payload;
+    let messages = [];
+    if (payload.messages) {
+        messages = payload.messages;
+    }
+    else {
+        if (payload.system)
+            messages.push({ role: 'system', content: payload.system });
+        if (payload.prompt)
+            messages.push({ role: 'user', content: payload.prompt });
+    }
+    const prompt = messages.filter(m => m.role === 'user').map(m => m.content).join('\n');
+    const systemPrompt = messages.find(m => m.role === 'system')?.content;
+    // 4. Execute call — local or cloud
+    let content = '';
+    let input_tokens = 0;
+    let output_tokens = 0;
+    let cost_usd = 0;
+    if (route.tier === 'T2.5-LOCAL') {
+        // T2.5-LOCAL: thinking mode call with confidence-based escalation
+        const thinkResult = await callOllamaThink(route.model, prompt, systemPrompt, payload.max_tokens);
+        content = thinkResult.content;
+        input_tokens = thinkResult.input_tokens;
+        output_tokens = thinkResult.output_tokens;
+        cost_usd = 0;
+        // Confidence-based escalation: if response contains uncertainty markers, escalate to T3 APEX
+        const isUncertain = UNCERTAINTY_MARKERS.some(rx => rx.test(thinkResult.content));
+        if (isUncertain) {
+            console.warn(`[ClawRouter] T2.5-LOCAL confidence below threshold — escalating to T3 APEX`);
+            const apexResult = await callCloudGateway(TIER_MODELS.T3_APEX, messages, payload.max_tokens || 4096);
+            content = apexResult.content;
+            input_tokens += apexResult.input_tokens;
+            output_tokens += apexResult.output_tokens;
+            cost_usd = apexResult.cost_usd;
+            if (cost_usd > 0)
+                (0, wallet_state_1.recordSpend)(cost_usd);
+            route = { tier: 'T3', model: TIER_MODELS.T3_APEX, local: false };
+        }
+    }
+    else if (route.local) {
+        const result = await callOllamaLocal(route.model, prompt, systemPrompt, payload.max_tokens);
+        content = result.content;
+        input_tokens = result.input_tokens;
+        output_tokens = result.output_tokens;
+        cost_usd = 0; // local = free
+    }
+    else {
+        const result = await callCloudGateway(route.model, messages, payload.max_tokens || 4096);
+        content = result.content;
+        input_tokens = result.input_tokens;
+        output_tokens = result.output_tokens;
+        cost_usd = result.cost_usd;
+    }
+    // 4b. CEO Wallet billing — record every cloud spend (§17.5)
+    if (cost_usd > 0) {
+        (0, wallet_state_1.recordSpend)(cost_usd);
+    }
+    // 4c. x402 on-chain metering (Option B): when enabled, every cloud-tier
+    // call broadcasts a small EIP-3009 USDC transfer from the x402 signer
+    // wallet to the configured meter recipient. Makes ClawRouter's accounting
+    // visible on Basescan in real time. Fire-and-forget — won't block the
+    // LLM response. Local-tier calls are NOT metered (they're $0 anyway).
+    if (!route.local && process.env.X402_METER_ENABLED === 'true') {
+        void meterX402Settle(cost_usd, route.tier, route.model, req.agent_id);
+    }
+    // 5. Log
+    const logEntry = {
+        timestamp, agent_id: req.agent_id, task_type: req.task_type,
+        tier: route.tier, model: route.model, local: route.local,
+        cost_usd, input_tokens, output_tokens,
+        qcg_compressed: qcgResult.compressed, tokens_saved: qcgResult.tokensSaved,
+    };
+    costLog.push(logEntry);
+    if (costLog.length > MAX_COST_LOG)
+        costLog.shift();
+    // 6. Append to daily cost log file
+    try {
+        const logDir = path.join(process.cwd(), 'logs', 'clawrouter');
+        if (!fs.existsSync(logDir))
+            fs.mkdirSync(logDir, { recursive: true });
+        const logFile = path.join(logDir, `${timestamp.slice(0, 10)}.jsonl`);
+        fs.appendFileSync(logFile, JSON.stringify(logEntry) + '\n');
+    }
+    catch { /* non-critical */ }
+    return {
+        content, model: route.model, tier: route.tier, local: route.local,
+        cost_usd, input_tokens, output_tokens,
+        qcg_compressed: qcgResult.compressed, tokens_saved_by_qcg: qcgResult.tokensSaved,
+        agent_id: req.agent_id, task_type: req.task_type, timestamp,
+    };
+}
+// ── BACKWARD-COMPATIBLE WRAPPER ───────────────────────────────────────────────
+// Drop-in replacement for the old callClawRouter / callLLM pattern
+async function callLLM(prompt, opts = {}) {
+    const result = await routeCall({
+        task_type: opts.taskType || 'generic',
+        tier_class: 'text',
+        complexity: opts.complexity || 'power',
+        context_tokens: (prompt.length + (opts.systemPrompt?.length || 0)) / 4,
+        constitutional_flag: opts.constitutional || false,
+        agent_id: opts.agentId || 'unknown',
+        payload: {
+            system: opts.systemPrompt,
+            prompt,
+            max_tokens: opts.maxTokens || 4096,
+        },
+    });
+    return { content: result.content, model: result.model, tier: result.tier, cost_usd: result.cost_usd };
+}
+// ── HEALTH CHECK ──────────────────────────────────────────────────────────────
+async function clawRouterHealthCheck() {
+    let ollama = false;
+    let gateway = false;
+    let models = [];
+    // Check Ollama
+    try {
+        const res = await httpRequest(`${OLLAMA_BASE}/api/tags`, '{}', 'GET', {}, 3000);
+        if (res.status === 200) {
+            ollama = true;
+            const json = JSON.parse(res.data);
+            models = (json.models || []).map((m) => m.name || m.model);
+        }
+    }
+    catch { /* not available */ }
+    // Check OpenClaw gateway
+    try {
+        const res = await httpRequest(`${CLAWROUTER_GATEWAY}/models`, '{}', 'GET', {}, 3000);
+        gateway = res.status === 200;
+    }
+    catch { /* not available */ }
+    return { ollama, gateway, models };
+}