@rungate/llmrouter 0.1.0

package/dist/src/payment/wallet.js

@@ -0,0 +1,96 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createPublicClient, formatEther, formatUnits, http } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { resolveChain, resolveConfiguredNetwork, usdcAddressForNetwork } from './network.js';
+const WALLET_DIR = join(homedir(), '.openclaw', 'llmrouter');
+const WALLET_FILE = join(WALLET_DIR, 'wallet.key');
+const ERC20_ABI = [
+    {
+        type: 'function',
+        name: 'balanceOf',
+        stateMutability: 'view',
+        inputs: [{ name: 'account', type: 'address' }],
+        outputs: [{ name: 'balance', type: 'uint256' }],
+    },
+];
+// Make sure the wallet directory exists before we read or write the key file.
+function ensureWalletDir() {
+    mkdirSync(dirname(WALLET_FILE), { recursive: true });
+}
+// Expose the wallet file path for status commands and docs.
+export function walletFilePath() {
+    return WALLET_FILE;
+}
+// Resolve the wallet in priority order: env override, saved key, then auto-generate.
+export function resolveOrGenerateWalletKey(env = process.env) {
+    const envKey = env.LLM_ROUTER_WALLET_KEY;
+    if (typeof envKey === 'string' && envKey.startsWith('0x') && envKey.length === 66) {
+        const account = privateKeyToAccount(envKey);
+        return {
+            key: envKey,
+            info: {
+                address: account.address,
+                walletFile: WALLET_FILE,
+                network: resolveConfiguredNetwork(env.X402_NETWORK),
+                source: 'env',
+            },
+        };
+    }
+    ensureWalletDir();
+    try {
+        const savedKey = readFileSync(WALLET_FILE, 'utf8').trim();
+        if (savedKey.startsWith('0x') && savedKey.length === 66) {
+            const account = privateKeyToAccount(savedKey);
+            return {
+                key: savedKey,
+                info: {
+                    address: account.address,
+                    walletFile: WALLET_FILE,
+                    network: resolveConfiguredNetwork(env.X402_NETWORK),
+                    source: 'saved',
+                },
+            };
+        }
+    }
+    catch {
+        // ignore and generate below
+    }
+    const key = generatePrivateKey();
+    writeFileSync(WALLET_FILE, `${key}\n`, { mode: 0o600 });
+    const account = privateKeyToAccount(key);
+    return {
+        key,
+        info: {
+            address: account.address,
+            walletFile: WALLET_FILE,
+            network: resolveConfiguredNetwork(env.X402_NETWORK),
+            source: 'generated',
+        },
+    };
+}
+// Fetch native and USDC balances for the active llm_router wallet.
+export async function getWalletInfo(env = process.env) {
+    const wallet = resolveOrGenerateWalletKey(env);
+    const chain = resolveChain(wallet.info.network);
+    const client = createPublicClient({
+        chain,
+        transport: http(),
+    });
+    const [nativeBalance, usdcBalance] = await Promise.all([
+        client.getBalance({ address: wallet.info.address }),
+        client.readContract({
+            address: usdcAddressForNetwork(wallet.info.network),
+            abi: ERC20_ABI,
+            functionName: 'balanceOf',
+            args: [wallet.info.address],
+        }),
+    ]);
+    return {
+        ...wallet.info,
+        nativeBalance: formatEther(nativeBalance),
+        nativeSymbol: chain.nativeCurrency.symbol,
+        usdcBalance: formatUnits(usdcBalance, 6),
+    };
+}

package/dist/src/payment/x402.d.ts

@@ -0,0 +1,4 @@
+type RequestLike = string | URL | Request;
+type FetchFn = (input: RequestLike, init?: RequestInit) => Promise<Response>;
+export declare function createPaymentFetch(baseFetch: FetchFn, env?: NodeJS.ProcessEnv): FetchFn;
+export {};

package/dist/src/payment/x402.js

