@blockrun/clawrouter 0.5.7 → 0.5.9

package/README.md

@@ -56,6 +56,8 @@ Done! Smart routing (`blockrun/auto`) is now your default model.
 ### Tips
 
 - **Use `/model blockrun/auto`** in any conversation to switch on the fly
+- **Free tier?** Use `/model free` — routes to nvidia/gpt-oss-120b at $0
+- **Model aliases:** `/model sonnet`, `/model grok`, `/model deepseek`, `/model kimi`
 - **Want a specific model?** Use `blockrun/openai/gpt-4o` or `blockrun/anthropic/claude-sonnet-4`
 - **Already have a funded wallet?** `export BLOCKRUN_WALLET_KEY=0x...`
 
@@ -83,7 +85,7 @@ No API keys. No accounts. Just fund and go.
 **100% local, <1ms, zero API calls.**
 
 ```
-Request → Weighted Scorer (14 dimensions)
+Request → Weighted Scorer (15 dimensions)
               │
               ├── High confidence → Pick model from tier → Done
               │
@@ -206,6 +208,42 @@ ClawRouter automatically filters out models that can't handle your context size:
 
 This prevents wasted API calls and faster fallback to capable models.
 
+### Model Aliases (v0.5)
+
+Use short aliases instead of full model paths:
+
+```bash
+/model free      # nvidia/gpt-oss-120b (FREE!)
+/model sonnet    # anthropic/claude-sonnet-4
+/model opus      # anthropic/claude-opus-4
+/model haiku     # anthropic/claude-haiku-4.5
+/model gpt       # openai/gpt-4o
+/model gpt5      # openai/gpt-5.2
+/model deepseek  # deepseek/deepseek-chat
+/model reasoner  # deepseek/deepseek-reasoner
+/model kimi      # moonshot/kimi-k2.5
+/model gemini    # google/gemini-2.5-pro
+/model flash     # google/gemini-2.5-flash
+/model grok      # xai/grok-3
+/model grok-fast # xai/grok-4-fast-reasoning
+```
+
+All aliases work with `/model blockrun/xxx` or just `/model xxx`.
+
+### Free Tier Fallback (v0.5)
+
+When your wallet balance hits $0, ClawRouter automatically falls back to the free model (`nvidia/gpt-oss-120b`):
+
+```
+Wallet: $0.00
+Request: "Help me write a function"
+→ Routes to nvidia/gpt-oss-120b (FREE)
+→ No "insufficient funds" error
+→ Keep building while you top up
+```
+
+You'll never get blocked by an empty wallet — the free tier keeps you running.
+
 ### Session Persistence (v0.5)
 
 For multi-turn conversations, ClawRouter pins the model to prevent mid-task switching:
@@ -262,8 +300,10 @@ Compared to **$75/M** for Claude Opus = **96% savings** on a typical workload.
 | grok-code-fast-1      | $0.20     | $1.50      | 131K    |           |
 | **Moonshot**          |           |            |         |           |
 | kimi-k2.5             | $0.50     | $2.40      | 262K    |    \*     |
-| **NVIDIA**            |           |            |         |           |
-| gpt-oss-120b          | **FREE**  | **FREE**   | 128K    |           |
+| **NVIDIA (Free)**     |           |            |         |           |
+| gpt-oss-120b          | **$0**    | **$0**     | 128K    |           |
+
+> **Free tier:** `nvidia/gpt-oss-120b` costs nothing and serves as automatic fallback when wallet is empty.
 
 Full list: [`src/models.ts`](src/models.ts)
 
@@ -408,7 +448,7 @@ If you lose your wallet key, **there is no way to recover it**. The wallet is se
 │                   ClawRouter (localhost)                     │
 │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
 │  │ Weighted Scorer │→ │ Model Selector  │→ │ x402 Signer │ │
-│  │  (14 dimensions)│  │ (cheapest tier) │  │   (USDC)    │ │
+│  │  (15 dimensions)│  │ (cheapest tier) │  │   (USDC)    │ │
 │  └─────────────────┘  └─────────────────┘  └─────────────┘ │
 └─────────────────────────────────────────────────────────────┘
                               │
@@ -584,7 +624,7 @@ Agents shouldn't need a human to paste API keys. They should generate a wallet,
 ### Quick Checklist
 
 ```bash
-# 1. Check your version (should be 0.5.0+)
+# 1. Check your version (should be 0.5.7+)
 cat ~/.openclaw/extensions/clawrouter/package.json | grep version
 
 # 2. Check proxy is running
