@blockrun/clawrouter 0.12.26 → 0.12.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.26",
+  "version": "0.12.27",
   "description": "Smart LLM router — save 92% on inference costs. 41+ models, one wallet, x402 micropayments.",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
   "files": [
     "dist",
     "scripts",
+    "skills",
     "openclaw.plugin.json"
   ],
   "scripts": {

package/skills/clawrouter/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: clawrouter
+description: Smart LLM router — save 67% on inference costs. Routes every request to the cheapest capable model across 41 models from OpenAI, Anthropic, Google, DeepSeek, and xAI.
+homepage: https://github.com/BlockRunAI/ClawRouter
+metadata: { "openclaw": { "emoji": "🦀", "requires": { "config": ["models.providers.blockrun"] } } }
+---
+
+# ClawRouter
+
+Smart LLM router that saves 67% on inference costs by routing each request to the cheapest model that can handle it. 41 models across 5 providers, all through one wallet.
+
+## Install
+
+```bash
+openclaw plugins install @blockrun/clawrouter
+```
+
+## Setup
+
+```bash
+# Enable smart routing (auto-picks cheapest model per request)
+openclaw models set blockrun/auto
+
+# Or pin a specific model
+openclaw models set openai/gpt-4o
+```
+
+## How Routing Works
+
+ClawRouter classifies each request into one of four tiers:
+
+- **SIMPLE** (40% of traffic) — factual lookups, greetings, translations → Gemini Flash ($0.60/M, 99% savings)
+- **MEDIUM** (30%) — summaries, explanations, data extraction → DeepSeek Chat ($0.42/M, 99% savings)
+- **COMPLEX** (20%) — code generation, multi-step analysis → Claude Opus ($75/M, best quality)
+- **REASONING** (10%) — proofs, formal logic, multi-step math → o3 ($8/M, 89% savings)
+
+Rules handle ~80% of requests in <1ms. Only ambiguous queries hit the LLM classifier (~$0.00003 per classification).
+
+## Available Models
+
+41 models including: gpt-5.2, gpt-4o, gpt-4o-mini, o3, o1, claude-opus-4.6, claude-sonnet-4.6, claude-haiku-4.5, gemini-3.1-pro, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, deepseek-chat, deepseek-reasoner, grok-3, grok-3-mini.
+
+## Example Output
+
+```
+[ClawRouter] google/gemini-2.5-flash (SIMPLE, rules, confidence=0.92)
+             Cost: $0.0025 | Baseline: $0.308 | Saved: 99.2%
+```

package/skills/imagegen/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: imagegen
+description: Generate images via BlockRun's image API. Trigger when the user asks to generate, create, draw, or make an image.
+metadata: { "openclaw": { "emoji": "🖼️", "requires": { "config": ["models.providers.blockrun"] } } }
+---
+
+# Image Generation
+
+When the user asks to generate, create, draw, or make an image, generate it by calling ClawRouter's image API directly — no extra setup needed.
+
+## How to Generate
+
+POST to `http://localhost:8402/v1/images/generations`:
+
+```json
+{
+  "model": "google/nano-banana",
+  "prompt": "<user's prompt>",
+  "size": "1024x1024",
+  "n": 1
+}
+```
+
+The response contains a public image URL:
+
+```json
+{
+  "created": 1741460000,
+  "data": [{ "url": "https://files.catbox.moe/abc123.png" }]
+}
+```
+
+Display the image inline in your response:
+
+```markdown
+![generated image](https://files.catbox.moe/abc123.png)
+```
+
+## Model Selection
+
+Pick the model based on what the user asks for (or default to `nano-banana`):
+
+| Model shorthand | Full ID | Price | Best for |
+|---|---|---|---|
+| `nano-banana` | `google/nano-banana` | $0.05 | Default — fast, cheap, good quality |
+| `banana-pro` | `google/nano-banana-pro` | $0.10 | High-res up to 4096×4096 |
+| `dall-e-3` | `openai/dall-e-3` | $0.04 | Photorealistic, complex scenes |
+| `gpt-image` | `openai/gpt-image-1` | $0.02 | Budget option |
+| `flux` | `black-forest/flux-1.1-pro` | $0.04 | Artistic styles, fewer restrictions |
+
+If the user mentions "high res" or "large", use `banana-pro`. If they want "photorealistic" or "dall-e", use `dall-e-3`. Otherwise default to `nano-banana`.
+
+## Size Options
+
+Default is `1024x1024`. Adjust based on user request:
+
+- Portrait: `1024x1792`
+- Landscape: `1792x1024` (dall-e-3) or `1024x1024` (others)
+- High-res: up to `4096x4096` with `banana-pro` only
+
+## Example Interactions
+
+**User:** Draw me a golden retriever surfing on a wave
+
+→ Call `nano-banana` with prompt `"a golden retriever surfing on a wave"`, display the image.
+
+**User:** Generate a high-res mountain landscape, landscape format
+
+→ Call `banana-pro` with size `1024x1024` (max varies by model), prompt `"mountain landscape"`.
+
+**User:** Make a cyberpunk city with dall-e
+
+→ Call `dall-e-3` with prompt `"a futuristic cyberpunk city"`.
+
+## Notes
+
+- Payment is automatic via x402 — deducted from the user's BlockRun wallet
+- If the call fails with a payment error, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
+- DALL-E 3 applies OpenAI content policy; use `flux` or `nano-banana` for more flexibility
+- Google models may return base64 — ClawRouter handles uploading automatically, you'll get a URL back

package/skills/release/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: release
+description: Use this skill for EVERY ClawRouter release. Enforces the full checklist — version sync, CHANGELOG, blockrun server constant, build, tests, npm publish, git tag, GitHub release. No step can be skipped.
+---
+
+# ClawRouter Release Checklist
+
+**This skill is mandatory for every release. Execute every step in order. Do not skip.**
+
+## Step 1: Confirm the New Version
+
+Read the current version:
+
+```bash
+cat package.json | grep '"version"'
+```
+
+Ask: "What version are we releasing?" Confirm it follows semver and is higher than current.
+
+---
+
+## Step 2: Update `package.json` Version
+
+Edit `package.json` — bump `"version"` to the new version.
+
+---
+
+## Step 3: Write CHANGELOG Entry
+
+Open `CHANGELOG.md`. Add a new section at the top (after the header) in this format:
+
+```markdown
+## v{VERSION} — {DATE}
+
+- **Feature/Fix name** — description
+- **Feature/Fix name** — description
+```
+
+Rules:
+- Date format: `Mar 8, 2026`
+- One bullet per logical change
+- Every bullet must be present — no "see git log"
+- Include **all** changes since the previous release
+
+---
+
+## Step 4: Sync `CURRENT_CLAWROUTER_VERSION` in blockrun
+
+**This is the most commonly forgotten step.**
+
+File: `/Users/vickyfu/Documents/blockrun-web/blockrun/src/app/api/v1/chat/completions/route.ts`
+
+Find this line:
+```typescript
+const CURRENT_CLAWROUTER_VERSION = "x.y.z";
+```
+
+Update it to match the new version. Verify with:
+```bash
+grep CURRENT_CLAWROUTER_VERSION /Users/vickyfu/Documents/blockrun-web/blockrun/src/app/api/v1/chat/completions/route.ts
+```
+
+**Do not skip this.** It controls the update nudge shown to users running outdated versions.
+
+---
+
+## Step 5: Build
+
+```bash
+npm run build
+```
+
+Fix any TypeScript or build errors before proceeding.
+
+---
+
+## Step 6: Run Tests
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+```
+
+All must pass. Fix failures before proceeding.
+
+---
+
+## Step 7: Commit Everything
+
+Stage and commit:
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: bump version to {VERSION}"
+```
+
+If blockrun's route.ts was updated, commit that separately in the blockrun repo.
+
+---
+
+## Step 8: Push to GitHub
+
+```bash
+git push origin main
+```
+
+---
+
+## Step 9: Create Git Tag
+
+```bash
+git tag v{VERSION}
+git push origin v{VERSION}
+```
+
+---
+
+## Step 10: Create GitHub Release
+
+```bash
+gh release create v{VERSION} \
+  --title "v{VERSION}" \
+  --notes "$(sed -n '/^## v{VERSION}/,/^## v[0-9]/p' CHANGELOG.md | head -n -1)"
+```
+
+Verify the release on GitHub: https://github.com/BlockRunAI/ClawRouter/releases
+
+The release notes **must** match the CHANGELOG entry exactly.
+
+---
+
+## Step 11: Publish to npm
+
+```bash
+npm publish --access public
+```
+
+Verify: https://npmjs.com/package/@blockrun/clawrouter
+
+Expected output: `+ @blockrun/clawrouter@{VERSION}`
+
+---
+
+## Step 12: Final Verification
+
+Run this checklist to confirm everything is in sync:
+
+```bash
+# 1. package.json version
+cat package.json | grep '"version"'
+
+# 2. CHANGELOG has the entry
+head -10 CHANGELOG.md
+
+# 3. blockrun CURRENT_CLAWROUTER_VERSION
+grep CURRENT_CLAWROUTER_VERSION /Users/vickyfu/Documents/blockrun-web/blockrun/src/app/api/v1/chat/completions/route.ts
+
+# 4. npm package is live
+npm view @blockrun/clawrouter version
+
+# 5. GitHub tag exists
+git tag | grep v{VERSION}
+
+# 6. GitHub release exists
+gh release view v{VERSION}
+```
+
+All 6 must match the new version. If any mismatch, fix before declaring the release done.
+
+---
+
+## Common Mistakes (Never Repeat These)
+
+| Mistake | Prevention |
+|---------|-----------|
+| Forgot to update `CURRENT_CLAWROUTER_VERSION` in blockrun | Step 4 — always check |
+| CHANGELOG entry missing or incomplete | Step 3 — write it before building |
+| npm publish before tests pass | Steps 5-6 must precede Step 11 |
+| GitHub release notes empty | Step 10 — extract from CHANGELOG |
+| Git tag not pushed | Step 9 — push tag separately |
+| docs not reflecting new features | Update docs in same PR as the feature |