@@ -0,0 +1,37 @@
+import { x402Client, x402HTTPClient } from '@x402/fetch';
+import { registerExactEvmScheme } from '@x402/evm/exact/client';
+import { toClientEvmSigner } from '@x402/evm';
+import { privateKeyToAccount } from 'viem/accounts';
+import { createPublicClient, http } from 'viem';
+import { resolveChain } from './network.js';
+import { resolveOrGenerateWalletKey } from './wallet.js';
+// Wrap fetch so a single upstream 402 challenge is paid and retried transparently.
+export function createPaymentFetch(baseFetch, env = process.env) {
+    const wallet = resolveOrGenerateWalletKey(env);
+    const account = privateKeyToAccount(wallet.key);
+    const client = new x402Client();
+    const publicClient = createPublicClient({
+        chain: resolveChain(wallet.info.network),
+        transport: http(),
+    });
+    registerExactEvmScheme(client, { signer: toClientEvmSigner(account, publicClient) });
+    const httpClient = new x402HTTPClient(client);
+    return async (input, init) => {
+        const firstRequest = new Request(input, init);
+        const retryRequest = firstRequest.clone();
+        const firstResponse = await baseFetch(firstRequest);
+        if (firstResponse.status !== 402) {
+            return firstResponse;
+        }
+        const getHeader = (name) => firstResponse.headers.get(name);
+        const bodyText = await firstResponse.text();
+        const body = bodyText ? JSON.parse(bodyText) : undefined;
+        const paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, body);
+        const payload = await client.createPaymentPayload(paymentRequired);
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(payload);
+        for (const [key, value] of Object.entries(paymentHeaders)) {
+            retryRequest.headers.set(key, value);
+        }
+        return baseFetch(retryRequest);
+    };
+}

package/dist/src/proxy/openai.d.ts

@@ -0,0 +1,12 @@
+import type { RouterRequest } from '../types.js';
+export type OpenAIMessage = {
+    role: string;
+    content: unknown;
+};
+export type OpenAIChatRequest = Record<string, unknown> & {
+    model: string;
+    messages: OpenAIMessage[];
+    stream?: boolean;
+};
+export declare function isChatCompletionRequest(body: unknown): body is OpenAIChatRequest;
+export declare function toRouterRequest(body: OpenAIChatRequest): RouterRequest;

package/dist/src/proxy/openai.js

@@ -0,0 +1,33 @@
+// Normalize OpenAI message content into the smaller router request shape.
+function normalizeContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content.filter((part) => typeof part === 'object' && part !== null);
+    }
+    return '';
+}
+// Guard that the incoming payload looks like a chat completion request before routing it.
+export function isChatCompletionRequest(body) {
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const record = body;
+    return typeof record.model === 'string' && Array.isArray(record.messages);
+}
+// Convert the OpenAI request payload into the router's internal request shape.
+export function toRouterRequest(body) {
+    return {
+        model: body.model,
+        messages: body.messages.map((message) => ({
+            role: (typeof message.role === 'string' ? message.role : 'user'),
+            content: normalizeContent(message.content),
+        })),
+        ...(Array.isArray(body.tools) ? { tools: body.tools } : {}),
+        ...(typeof body.response_format === 'object' &&
+            body.response_format !== null &&
+            body.response_format.type === 'json_object'
+            ? { responseFormat: 'json' }
+            : {}),
+        ...(typeof body.max_tokens === 'number' ? { maxTokens: body.max_tokens } : {}),
+    };
+}

package/dist/src/proxy/server.d.ts

@@ -0,0 +1,11 @@
+export type ProxyOptions = {
+    host?: string;
+    port?: number;
+    upstreamBaseUrl?: string;
+};
+export type RunningProxyServer = {
+    host: string;
+    port: number;
+    close: () => Promise<void>;
+};
+export declare function startProxyServer(options?: ProxyOptions): Promise<RunningProxyServer>;

package/dist/src/proxy/server.js

