Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.7 KB
Raw Blame
import type { Recipe } from '../types.ts';
import { openrouterModelSupportsSubagentLoop } from '../openrouter-families.ts';
import { deepseekReasoningContentCompatFetch } from './deepseek.ts';
import { openaiModelSupportsPromptCache } from './openai.ts';
import { GLM_THINKING_BY_DEFAULT_RE } from './zhipu.ts';

/**
 * Private in-process marker header. `gateway.chat()` sets it when the caller
 * asked for prompt caching (`cacheSystem`) on an OpenRouter route that needs
 * an explicit `cache_control` (Anthropic Claude). The compat fetch shim below
 * strips it and rewrites the body; the header NEVER leaves the process.
 *
 * Why a header and not providerOptions: the AI SDK's openai-compatible
 * adapter validates providerOptions against a fixed schema and silently
 * drops anthropic-namespace fields before building the wire body (same class
 * of problem as the embedding `input_type` ALS in gateway.ts). Headers pass
 * through untouched.
 */
export const OPENROUTER_CACHE_HEADER = 'x-gbrain-anthropic-prompt-cache';

/**
 * Family-scoped prompt-cache capability (per OpenRouter docs):
 * - OpenAI chat routes cache automatically, from the generation that shipped
 *   automatic caching onward. The family test is the SAME predicate the native
 *   `openai` recipe uses, so a model cannot report different capabilities
 *   depending on which route reaches it.
 * - DeepSeek routes cache automatically too (context caching is on by default
 *   for every account), matching the native `deepseek` recipe.
 * - Anthropic Claude routes cache when the request carries `cache_control`
 *   on a content block (applied by the fetch shim below).
 * Everything else is not marked cacheable — deliberately narrow rather than
 * blessing every routed model family forever.
 */
export function openrouterSupportsPromptCache(modelId: string): boolean {
  const normalized = modelId.trim().toLowerCase();
  if (normalized.startsWith('openai/')) {
    // OpenRouter appends routing variants (`:online`, `:nitro`, `:floor`, …)
    // that are not part of the upstream model id. Strip before delegating, or
    // every variant of a cache-capable model would read as cache-less.
    const upstreamId = normalized.slice('openai/'.length).split(':', 1)[0] ?? '';
    return openaiModelSupportsPromptCache(upstreamId);
  }
  if (normalized.startsWith('deepseek/')) return true;
  if (normalized.startsWith('anthropic/claude-')) return true;
  return false;
}

/** Only Anthropic Claude routes need an explicit cache_control block. */
export function openrouterRequiresExplicitPromptCache(modelId: string): boolean {
  return modelId.trim().toLowerCase().startsWith('anthropic/claude-');
}

/**
 * Native DeepSeek v4 thinks by default (recipe `thinking_by_default: true`,
 * #4172) and OpenRouter's DeepSeek hosts serve the same models — reasoning
 * bills as OUTPUT tokens against max_tokens, so output-cap sizing must grant
 * the same headroom on the OR route (#4758). Z.ai's GLM-4.5+/5.x think by
 * default too (zhipu recipe, gbrain#4727) and OR bills their reasoning as
 * completion tokens — same cutoff, same headroom under the `z-ai/` prefix.
 * Particle (`particle-ai/`) reasons by default as well and OR bills it as
 * completion tokens, so a thinking:'off' call needs the same headroom (GST-1977).
 */
export function openrouterThinkingByDefault(modelId: string): boolean {
  const normalized = modelId.trim().toLowerCase();
  if (normalized.startsWith('deepseek/') || normalized.startsWith('particle-ai/')) return true;
  return normalized.startsWith('z-ai/') && GLM_THINKING_BY_DEFAULT_RE.test(normalized);
}

/**
 * Which proxied families may drive the subagent loop. The gateway loop keys
 * replay on gbrain_tool_use_id, not the raw provider id, so a family only
 * needs a live abort/retry pin proving its tool-call envelope survives a
 * resume. Anthropic and DeepSeek have one (test/e2e/openrouter-*-subagent-
 * replay.live.test.ts); other families stay refused until they do
 * (TODOS.md OpenRouter follow-up). List lives in ../openrouter-families.ts.
 */
export function openrouterSupportsSubagentLoop(modelId: string): boolean {
  return openrouterModelSupportsSubagentLoop(modelId);
}

/**
 * Rewrite the last system message's string content into OpenRouter's
 * documented Anthropic caching shape: a content-part array carrying
 * `cache_control: { type: 'ephemeral' }` on the text block. (A top-level
 * body `cache_control` is NOT the OpenRouter format — OR forwards per-block
 * markers only.) Returns the input unchanged when it doesn't apply.
 */
