@worca/app 1.5.0-rc.3 → 1.6.0-rc.1

package/src/core/ask/web-proposal.mjs

@@ -0,0 +1,76 @@
+// src/core/ask/web-proposal.mjs
+// The ONE validator behind mcp__worca__propose_web_access, the event/notice text of the web card,
+// and the per-chat host list the cards record. The model asks to read a host that is not allowed
+// yet; the user answers "for this chat", "always" or declines (docs/guardrails.md "Web access").
+// Pure: the allowed list and the team cap are injected, so the MCP child validates for the model's
+// self-correction and the parent turn re-validates authoritatively and mints the card — the
+// clone-proposal.mjs split. Nothing here allows anything: the card route in ui/server.mjs does,
+// behind the user's click.
+import { checkWebUrl } from './web-fetch.mjs';
+import { ANY_HOST, hostAllowed } from '../web-allowlist.mjs';
+
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+// eslint-disable-next-line no-control-regex
+const BREAKS_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/g;
+const clip = (v, n) => String(v ?? '').replace(BREAKS_RE, ' ').slice(0, n);
+
+/**
+ * @param {object} r
+ * @param {() => string[]} r.allowed          this turn's effective allowlist (a card for an allowed host is pointless)
+ * @param {() => string[]|null} [r.teamCap]   the team allowlist cap, or null
+ */
+export function createWebValidator({ allowed, teamCap = () => null }) {
+  /** @returns {Promise<{ok:true, card:object}|{ok:false, errors:string[]}>} */
+  return async function validateWebProposal(input) {
+    const inp = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+    if (!str(inp.url)) return { ok: false, errors: ['url is required'] };
+    let url;
+    // Every URL rule except the allowlist (https, port, no credentials, no IP, no data in the URL):
+    // the card shows the exact URL, and a URL web_fetch would refuse anyway is never proposed.
+    try { url = checkWebUrl(str(inp.url), [ANY_HOST]); } catch (err) { return { ok: false, errors: [err.message] }; }
+    const host = url.hostname;
+    if (hostAllowed(host, allowed())) return { ok: false, errors: [`${host} is already allowed — call web_fetch instead`] };
+    const cap = teamCap();
+    if (Array.isArray(cap) && !hostAllowed(host, cap)) {
+      return { ok: false, errors: [`${host} is outside the team policy's web allowlist for this project — tell the user; a card cannot allow it`] };
+    }
+    const reason = clip(str(inp.reason), 200);
+    return { ok: true, card: {
+      type: 'web', kind: 'web', summary: `Read ${host}`, host, url: url.href.slice(0, 500),
+      ...(reason ? { reason } : {}),
+      change: { host },
+    } };
+  };
+}
+
+/** The hosts this chat's web cards allowed "for this chat" (the cards are the record). */
+export function chatWebHosts(messages) {
+  const out = [];
+  for (const m of messages || []) {
+    for (const b of Array.isArray(m?.blocks) ? m.blocks : []) {
+      if (b && b.kind === 'card' && b.state === 'applied' && b.card?.type === 'web' && b.card.result?.scope === 'chat'
+        && typeof b.card.host === 'string' && !out.includes(b.card.host)) out.push(b.card.host);
+    }
+  }
+  return out;
+}
+
+const eventText = (s, n) => clip(s, n).replace(/"/g, "'").replace(/\[(\/?)worca context\]/gi, '($1worca context)');
+
+/** `[worca event] …` — the synthetic turn's prompt after the user answered a web card. */
+export function webEventPrompt({ cardId, state, card = {}, result = null }) {
+  const summary = eventText(card.summary, 200);
+  const host = eventText(card.host, 253);
+  if (state === 'declined') return `[worca event] web card ${cardId} declined: do not fetch ${host} — answer without it; "${summary}"`;
+  if (state === 'failed') return `[worca event] web card ${cardId} failed: ${eventText(result?.error || 'unknown error', 300)}; "${summary}"`;
+  const scope = result?.scope === 'always' ? 'is on the allowlist from now on' : 'is allowed for this chat';
+  return `[worca event] web card ${cardId} applied: ${host} ${scope} — fetch it now; "${summary}"`;
+}
+
+/** The user-row notice above the event turn. */
+export function webNoticeText({ state, card = {}, result = null }) {
+  const host = clip(card.host, 253);
+  if (state === 'declined') return `Declined — ${clip(card.summary, 160)}`;
+  if (state === 'failed') return `Could not allow ${host}: ${clip(result?.error || 'unknown error', 200)}`;
+  return result?.scope === 'always' ? `Always allowing ${host}` : `Allowed ${host} for this chat`;
+}

package/src/core/auto/classify.mjs

@@ -8,6 +8,7 @@
 import { runClaude, mockEnabled } from '../claude-runner.mjs';
 import { resolveModelEnv, resolveModelCost } from '../config.mjs';
 import { safeParseJson } from '../protocol.mjs';
+import { classifyError } from '../recoverable-error.mjs';
 import { normalizeShape, ShapeError, cleanText, SHAPE_LIMITS } from '../../shared/graph/assemble.mjs';
 import { RECIPE_GUIDE, mockShapeFor } from './recipes.mjs';
 
@@ -27,7 +28,12 @@ export const VOCAB_LIMITS = Object.freeze({ maxAgents: 32, purpose: 300, role: 4
 export class ClassifierError extends Error {
   /** `costUsd`/`usage` = what the FAILED attempts already spent (two billed replies
    *  behind CLASSIFIER_FAILED, a partial reply behind a timeout): the caller books it. */
-  constructor(code, detail, issues = [], { costUsd = 0, usage = null } = {}) {
+  /** `errorClass` = the recovery class of the runner failure behind it
+   *  (recoverable-error.mjs), stamped so classifyError() reads it instead of sniffing
+   *  the wrapped message: a rate_limit/network cause is retried and, if it outlasts
+   *  the retries, the run falls back to the default workflow. Every other failure — a
+   *  timeout, an unusable reply — stays null and keeps the D17 error-pause. */
+  constructor(code, detail, issues = [], { costUsd = 0, usage = null, errorClass = null } = {}) {
     super(`${code === 'CLASSIFIER_TIMEOUT' ? 'the workflow classifier timed out' : 'the workflow classifier failed'}: ${detail}`);
     this.name = 'ClassifierError';
     this.code = code;
@@ -35,6 +41,7 @@ export class ClassifierError extends Error {
     this.issues = issues;
     this.costUsd = Number.isFinite(Number(costUsd)) ? Number(costUsd) : 0;
     this.usage = usage;
+    this.errorClass = errorClass;
   }
 }
 
@@ -146,7 +153,7 @@ export function shapeForPrompt(shape) {
   return { ...shape, stages: (Array.isArray(shape.stages) ? shape.stages : []).map((u) => (isObject(u) && Array.isArray(u.parallel) ? { ...u, parallel: u.parallel.map(flatStage) } : flatStage(u))) };
 }
 
-export function buildClassifierSystemPrompt({ agents = [], models = [], humanInLoop = true, repoLook = false } = {}) {
+export function buildClassifierSystemPrompt({ agents = [], models = [], humanInLoop = true, repoLook = false, requireModel = false } = {}) {
   const modelLines = models.filter((m) => m && !m.hidden).map((m) => `- ${m.id}${m.label && m.label !== m.id ? ` (${m.label})` : ''}: efforts ${(m.efforts || []).join('/')}`);
   return [
     'You design a worca workflow for ONE software task. Reply with exactly one fenced ```json block containing a shape object and nothing else.',
@@ -176,7 +183,10 @@ export function buildClassifierSystemPrompt({ agents = [], models = [], humanInL
     '',
     RECIPE_GUIDE,
     '',
-    '## Models (use only these ids; omit both "model" and "effort" to run on the default model — an effort without a model is rejected)',
+    requireModel
+      // Signed out (auto/runnable.mjs): the default model is the CLI's own and cannot run here.
+      ? '## Models (use only these ids; every stage MUST name one of these models — this install has no default model; an effort without a model is rejected)'
+      : '## Models (use only these ids; omit both "model" and "effort" to run on the default model — an effort without a model is rejected)',
     ...modelLines,
     'Tuning guide: planning and review stages deserve the strongest model at high effort; producer stages (checklist, decomposer) the cheapest; the implementer a strong model at medium or high effort; set fanOut only where allowed and only for wide tasks.',
     'size and signals are shown to the user as chips: keep them short and literal.',
@@ -216,7 +226,7 @@ export function parseShapeReply(text) {
 
 /** Catalog check of the per-stage model/effort picks; canonicalises the id casing IN PLACE.
  *  Hidden catalog entries are accepted (a hidden id still resolves), they are just never offered. */
-export function checkShapeModels(shape, models) {
+export function checkShapeModels(shape, models, { requireModel = false } = {}) {
   const byId = new Map((models || []).map((m) => [String(m.id).toLowerCase(), m]));
   const issues = [];
   for (const st of flat(shape)) {
@@ -228,6 +238,8 @@ export function checkShapeModels(shape, models) {
       if (t.effort !== undefined && !(m.efforts || []).includes(t.effort)) issues.push({ code: 'BAD_EFFORT', message: `stage "${st.id}": model ${m.id} has no effort "${t.effort}"`, stageId: st.id });
     } else if (t.effort !== undefined) {
       issues.push({ code: 'EFFORT_WITHOUT_MODEL', message: `stage "${st.id}": an effort needs a model`, stageId: st.id });
+    } else if (requireModel) {
+      issues.push({ code: 'MISSING_MODEL', message: `stage "${st.id}": needs a model — this install has no default model (Claude Code is not signed in)`, stageId: st.id });
     }
   }
   return issues;
@@ -247,7 +259,7 @@ export function withCardsSignal(shape, n) {
  */
 export async function classifyTask(input, deps = {}) {
   const {
-    taskText = '', extras = [], fingerprint = '', models = [], humanInLoop = true, feedback = [], priorShape = null, registry = {}, domain = null,
+    taskText = '', extras = [], fingerprint = '', models = [], humanInLoop = true, feedback = [], priorShape = null, registry = {}, domain = null, requireModel = false,
     model, modelEnv, cwd = process.cwd(), bin, mock = false, signal, envScrub, envAllowlist, maxAttempts = 2, repoLook = false, timeoutMs,
   } = input || {};
   const timeout = Number.isFinite(timeoutMs) ? timeoutMs : (repoLook ? REPO_LOOK_TIMEOUT_MS : CLASSIFIER_TIMEOUT_MS);
@@ -259,7 +271,7 @@ export async function classifyTask(input, deps = {}) {
     return { shape: withCardsSignal(normalizeShape(mockShapeFor(taskText, { humanInLoop })), agents.length), warnings: [], attempts: 0, costUsd: 0, usage, raw: '', model: model || null };
   }
   const known = new Set(agents.map((a) => a.key));
-  const systemPrompt = buildClassifierSystemPrompt({ agents, models, humanInLoop, repoLook });
+  const systemPrompt = buildClassifierSystemPrompt({ agents, models, humanInLoop, repoLook, requireModel });
   const nudge = repoLook ? ' Do not spend more tool calls: reply with the shape now.' : '';
   let fb = [...feedback];
   let prior = priorShape;
@@ -323,7 +335,7 @@ export async function classifyTask(input, deps = {}) {
         fb = [...fb, `Your previous attempt ran out of turns before replying with a shape.${nudge || ' Reply with the shape now.'}`];
         continue;
       }
-      throw new ClassifierError('CLASSIFIER_FAILED', err?.message || String(err), [], { costUsd, usage });
+      throw new ClassifierError('CLASSIFIER_FAILED', err?.message || String(err), [], { costUsd, usage, errorClass: classifyError(err) });
     } finally {
       clearTimeout(timer);
       if (signal) signal.removeEventListener?.('abort', onOuterAbort);
@@ -338,7 +350,7 @@ export async function classifyTask(input, deps = {}) {
       try { shape = normalizeShape(raw); } catch (e) { if (e instanceof ShapeError) issues = e.issues; else throw e; }
       if (shape) {
         for (const st of flat(shape)) if (!known.has(st.agent)) issues.push({ code: 'UNKNOWN_AGENT', message: `stage "${st.id}": unknown agent "${st.agent}"`, stageId: st.id });
-        issues.push(...checkShapeModels(shape, models));
+        issues.push(...checkShapeModels(shape, models, { requireModel }));
       }
     }
     if (!issues.length) return { shape: withCardsSignal(shape, agents.length), warnings, attempts: attempt, costUsd, usage, raw: text, model: model || null };

package/src/core/auto/runnable.mjs

@@ -0,0 +1,28 @@
+// src/core/auto/runnable.mjs
+// The models Auto may design with: the ones this install can actually RUN. A bridged model
+// whose provider is not set up never is. With Claude Code signed out (a hosted worca that
+// reaches models only through OpenRouter or a gateway), a first-party id is not either — and
+// neither is "the default model" a stage without one falls back to, since that is the CLI's
+// own. So signed out, only endpoint-routed / bridged models are offered and every stage must
+// name one. An unknown sign-in state (mock, a probe that could not run) narrows nothing.
+
+/**
+ * @param {Array<{id:string, bridged?:string, needsSignIn?:boolean}>} models  listModels() output
+ * @param {{auth:'signed-in'|'signed-out'|'unknown', routed:(id:string)=>boolean}} o
+ * @returns {{models:Array, requireModel:boolean, note:(string|null)}}
+ */
+export function autoModelsFor(models, { auth, routed }) {
+  const ready = (Array.isArray(models) ? models : []).filter((m) => m && !m.needsSignIn);
+  if (auth !== 'signed-out') return { models: ready, requireModel: false, note: null };
+  const usable = ready.filter((m) => routed(m.id));
+  if (!usable.length) {
+    return {
+      models: ready, requireModel: false,
+      note: "Claude Code isn't signed in and no endpoint or provider model is set up — the run's first-party models will fail; sign in, or add a model under Settings › Providers.",
+    };
+  }
+  return {
+    models: usable, requireModel: true,
+    note: `Claude Code isn't signed in — Auto designs with the ${usable.length} model${usable.length === 1 ? '' : 's'} routed through an endpoint or provider, and names one on every stage.`,
+  };
+}

package/src/core/billing.mjs

@@ -0,0 +1,53 @@
+// src/core/billing.mjs
+// Who pays for a spawn (plans/credential-broker-design.html §5.5): the person
+// whose action caused it. The server sets the acting person once per request
+// (ui/server.mjs) and around a run's own loop (run-harness.mjs); every claude spawn
+// started inside that async context is billed to them, without threading a
+// parameter through every call site. An explicit `billTo` on a spawn still wins.
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const als = new AsyncLocalStorage();
+
+/** A usable bill-to: a lower-cased email, 'local', or null. */
+export function normalizeBillTo(v) {
+  const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
+  if (!s) return null;
+  if (s === 'local') return 'local';
+  return /^[^\s@<>]{1,200}@[^\s@<>]{1,200}$/.test(s) ? s : null;
+}
+
+/**
+ * Run `fn` with `billTo` as the acting person (an unusable value leaves the context unset).
+ * `owner` is whose work it is — whose agent user (agent-pool.mjs) its processes run as.
+ * It defaults to the payer; a resumed run pays as the resumer but keeps its starter's
+ * agent user, where Claude Code keeps the run's sessions.
+ */
+export function withBillTo(billTo, fn, { owner } = {}) {
+  const b = normalizeBillTo(billTo);
+  return als.run({ billTo: b, owner: owner === undefined ? b : normalizeBillTo(owner) }, fn);
+}
+
+/** Enter `billTo` for the rest of the current synchronous execution and its async continuations (Express middleware). */
+export function enterBillTo(billTo) {
+  const b = normalizeBillTo(billTo);
+  als.enterWith({ billTo: b, owner: b });
+}
+
+/** The acting person in this async context, or null. */
+export function currentBillTo() {
+  return als.getStore()?.billTo ?? null;
+}
+
+/** Whose work this async context is (see withBillTo), or null. */
+export function currentOwner() {
+  const s = als.getStore();
+  return s ? (s.owner ?? s.billTo ?? null) : null;
+}
+
+/**
+ * The person a spawn is billed to: an explicit value, else the async context,
+ * else WORCA_BROKER_SYSTEM_BILL_TO, else null (the caller refuses in multi mode).
+ */
+export function resolveBillTo(explicit, env = process.env) {
+  return normalizeBillTo(explicit) || currentBillTo() || normalizeBillTo(env.WORCA_BROKER_SYSTEM_BILL_TO) || null;
+}

package/src/core/bridge/errors.mjs

@@ -18,16 +18,58 @@ export function anthropicError(status, type, message) {
   return { status, body: { type: 'error', error: { type, message: String(message || type) } } };
 }
 
-/** Pull a human message out of an upstream error body (JSON or text). */
+const MESSAGE_MAX = 500;
+
+/** A provider's own error text: a JSON body's message, else the text itself. */
+function rawProviderText(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return '';
+  try {
+    const j = JSON.parse(raw);
+    const e = j && (j.error || j);
+    if (e && typeof e === 'object' && typeof e.message === 'string') return e.message;
+    if (typeof e === 'string') return e;
+  } catch { /* plain text */ }
+  return raw.trim();
+}
+
+/**
+ * Pull a human message out of an upstream error body (JSON or text). A router
+ * (OpenRouter) answers with a generic `message` ("Provider returned error") and
+ * puts the provider's own explanation in `error.metadata.raw` — the line that
+ * says what to do (rate-limited upstream: retry, or bring your own key) — so
+ * the two are joined. Capped: a provider can return a whole HTML page.
+ */
 export function upstreamMessage(text) {
   if (!text) return '';
   try {
     const j = JSON.parse(text);
     const e = j && (j.error || j);
-    if (e && typeof e === 'object') return e.message || e.msg || e.code || JSON.stringify(e);
-    if (typeof e === 'string') return e;
+    if (e && typeof e === 'object') {
+      const base = e.message || e.msg || e.code || '';
+      const raw = rawProviderText(e.metadata && e.metadata.raw);
+      const joined = raw && raw !== base ? (base ? `${base} — ${raw}` : raw) : String(base);
+      return (joined || JSON.stringify(e)).slice(0, MESSAGE_MAX);
+    }
+    if (typeof e === 'string') return e.slice(0, MESSAGE_MAX);
   } catch { /* not JSON */ }
-  return String(text).slice(0, 500);
+  return String(text).slice(0, MESSAGE_MAX);
+}
+
+/** What a router (OpenRouter) says beside an error: the provider that answered, and whose limit it hit. */
+function routerMetadata(text) {
+  try {
+    const m = JSON.parse(text)?.error?.metadata;
+    if (!m || typeof m !== 'object') return {};
+    // A rate limit's own headers ride the body too: X-RateLimit-Reset is when it lifts (ms).
+    const h = m.headers && typeof m.headers === 'object' ? m.headers : {};
+    const resetRaw = Object.entries(h).find(([k]) => k.toLowerCase() === 'x-ratelimit-reset')?.[1];
+    const reset = Number(resetRaw);
+    return {
+      providerName: typeof m.provider_name === 'string' ? m.provider_name : '',
+      limitSource: typeof m.limit_source === 'string' ? m.limit_source : '',
+      resetAt: Number.isFinite(reset) && reset > 1e12 ? new Date(reset).toISOString() : '',
+    };
+  } catch { return {}; }
 }
 
 /** The machine-readable code in an upstream error body ('' when there is none). */
@@ -50,6 +92,9 @@ export function unsupportedApiFix(provider) {
     : 'this model needs a different API: change its API in the model editor';
 }
 
+/** A 403 body that is about the credential itself (bad, expired or unscoped key) — still an auth failure. */
+const AUTH_403_RE = /\b(api[ _-]?key|token|credential|unauthori[sz]ed|authenticat|invalid key|expired|revoked|sign(ed)? ?in|log(ged)? ?in)/i;
+
 /** Error codes for a prompt past the model's context window: OpenAI's, and Copilot's own limit check. */
 const CONTEXT_CODES = new Set(['context_length_exceeded', 'model_max_prompt_tokens_exceeded']);
 
@@ -84,11 +129,38 @@ export function isFailedResponseOverflow(code, message) {
 export function mapUpstreamError(status, text, { provider = 'upstream', retryAfter } = {}) {
   const msg = upstreamMessage(text);
   const who = provider;
+  // The credential broker's own refusals (a missing key, a spent cap, a dead token) keep
+  // their 403 and their words: re-wrapped as a 401 the CLI would retry for minutes, and the
+  // `worca-broker:` prefix is what run pauses and the key-page hint key on.
+  if (/^worca-broker:/.test(msg)) {
+    const type = /quota reached|not allowed/.test(msg) ? 'permission_error' : 'authentication_error';
+    return anthropicError(status === 429 ? 429 : 403, status === 429 ? 'rate_limit_error' : type, msg);
+  }
+  // A 403 whose body names something other than the credential is a POLICY
+  // refusal (OpenRouter gates some :free models to listed agent apps: "only
+  // available on agentic harnesses"). Calling that an auth failure sends the
+  // user to re-enter a key that works; the body is the real reason, and it is
+  // permanent, so nothing downstream classifies it as retryable. It reaches the
+  // CLI as a 400: the CLI reads ANY 403 from its endpoint as a sign-in failure
+  // ("Failed to authenticate" / "Not logged in · Please run /login") and buries
+  // the reason under it.
+  if (status === 403 && /[a-z]{3}/i.test(msg) && !AUTH_403_RE.test(msg)) {
+    return anthropicError(400, 'invalid_request_error', `${who}: refused (403) — ${msg}`);
+  }
   if (status === 401 || status === 403) {
     return anthropicError(401, 'authentication_error', `${who}: authentication failed (${status})${msg ? ` — ${msg}` : ''}`);
   }
   if (status === 429) {
-    const e = anthropicError(429, 'rate_limit_error', `${who}: rate limited (429)${msg ? ` — ${msg}` : ''}`);
+    // A router's 429 can come from a pool every one of its users shares
+    // (OpenRouter's `:free` models), not from this install's traffic: name the
+    // provider behind it and the limit's source, so the run surfaces can say
+    // that lowering Max concurrent requests will not help.
+    const { providerName, limitSource, resetAt } = routerMetadata(text);
+    const via = providerName ? ` via ${providerName}` : '';
+    const source = limitSource ? ` [${limitSource}]` : '';
+    // When the limit lifts, if the router said: a daily allowance pauses the run until then.
+    const reset = resetAt ? ` resets ${resetAt}` : '';
+    const e = anthropicError(429, 'rate_limit_error', `${who}: rate limited (429)${via}${msg ? ` — ${msg}` : ''}${source}${reset}`);
     if (retryAfter) e.headers = { 'retry-after': String(retryAfter) };
     return e;
   }

package/src/core/bridge/openrouter.mjs

@@ -0,0 +1,59 @@
+// src/core/bridge/openrouter.mjs
+// OpenRouter's dialect of chat completions (docs/models.md › OpenRouter). The
+// wire protocol is OpenAI's, so an OpenRouter model is an ordinary `openai`
+// provider entry; what differs is decided by the base URL alone:
+//   - `usage: {include: true}` — the reply's usage then carries the call's USD
+//     `cost`, which the bridge books under the run's tag (the CLI prices a
+//     bridged id at $0);
+//   - `reasoning: {effort}` — OpenRouter's one reasoning knob for every model,
+//     where OpenAI's `reasoning_effort` is honoured only by some;
+//   - `max_tokens` — OpenRouter's name for the output cap on every model;
+//   - the entry's `upstream.openrouter` routing: `provider` preferences and the
+//     `models` fallback list, tried when the first model is rate-limited or down;
+//   - attribution headers, so worca's traffic is named on the OpenRouter dashboard.
+// Pure; zero imports beyond the model-env leaf.
+
+import { isOpenRouterBaseUrl } from '../model-env.mjs';
+
+/** Whether a base URL is OpenRouter's (openrouter.ai or a subdomain). */
+export const isOpenRouter = isOpenRouterBaseUrl;
+
+/**
+ * OpenRouter app attribution (openrouter.ai/docs/app-attribution): every install
+ * reports as the one Worca app. HTTP-Referer is what creates the app page; the
+ * title rides both spellings (X-Title is the older one); categories come from
+ * OpenRouter's fixed list, at most two per request (unknown ones are dropped).
+ * Only ever Worca's own identity — never another listed app's referer. No
+ * X-OpenRouter-App-Visibility: Worca is listed publicly (OpenRouter's default),
+ * and that header only counts on the request that creates the app anyway.
+ */
+export const OPENROUTER_HEADERS = Object.freeze({
+  'HTTP-Referer': 'https://worca.dev',
+  'X-Title': 'Worca',
+  'X-OpenRouter-Title': 'Worca',
+  'X-OpenRouter-Categories': 'cloud-agent,cli-agent',
+});
+
+/**
+ * A translated chat/completions body, adapted for OpenRouter. Never mutates
+ * `body`.
+ * @param {object} body  toChatRequest's output
+ * @param {{openrouter?: {models?:string[], provider?:object}}} upstream  the entry's upstream settings
+ * @returns {object}
+ */
+export function adaptOpenRouterChatBody(body, upstream = {}) {
+  const out = { ...body };
+  if (out.reasoning_effort) {
+    out.reasoning = { effort: out.reasoning_effort };
+    delete out.reasoning_effort;
+  }
+  if (out.max_completion_tokens !== undefined) {
+    out.max_tokens = out.max_completion_tokens;
+    delete out.max_completion_tokens;
+  }
+  out.usage = { include: true };
+  const or = upstream && upstream.openrouter;
+  if (or && Array.isArray(or.models) && or.models.length) out.models = [...or.models];
+  if (or && or.provider && typeof or.provider === 'object') out.provider = { ...or.provider };
+  return out;
+}