@@ -0,0 +1,206 @@
+import { createServer } from 'node:http';
+import { Readable } from 'node:stream';
+import { createPaymentFetch } from '../payment/x402.js';
+import { getWalletInfo } from '../payment/wallet.js';
+import { normalizePromptText } from '../router/normalize.js';
+import { LOGICAL_MODELS } from '../router/models.js';
+import { routeRequest } from '../router/route.js';
+import { isChatCompletionRequest, toRouterRequest } from './openai.js';
+// Strip OpenClaw's metadata wrapper from the latest user turn for routing/logging only.
+function normalizeLatestUserMessageForRouting(body) {
+    const latestUserIndex = [...body.messages].map((message, index) => ({ message, index })).reverse()
+        .find(({ message }) => message.role === 'user')?.index;
+    if (latestUserIndex === undefined) {
+        return {
+            body,
+            preview: '',
+        };
+    }
+    const previewParts = [];
+    let changed = false;
+    const messages = body.messages.map((message, index) => {
+        if (index !== latestUserIndex)
+            return message;
+        if (typeof message.content === 'string') {
+            const normalized = normalizePromptText(message.content);
+            previewParts.push(normalized);
+            changed ||= normalized !== message.content;
+            return {
+                ...message,
+                content: normalized,
+            };
+        }
+        if (Array.isArray(message.content)) {
+            return {
+                ...message,
+                content: message.content.map((part) => {
+                    if (typeof part !== 'object' || part === null)
+                        return part;
+                    if ((part.type === 'text' || part.type === 'input_text') && typeof part.text === 'string') {
+                        const normalized = normalizePromptText(part.text);
+                        previewParts.push(normalized);
+                        changed ||= normalized !== part.text;
+                        return {
+                            ...part,
+                            text: normalized,
+                        };
+                    }
+                    return part;
+                }),
+            };
+        }
+        return message;
+    });
+    return {
+        body: changed ? { ...body, messages } : body,
+        preview: previewParts.join('\n').slice(0, 120),
+    };
+}
+// Read the full JSON request body before we normalize and route it.
+function collectBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => {
+            body += chunk;
+        });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+// Send a small JSON response for health, errors, and simple plugin endpoints.
+function writeJson(res, statusCode, payload) {
+    res.statusCode = statusCode;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify(payload));
+}
+// Forward caller headers upstream, but strip transport/auth headers the proxy owns.
+function copyRequestHeaders(req) {
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (['host', 'content-length', 'connection', 'authorization', 'x-provider-key', 'x-payment'].includes(key)) {
+            continue;
+        }
+        headers[key] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    return headers;
+}
+// Mirror upstream headers back to the caller while leaving framing headers to Node.
+function copyResponseHeaders(upstream, res) {
+    for (const [key, value] of upstream.headers.entries()) {
+        if (['content-length', 'connection', 'transfer-encoding'].includes(key))
+            continue;
+        res.setHeader(key, value);
+    }
+}
+// Handle the only routed endpoint in this minimal version: chat completions.
+async function handleChat(req, res, upstreamBaseUrl, payFetch) {
+    const raw = await collectBody(req);
+    const body = JSON.parse(raw);
+    if (!isChatCompletionRequest(body)) {
+        writeJson(res, 400, { error: { message: 'Invalid chat completion request' } });
+        return;
+    }
+    const normalizedLatestUser = normalizeLatestUserMessageForRouting(body);
+    const decision = routeRequest(toRouterRequest(normalizedLatestUser.body));
+    const upstreamBody = {
+        ...body,
+        model: decision.resolvedModel,
+    };
+    console.info(JSON.stringify({
+        component: 'llm_router',
+        event: 'route_request',
+        requestPath: req.url ?? '/v1/chat/completions',
+        incomingModel: normalizedLatestUser.body.model,
+        latestUserPreview: normalizedLatestUser.preview,
+        logicalModel: decision.logicalModel,
+        category: decision.category,
+        resolvedModel: decision.resolvedModel,
+        reason: decision.reason,
+        hasTools: decision.hasTools,
+        wantsJson: decision.wantsJson,
+        hasImage: decision.hasImage,
+    }));
+    const upstreamResponse = await payFetch(new URL('/v1/chat/completions', upstreamBaseUrl), {
+        method: 'POST',
+        headers: {
+            ...copyRequestHeaders(req),
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(upstreamBody),
+    });
+    copyResponseHeaders(upstreamResponse, res);
+    res.setHeader('x-llm-router-logical-model', decision.logicalModel);
+    res.setHeader('x-llm-router-category', decision.category);
+    res.setHeader('x-llm-router-resolved-model', decision.resolvedModel);
+    res.statusCode = upstreamResponse.status;
+    if (!upstreamResponse.body) {
+        res.end();
+        return;
+    }
+    Readable.fromWeb(upstreamResponse.body).pipe(res);
+}
+// Start the local proxy that OpenClaw points at.
+export async function startProxyServer(options = {}) {
+    const host = options.host ?? process.env.LLM_ROUTER_HOST ?? '127.0.0.1';
+    const port = options.port ?? Number(process.env.LLM_ROUTER_PORT ?? 3000);
+    const upstreamBaseUrl = options.upstreamBaseUrl ?? process.env.INFERENCE_PROVIDER_BASE_URL ?? 'http://127.0.0.1:8787';
+    const payFetch = createPaymentFetch(fetch, process.env);
+    const server = createServer(async (req, res) => {
+        try {
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204, {
+                    'access-control-allow-origin': '*',
+                    'access-control-allow-methods': 'GET,POST,OPTIONS',
+                    'access-control-allow-headers': 'Authorization, Content-Type, X-Provider-Key',
+                });
+                res.end();
+                return;
+            }
+            res.setHeader('access-control-allow-origin', '*');
+            res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
+            res.setHeader('access-control-allow-headers', 'Authorization, Content-Type, X-Provider-Key');
+            if (req.method === 'GET' && req.url === '/healthz') {
+                writeJson(res, 200, { ok: true });
+                return;
+            }
+            if (req.method === 'GET' && (req.url === '/wallet' || req.url === '/v1/wallet')) {
+                writeJson(res, 200, await getWalletInfo(process.env));
+                return;
+            }
+            if (req.method === 'GET' && req.url === '/v1/models') {
+                writeJson(res, 200, {
+                    data: LOGICAL_MODELS.map((id) => ({
+                        id,
+                        object: 'model',
+                        owned_by: 'llm_router',
+                    })),
+                });
+                return;
+            }
+            if (req.method === 'POST' && req.url === '/v1/chat/completions') {
+                await handleChat(req, res, upstreamBaseUrl, payFetch);
+                return;
+            }
+            writeJson(res, 404, { error: { message: 'Not found' } });
+        }
+        catch (error) {
+            writeJson(res, 500, {
+                error: {
+                    message: error instanceof Error ? error.message : 'Internal server error',
+                },
+            });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    return {
+        host,
+        port,
+        close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())),
+    };
+}

