openrouter

OpenRouter multi-vendor LLM gateway for all snappy-* skills.

Ported from kernel snappy-openrouter in Phase 0.5. See state/lib/openrouter.ts for the full API surface.

Steps

• chat() - see state/lib/openrouter.ts
• chatWithFallback() - see state/lib/openrouter.ts

Eval

Actor: the exported functions in state/lib/openrouter.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

Gotchas

via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)

1. realpathSync(process.argv[1]) CLI guard wrapped in try/catch

• See the kernel SKILL.md for the original long-form guidance if you need it

(read-only reference at the kernel path above).

Graduation

This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.

Rubric

criteria:
  - name: primary_endpoint_responds
    kind: deterministic
    check: "chat() call completes with OpenRouter API response (HTTP 200); response includes {choices: [{message: {content: '...'}}]} with content.length > 0."
  - name: model_returns_tokens
    kind: deterministic
    check: "Response has tokens_used field (or equivalent) > 0 (not zero-token stub). Proof of actual inference, not cached/empty."
  - name: if_primary_fails_fallback_fired
    kind: deterministic
    check: "chatWithFallback() on primary failure attempts fallback model; if fallback succeeds, response is returned. If both fail, score is 0.0."
  - name: fallback_capped_lower_than_primary
    kind: deterministic
    check: "If chatWithFallback uses fallback path (primary failed), score is capped at 0.5 max. Primary success = 1.0, fallback success = 0.5."
  - name: response_coherence
    kind: judge
    check: "Response content is semantically coherent (not garbage, truncated, or adversarial tokens). For deterministic check: response is not empty or error-only text."

openrouter - loader

Per-turn rules for the openrouter skill. Full reference: state/skills/openrouter/SKILL.md. Do not skip these.

Read intents - mirror Query (do this first)

For "show available models" / "list openrouter models" / "what models do I have" requests, call the mirror Query directly inside compose_inline. Returns in ~10ms from the local SQLite mirror.

$rows = Query("openrouter_models", {limit: 50}, {rows: []})
root = Card([
  CardHeader("OpenRouter Models"),
  Table($rows.rows, ["id", "name", "provider", "context_length"]),
])

Mirror columns: id, name, provider, context_length, pricing_prompt, pricing_completion.

NEVER call the OpenRouter HTTP API for a model-list intent. API calls are for WRITES only: sending completions. Use the mirror for all read views.

Critical Rules

• NEVER hardcode an API key - use env("OPENROUTER_API_KEY") from state/lib/env.ts or env("KEY") throws
• Prefer state/lib/dispatch.ts for cheap-labor grunt work - dispatch.ts is the canonical PID-loop dispatch path and logs to state/log/dispatches.ndjson for cost/latency audit. Reach for openrouter directly only when you specifically need the multi-vendor fallback chain.
• Every dispatch logs one ndjson line - do not bypass the audit log

Commands

| ui model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact | |invoke: import from state/lib/openrouter.ts - chat(), chatWithFallback() |preferred for grunt work: state/lib/dispatch.ts (haiku/sonnet/gemini/llama/qwen/deepseek) |eval log: state/log/pending-eval.ndjson (manual review until shape gate added) |cost audit: state/log/dispatches.ndjson

Lang surface example

root = Stack([controls, content])
controls = Buttons([btn7, btn30, btn90])
btn7 = Button("7 days", @Set($days, "7"))
btn30 = Button("30 days", @Set($days, "30"))
btn90 = Button("90 days", @Set($days, "90"))
$days = "7"
log = Query("get_dispatch_log", {days: $days}, {dispatches: []}, 60)
config = Query("get_dispatch_config", {}, {chat: {backend: "", model: ""}, subagent: {backend: "", model: ""}}, 120)
content = Stack([
  TextContent("Backend: " + config.chat.backend + " / " + config.chat.model),
  Table(log.dispatches, ["timestamp", "backend", "model", "intent", "durationMs"])
])

Response fields: log.dispatches[].timestamp, log.dispatches[].backend, log.dispatches[].model, log.dispatches[].intent, log.dispatches[].durationMs; config.chat.backend, config.chat.model

Known Pitfalls

• Phase 0.5 port from snappy-openrouter - mechanical, no hard-won rules in the page
• "Use cheap models for mechanical/verifiable work, keep judgment on the orchestrator" - program.md cheap-labor dispatch rule applies
• During interactive work with Robert, Opus drafts directly - reserve dispatch for background/bulk jobs

Self-Test

An agent reading this should correctly:

1. [ ] Prefer state/lib/dispatch.ts over raw openrouter for routine cheap-labor calls?
2. [ ] Pull the API key via env("OPENROUTER_API_KEY") rather than reading the cache file directly?
3. [ ] Skip openrouter dispatch when in interactive Robert-in-room work?

Found a gap? Edit this file. <!-- footer-injection-point -->