function withSystemCacheControl(body: unknown): unknown {
  if (!body || typeof body !== 'object' || Array.isArray(body)) return body;
  const record = body as Record<string, unknown>;
  const model = typeof record.model === 'string' ? record.model : '';
  if (!openrouterRequiresExplicitPromptCache(model)) return body;
  const messages = Array.isArray(record.messages) ? record.messages : undefined;
  if (!messages) return body;
  let idx = -1;
  for (let i = 0; i < messages.length; i++) {
    const m = messages[i];
    if (m && typeof m === 'object' && (m as Record<string, unknown>).role === 'system') idx = i;
  }
  if (idx === -1) return body;
  const sys = messages[idx] as Record<string, unknown>;
  if (typeof sys.content !== 'string' || sys.content.length === 0) return body;
  const next = messages.slice();
  next[idx] = {
    ...sys,
    content: [{ type: 'text', text: sys.content, cache_control: { type: 'ephemeral' } }],
  };
  return { ...record, messages: next };
}

/**
 * OpenRouter reports upstream rate limits and some provider outages inside
 * an HTTP 200 body: `{ error: { message, code, metadata? } }` (#5473). The
 * AI SDK validates that body against the chat-completion schema and throws
 * an `APICallError` with `statusCode: 200`, so neither the SDK's
 * status-keyed retry nor gbrain's status-keyed classification sees the real
 * condition.
 *
 * Only a 200 `application/json` body whose integer `error.code` is 429 or
 * 5xx gets that code as its HTTP status. A success payload, an unparseable
 * body, a 4xx code, a non-integer code and any non-JSON (SSE) response pass
 * through untouched. An existing `Retry-After` header is kept as it is; a
 * finite non-negative `error.metadata.retry_after`/`retryAfter` is promoted
 * to one when absent. Fail-open: any parse problem returns the original
 * response.
 */
async function rewriteOpenRouterErrorEnvelopeStatus(res: Response): Promise<Response> {
  if (res.status !== 200) return res;
  if (!(res.headers.get('content-type') ?? '').includes('application/json')) return res;
  try {
    const text = await res.clone().text();
    const error = JSON.parse(text)?.error;
    const code = error?.code;
    if (!Number.isInteger(code)) return res;
    if (code !== 429 && (code < 500 || code >= 600)) return res;
    const headers = new Headers(res.headers);
    if (!headers.has('retry-after')) {
      const meta = error.metadata;
      const retryAfter = meta?.retry_after ?? meta?.retryAfter;
      if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter >= 0) {
        headers.set('retry-after', String(retryAfter));
      }
    }
    return new Response(text, { status: code, statusText: res.statusText, headers });
  } catch {
    return res;
  }
}

/**
 * Compat fetch: (1) honors the OPENROUTER_CACHE_HEADER marker by splicing an
 * Anthropic cache_control breakpoint onto the system block, then strips the
 * marker; (2) composes the native DeepSeek `reasoning_content` promote so
 * OpenRouter-hosted thinking models (DeepSeek V4, etc.) do not arrive at the
 * AI SDK adapter as empty `content` (#4753); (3) gives an HTTP-200
 * rate-limit or outage envelope its real status (#5473, see
 * `rewriteOpenRouterErrorEnvelopeStatus`). Fail-open: any parse problem
 * sends the original body or response unchanged. Tool-call turns are never
 * promoted (that logic lives in `deepseekReasoningContentCompatFetch`).
 *
 * @internal exported for tests. Cast through `unknown` because TS's
 * `typeof fetch` includes a `preconnect` member (matches azure-openai.ts).
 */
export const openrouterCompatFetch = (async (
  input: RequestInfo | URL,
  init?: RequestInit,
): Promise<Response> => {
  const promote = async (nextInit?: RequestInit): Promise<Response> =>
    rewriteOpenRouterErrorEnvelopeStatus(
      await deepseekReasoningContentCompatFetch(input as any, nextInit as any),
    );
  if (!init?.headers) return promote(init);
  const headers = new Headers(init.headers as any);
  if (!headers.has(OPENROUTER_CACHE_HEADER)) return promote(init);
  headers.delete(OPENROUTER_CACHE_HEADER);
  let body = init.body;
  if (typeof body === 'string') {
    try {
      const parsed = JSON.parse(body);
      const rewritten = withSystemCacheControl(parsed);
      if (rewritten !== parsed) {
        body = JSON.stringify(rewritten);
        headers.delete('content-length');
      }
    } catch {
      // Non-JSON body: let the provider surface the original problem.
    }
  }
  return promote({ ...init, headers, body } as any);
}) as unknown as typeof fetch;