package/dist/src/router/classify.d.ts

@@ -0,0 +1,3 @@
+import type { PromptClassification, RouterRequest } from '../types.js';
+export declare function requestSignals(request: RouterRequest): Pick<PromptClassification, 'hasTools' | 'wantsJson' | 'hasImage'>;
+export declare function classifyPrompt(request: RouterRequest): PromptClassification;

package/dist/src/router/classify.js

@@ -0,0 +1,81 @@
+import { normalizePromptText } from './normalize.js';
+const CODING_MARKERS = ['typescript', 'javascript', 'python', 'rust', 'bug', 'refactor', 'function', 'class'];
+const REASONING_MARKERS = ['analyze', 'compare', 'tradeoff', 'deep dive', 'step by step', 'think more'];
+// Flatten OpenAI-style content parts into plain text for simple keyword checks.
+function extractText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .flatMap((part) => {
+        if (typeof part !== 'object' || part === null)
+            return [];
+        if ((part.type === 'text' || part.type === 'input_text') && typeof part.text === 'string') {
+            return [part.text];
+        }
+        return [];
+    })
+        .join('\n');
+}
+// Detect whether any user message contains an image input part.
+function hasImageInput(request) {
+    return request.messages.some((message) => Array.isArray(message.content) &&
+        message.content.some((part) => typeof part === 'object' &&
+            part !== null &&
+            (part.type === 'image_url' || part.type === 'input_image')));
+}
+// Minimal keyword matcher for the first-pass classifier.
+function includesAny(text, markers) {
+    const normalized = text.toLowerCase();
+    return markers.some((marker) => normalized.includes(marker));
+}
+export function requestSignals(request) {
+    return {
+        hasTools: Boolean(request.tools && request.tools.length > 0),
+        wantsJson: request.responseFormat === 'json',
+        hasImage: hasImageInput(request),
+    };
+}
+// Classify against the latest user prompt so older turns do not keep contaminating routing.
+function latestUserText(request) {
+    const latestUserMessage = [...request.messages].reverse().find((message) => message.role === 'user');
+    return latestUserMessage ? normalizePromptText(extractText(latestUserMessage.content)).toLowerCase() : '';
+}
+// Classify the request into one of the few coarse routing buckets we support today.
+export function classifyPrompt(request) {
+    const text = latestUserText(request);
+    const { hasTools, wantsJson, hasImage } = requestSignals(request);
+    if (hasImage) {
+        return {
+            category: 'vision',
+            reason: 'image input detected',
+            hasTools,
+            wantsJson,
+            hasImage,
+        };
+    }
+    if (includesAny(text, CODING_MARKERS)) {
+        return {
+            category: 'coding',
+            reason: 'coding keywords detected',
+            hasTools,
+            wantsJson,
+            hasImage,
+        };
+    }
+    if (includesAny(text, REASONING_MARKERS)) {
+        return {
+            category: 'reasoning',
+            reason: 'reasoning keywords detected',
+            hasTools,
+            wantsJson,
+            hasImage,
+        };
+    }
+    return {
+        category: 'simple',
+        reason: 'default simple route',
+        hasTools,
+        wantsJson,
+        hasImage,
+    };
+}