@@ -644,14 +684,17 @@ OpenClaw's security scanner may flag ClawRouter with:
 [env-harvesting] Environment variable access combined with network send
 ```
 
-**This is a false positive.** ClawRouter reads `BLOCKRUN_WALLET_KEY` to sign x402 payment transactions — this is required and intentional:
+**This is a false positive.** The scanner's heuristic (`env variable + network request = suspicious`) flags all payment plugins, but this pattern is inherently required for non-custodial payments.
+
+ClawRouter reads `BLOCKRUN_WALLET_KEY` to sign x402 payment transactions — this is required and intentional:
 
 - The wallet key is used **locally** for cryptographic signing (EIP-712)
 - The **signature** is transmitted, not the private key itself
-- This is standard x402 payment protocol behavior
+- The key **never leaves the machine** — only cryptographic proofs are sent
+- This is standard [x402 payment protocol](https://x402.org) behavior
 - Source code is [MIT licensed and fully auditable](https://github.com/BlockRunAI/ClawRouter)
 
-See [`openclaw.security.json`](openclaw.security.json) for detailed security documentation.
+See [`openclaw.security.json`](openclaw.security.json) for detailed security documentation and [this discussion](https://x.com/bc1beat/status/2020158972561428686) for more context.
 
 ### Port 8402 already in use
 
@@ -724,6 +767,8 @@ BLOCKRUN_WALLET_KEY=0x... npx tsx test-e2e.ts
 - [x] Context-aware routing — filter out models that can't handle context size
 - [x] Session persistence — pin model for multi-turn conversations
 - [x] Cost tracking — /stats command with savings dashboard
+- [x] Model aliases — `/model free`, `/model sonnet`, `/model grok`, etc.
+- [x] Free tier — nvidia/gpt-oss-120b for $0 when wallet is empty
 - [ ] Cascade routing — try cheap model first, escalate on low quality
 - [ ] Spend controls — daily/monthly budgets
 - [ ] Remote analytics — cost tracking at blockrun.ai

package/dist/index.js

@@ -2384,6 +2384,28 @@ function isProviderError(status, body) {
   }
   return PROVIDER_ERROR_PATTERNS.some((pattern) => pattern.test(body));
 }
+var VALID_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool", "function"]);
+var ROLE_MAPPINGS = {
+  developer: "system",
+  // OpenAI's newer API uses "developer" for system messages
+  model: "assistant"
+  // Some APIs use "model" instead of "assistant"
+};
+function normalizeMessageRoles(messages) {
+  if (!messages || messages.length === 0) return messages;
+  let hasChanges = false;
+  const normalized = messages.map((msg) => {
+    if (VALID_ROLES.has(msg.role)) return msg;
+    const mappedRole = ROLE_MAPPINGS[msg.role];
+    if (mappedRole) {
+      hasChanges = true;
+      return { ...msg, role: mappedRole };
+    }
+    hasChanges = true;
+    return { ...msg, role: "user" };
+  });
+  return hasChanges ? normalized : messages;
+}
 function normalizeMessagesForGoogle(messages) {
   if (!messages || messages.length === 0) return messages;
   let firstNonSystemIdx = -1;
@@ -2614,6 +2636,9 @@ async function tryModelRequest(upstreamUrl, method, headers, body, modelId, maxT
   try {
     const parsed = JSON.parse(body.toString());
     parsed.model = modelId;
+    if (Array.isArray(parsed.messages)) {
+      parsed.messages = normalizeMessageRoles(parsed.messages);
+    }
     if (isGoogleModel(modelId) && Array.isArray(parsed.messages)) {
       parsed.messages = normalizeMessagesForGoogle(parsed.messages);
     }
@@ -3029,7 +3054,14 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
               if (toolCalls && toolCalls.length > 0) {
                 const toolCallChunk = {
                   ...baseChunk,
-                  choices: [{ index, delta: { tool_calls: toolCalls }, logprobs: null, finish_reason: null }]
+                  choices: [
+                    {
+                      index,
+                      delta: { tool_calls: toolCalls },
+                      logprobs: null,
+                      finish_reason: null
+                    }
+                  ]
                 };
                 const toolCallData = `data: ${JSON.stringify(toolCallChunk)}
 
@@ -3039,7 +3071,14 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
               }
               const finishChunk = {
                 ...baseChunk,
-                choices: [{ index, delta: {}, logprobs: null, finish_reason: choice.finish_reason ?? "stop" }]
+                choices: [
+                  {
+                    index,
+                    delta: {},
+                    logprobs: null,
+                    finish_reason: choice.finish_reason ?? "stop"
+                  }
+                ]
               };
               const finishData = `data: ${JSON.stringify(finishChunk)}