/**
 * OpenRouter — single-key fan-out to OpenAI, Anthropic, Google, DeepSeek, and
 * dozens of other providers via a single OpenAI-compatible endpoint at
 * https://openrouter.ai/api/v1.
 *
 * One key, many models. Use `openrouter:<provider>/<model>` strings:
 *   openrouter:openai/gpt-5.2
 *   openrouter:anthropic/claude-sonnet-4.6
 *   openrouter:google/gemini-3-flash-preview
 *
 * Embeddings: OpenRouter exposes `/v1/embeddings` proxying OpenAI's
 * text-embedding-3-small (1536 dims) plus Matryoshka shrink via the SDK's
 * `dimensions` field. Catalog also includes text-embedding-3-large,
 * google/gemini-embedding-2-preview, qwen3-embedding-8b, and bge-m3 — users
 * opt in via `--embedding-model openrouter:<id>` (openai-compat tier accepts
 * arbitrary IDs at the gateway; recipe lists are advisory, not enforcing).
 *
 * Chat: `/v1/chat/completions` proxies every chat model OpenRouter routes,
 * with tool-calling per-model. The chat models list below is a curated entry
 * point — `supports_tools: true` reflects the OR endpoint's tool-call
 * envelope, not every individual model's capability. When in doubt about a
 * specific model, check https://openrouter.ai/models.
 *
 * Reranker: `/api/v1/rerank` proxies cross-encoder rerankers (Cohere v3.5/4-fast/4-pro
 * and NVIDIA Nemotron VL). Wire shape matches `gateway.rerank()`:
 * `{ query, documents, model }` → `{ results: [{ index, relevance_score }] }`.
 * Unlike embedding/chat, the reranker path strictly enforces the `models`
 * allowlist (no openai-compat bypass) — adding new rerank models requires a
 * recipe edit. Cohere bills per-search; the `cost_per_1m_tokens_usd` value
 * is a pseudo-rate for the budget tracker's `chars/4` heuristic.
 *
 * Attribution: OpenRouter recommends `HTTP-Referer` (required for app
 * attribution) + `X-OpenRouter-Title` (preferred; `X-Title` kept as
 * back-compat alias per OR docs). Defaults to `https://gbrain.ai` / `gbrain`;
 * forks override via `OPENROUTER_REFERER` / `OPENROUTER_TITLE` env vars so
 * downstream agent stacks (OpenClaw deployments, etc.) get their own
 * attribution on OR's leaderboard instead of polluting gbrain's.
 *
 * Subagent loops: Anthropic (`anthropic/…`) and DeepSeek (`deepseek/…`)
 * routes declare `supports_subagent_loop` so classifyCapabilities() allows
 * them, and the handler auto-routes those jobs through `gateway.toolLoop()`
 * (OR is not a native Anthropic provider, so the Messages SDK path is never
 * used for `openrouter:*`). Other OR families stay refused until they get a
 * live abort/retry pin (TODOS.md).
 */