package/dist/src/router/models.d.ts

@@ -0,0 +1,4 @@
+import type { RouteCategory } from '../types.js';
+export declare const LOGICAL_MODELS: readonly ["llmrouter/auto", "llmrouter/simple", "llmrouter/coding", "llmrouter/reasoning", "llmrouter/vision"];
+export declare const CATEGORY_MODEL_MAP: Record<RouteCategory, string>;
+export declare function logicalModelToCategory(model: string): RouteCategory | undefined;

package/dist/src/router/models.js

@@ -0,0 +1,27 @@
+export const LOGICAL_MODELS = [
+    'llmrouter/auto',
+    'llmrouter/simple',
+    'llmrouter/coding',
+    'llmrouter/reasoning',
+    'llmrouter/vision',
+];
+export const CATEGORY_MODEL_MAP = {
+    simple: 'deepseek/deepseek-chat',
+    coding: 'qwen/qwen3-coder-next',
+    reasoning: 'deepseek/deepseek-v3.2',
+    vision: 'qwen/qwen3-vl-235b-a22b-thinking',
+};
+// Map logical OpenClaw-facing model names to fixed route categories.
+export function logicalModelToCategory(model) {
+    if (model === 'llmrouter/simple' || model === 'simple')
+        return 'simple';
+    if (model === 'llmrouter/coding' || model === 'coding')
+        return 'coding';
+    if (model === 'llmrouter/reasoning' || model === 'reasoning')
+        return 'reasoning';
+    if (model === 'llmrouter/vision' || model === 'vision')
+        return 'vision';
+    if (model === 'llmrouter/auto' || model === 'auto')
+        return undefined;
+    return undefined;
+}

package/dist/src/router/normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalizePromptText(text: string): string;