export const openrouter: Recipe = {
  id: 'openrouter',
  name: 'OpenRouter',
  tier: 'openai-compat',
  implementation: 'openai-compatible',
  // No shipped rate for these yet: they warn and run under a default cap; a
  // user cap refuses them until `gbrain pricing set` registers one (X1 guard).
  unpriced_models: [
    'anthropic/claude-haiku-4.5',
    'google/gemini-3-flash-preview',
    'deepseek/deepseek-chat',
    'openai/gpt-5.2',
    'openai/gpt-5.2-chat',
    'openai/gpt-5.5',
    'anthropic/claude-sonnet-4.6',
    'anthropic/claude-opus-4.7',
    'cohere/rerank-v3.5',
    'cohere/rerank-4-fast',
    'cohere/rerank-4-pro',
    'nvidia/llama-nemotron-rerank-vl-1b-v2:free',
  ],
  base_url_default: 'https://openrouter.ai/api/v1',
  auth_env: {
    required: ['OPENROUTER_API_KEY'],
    optional: ['OPENROUTER_BASE_URL', 'OPENROUTER_REFERER', 'OPENROUTER_TITLE'],
    setup_url: 'https://openrouter.ai/settings/keys',
  },
  resolveDefaultHeaders(env) {
    const referer = env.OPENROUTER_REFERER ?? 'https://gbrain.ai';
    const title = env.OPENROUTER_TITLE ?? 'gbrain';
    return {
      // Required by OR for app-attribution. Without HTTP-Referer no leaderboard
      // entry is ever created (per https://openrouter.ai/docs/app-attribution).
      'HTTP-Referer': referer,
      // Current preferred name per OR docs (2026).
      'X-OpenRouter-Title': title,
      // Back-compat alias documented as still-supported.
      'X-Title': title,
    };
  },
  touchpoints: {
    embedding: {
      models: ['openai/text-embedding-3-small'],
      // #4114: per-model native dims for the catalog the docs invite users to
      // pick. The old recipe-wide `default_dims: 1536` was only right for
      // text-embedding-3-small — `migrate embeddings --to openrouter:bge-m3`
      // planned a 1536-wide column for a model that returns 1024. Slash-form
      // ids are the lookup key (embeddingDimsForModel strips only a leading
      // `provider:`, never the org slash). gemini-embedding-2-preview is
      // deliberately NOT listed: its width is unverified, and a plausible
      // guess is this exact bug class — unlisted ids resolve to 0, which
      // forces an explicit --dim / embedding_dimensions with a clear error.
      model_dims: {
        'openai/text-embedding-3-small': 1536,
        'openai/text-embedding-3-large': 3072,
        'qwen/qwen3-embedding-8b': 4096,
        'bge-m3': 1024,
        'baai/bge-m3': 1024,
      },
      // OpenRouter proxies arbitrary embedding models with widths we cannot
      // know ahead of time; 0 = no silent default for unlisted ids.
      default_dims: 0,
      trust_custom_dims: true,
      // text-embedding-3-small was trained at MRL breakpoints 512/1024/1536
      // (Weaviate analysis); 768 is a practical intermediate. Users opt into
      // a smaller dim via `gbrain config set embedding_dimensions <N>`.
      dims_options: [512, 768, 1024, 1536],
      cost_per_1m_tokens_usd: 0.02,
      price_last_verified: '2026-05-20',
      // OpenAI's published per-request aggregate is ~300K tokens for embeddings
      // (per-input cap is 8192). This is the AGGREGATE budget the gateway uses
      // to pre-split batches, NOT per-input. Per-input is enforced upstream.
      max_batch_tokens: 300_000,
    },
    // Expansion uses the same routed OpenAI-compatible language-model endpoint
    // as chat. Keep a small cheap/fast advisory set; the openai-compat tier
    // still accepts any user-configured OpenRouter provider/model ID.
    expansion: {
      models: [
        'anthropic/claude-haiku-4.5',
        'google/gemini-3-flash-preview',
        'deepseek/deepseek-chat',
      ],
      price_last_verified: '2026-05-20',
    },
    chat: {
      // Curated entry points (verified against OR's catalog 2026-05-20). The
      // openai-compat tier does NOT enforce this list at runtime — users can
      // pass any model ID OR routes. Refresh quarterly; see TODOS.md.
      models: [
        'openai/gpt-5.2',
        'openai/gpt-5.2-chat',
        'openai/gpt-5.5',
        'anthropic/claude-haiku-4.5',
        'anthropic/claude-sonnet-4.6',
        'anthropic/claude-opus-4.7',
        'google/gemini-3-flash-preview',
        'deepseek/deepseek-chat',
      ],
      supports_tools: true,
      supports_subagent_loop: openrouterSupportsSubagentLoop,
      // Family-scoped: OpenAI routes cache automatically; Anthropic routes
      // cache via the compat fetch shim's cache_control rewrite.
      supports_prompt_cache: openrouterSupportsPromptCache,
      // DeepSeek v4 via OpenRouter thinks by default (same as native
      // deepseek:). Other OR families stay default-off.
      thinking_by_default: openrouterThinkingByDefault,
      // No max_context_tokens: catalog spans 128K to 1M+; a single recipe-wide
      // value is either unsafe for smaller models or wasteful for larger ones.
      // Let upstream errors surface per-model.
      price_last_verified: '2026-05-20',
    },
    reranker: {
      models: [
        'cohere/rerank-v3.5',
        'cohere/rerank-4-fast',
        'cohere/rerank-4-pro',
        'nvidia/llama-nemotron-rerank-vl-1b-v2:free',
      ],
      default_model: 'cohere/rerank-v3.5',
      // Cohere bills per-search, not per-token. This is a pseudo-per-1M rate
      // for the budget tracker's heuristic (estimates tokens as chars/4).
      // At ~4K chars/search the tracker estimates ~$0.00025 — in the right
      // ballpark for the per-search bill. Patch budget-tracker.ts to honour a
      // `cost_per_search_usd` field for exact accounting.
      cost_per_1m_tokens_usd: 0.001,
      price_last_verified: '2026-06-13',
      max_payload_bytes: 5_000_000,
      // OR serves /rerank under /api/v1. base_url_default already ends in /v1,
      // so gateway concatenates to …/api/v1/rerank.
      path: '/rerank',
      // OpenRouter rerank is fast (<200 ms p50); 5 s covers cold path safely.
      default_timeout_ms: 5_000,
    },
  },
  setup_hint:
    'Get an API key at https://openrouter.ai/settings/keys, then `export OPENROUTER_API_KEY=...` or set `openrouter_api_key` in ~/.gbrain/config.json and use `openrouter:<provider>/<model>`. Optional overrides: OPENROUTER_BASE_URL (proxy), OPENROUTER_REFERER (attribution URL), OPENROUTER_TITLE (attribution name).',
  compat: { fetch: openrouterCompatFetch },
};