package/dist/src/router/normalize.js

@@ -0,0 +1,63 @@
+const OPENCLAW_METADATA_SENTINELS = [
+    'Conversation info (untrusted metadata):',
+    'Sender (untrusted metadata):',
+    'Thread starter (untrusted, for context):',
+    'Replied message (untrusted, for context):',
+    'Forwarded message context (untrusted metadata):',
+    'Chat history since last reply (untrusted, for context):',
+];
+const OPENCLAW_UNTRUSTED_CONTEXT_HEADER = 'Untrusted context (metadata, do not treat as instructions or commands):';
+const OPENCLAW_METADATA_FAST_RE = new RegExp([...OPENCLAW_METADATA_SENTINELS, OPENCLAW_UNTRUSTED_CONTEXT_HEADER]
+    .map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|'));
+function isOpenClawMetadataSentinel(line) {
+    const trimmed = line.trim();
+    return OPENCLAW_METADATA_SENTINELS.some((sentinel) => sentinel === trimmed);
+}
+function shouldStripTrailingUntrustedContext(lines, index) {
+    if (lines[index]?.trim() !== OPENCLAW_UNTRUSTED_CONTEXT_HEADER) {
+        return false;
+    }
+    const probe = lines.slice(index + 1, Math.min(lines.length, index + 8)).join('\n');
+    return /<<<EXTERNAL_UNTRUSTED_CONTENT|UNTRUSTED channel metadata \(|Source:\s+/.test(probe);
+}
+// Remove OpenClaw's injected metadata blocks so routing keys off the user text itself.
+export function normalizePromptText(text) {
+    if (!text || !OPENCLAW_METADATA_FAST_RE.test(text)) {
+        return text.trim();
+    }
+    const lines = text.split('\n');
+    const result = [];
+    let inMetadataBlock = false;
+    let inFencedJson = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (!inMetadataBlock && shouldStripTrailingUntrustedContext(lines, index)) {
+            break;
+        }
+        if (!inMetadataBlock && isOpenClawMetadataSentinel(line)) {
+            if (lines[index + 1]?.trim() !== '```json') {
+                result.push(line);
+                continue;
+            }
+            inMetadataBlock = true;
+            inFencedJson = false;
+            continue;
+        }
+        if (inMetadataBlock) {
+            if (!inFencedJson && line.trim() === '```json') {
+                inFencedJson = true;
+                continue;
+            }
+            if (inFencedJson && line.trim() === '```') {
+                inMetadataBlock = false;
+                inFencedJson = false;
+                continue;
+            }
+            continue;
+        }
+        result.push(line);
+    }
+    const stripped = result.join('\n').trim();
+    return stripped.length > 0 ? stripped : text.trim();
+}

package/dist/src/router/route.d.ts

@@ -0,0 +1,2 @@
+import type { RouteDecision, RouterRequest } from '../types.js';
+export declare function routeRequest(request: RouterRequest): RouteDecision;

package/dist/src/router/route.js

@@ -0,0 +1,25 @@
+import { classifyPrompt, requestSignals } from './classify.js';
+import { CATEGORY_MODEL_MAP, logicalModelToCategory } from './models.js';
+function forcedClassification(request, category) {
+    return {
+        category,
+        reason: `logical model forced ${category}`,
+        ...requestSignals(request),
+    };
+}
+// Resolve a request to one concrete model using either a forced logical route or the basic classifier.
+export function routeRequest(request) {
+    const forcedCategory = logicalModelToCategory(request.model);
+    const classification = forcedCategory
+        ? forcedClassification(request, forcedCategory)
+        : classifyPrompt(request);
+    return {
+        logicalModel: request.model,
+        category: classification.category,
+        resolvedModel: CATEGORY_MODEL_MAP[classification.category],
+        reason: classification.reason,
+        hasTools: classification.hasTools,
+        wantsJson: classification.wantsJson,
+        hasImage: classification.hasImage,
+    };
+}