@vantran-se/openchamber-web 1.23.1 → 1.24.4

package/server/lib/routing/runtime.js

@@ -0,0 +1,217 @@
+/**
+ * Owns Jev routing at runtime: whether Auto is ready, rewriting a prompt body
+ * that names the `openchamber/auto` model, and the safety net consulted before
+ * a permission is auto-accepted. Every failure path keeps the user's own
+ * behaviour: a prompt goes to the fallback model, a permission is accepted as
+ * auto-accept would have, and the UI is told why.
+ */
+import { createOpencodeClient } from '@opencode-ai/sdk/v2';
+import { z } from 'zod';
+import { isRoutingFeatureAvailable } from './feature-flag.js';
+import { BUILTIN_CATEGORIES, isAutoModel } from './defaults.js';
+import { createRoutingStore, parseEffectiveConfig } from './store.js';
+import { buildPermissionRequest, buildRoutingRequest, createJevClient, decidePermission, decideRouting } from './jev.js';
+import { loadRoutingHistory } from './history.js';
+
+const HISTORY_TIMEOUT_MS = 2500;
+/** A held permission is remembered so reconnect reconciliation does not re-ask Jev. */
+const PERMISSION_DECISION_TTL_MS = 15 * 60 * 1000;
+
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+
+const textPartSchema = z.object({ type: z.literal('text'), text: z.string(), synthetic: z.boolean().optional() });
+const commandBodySchema = z.object({ command: z.string(), arguments: z.string().optional() });
+const promptBodySchema = z.object({ parts: z.array(z.unknown()).optional() });
+
+/** The user's words for this send: text parts the composer authored, or the slash command. */
+export const requestTextOf = (body) => {
+  const command = commandBodySchema.safeParse(body);
+  if (command.success) {
+    const args = command.data.arguments?.trim();
+    return `/${command.data.command}${args ? ` ${args}` : ''}`;
+  }
+  const prompt = promptBodySchema.safeParse(body);
+  const parts = prompt.success ? prompt.data.parts ?? [] : [];
+  return parts
+    .map((part) => textPartSchema.safeParse(part))
+    .filter((part) => part.success && !part.data.synthetic)
+    .map((part) => part.data.text)
+    .join('\n\n')
+    .trim();
+};
+
+export function createRoutingRuntime({
+  dataDir,
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  broadcastGlobalUiEvent,
+  fetchImpl = fetch,
+  store = createRoutingStore({ dataDir }),
+  jev = createJevClient({ fetchImpl }),
+  now = Date.now,
+}) {
+  const permissionDecisions = new Map();
+
+  const broadcast = (type, properties) => {
+    try {
+      broadcastGlobalUiEvent?.({ type, properties });
+    } catch (error) {
+      console.warn(`[routing] failed to broadcast ${type}:`, errorMessage(error));
+    }
+  };
+
+  const enabledCategories = (config) => config.categories.filter((category) => category.enabled);
+
+  /** What the client needs to decide whether to offer Auto and what the settings page shows. */
+  const describe = async () => {
+    const available = isRoutingFeatureAvailable();
+    if (!available) return { available: false, autoReady: false, tokenPresent: false, config: null, builtins: [] };
+    const [config, token] = await Promise.all([store.readConfig(), store.readToken()]);
+    const tokenPresent = Boolean(token);
+    const autoReady = config.enabled && tokenPresent && Boolean(config.fallback) && enabledCategories(config).length >= 2;
+    // Built-in text travels with the config so "Reset" in Settings restores the shipped wording.
+    return { available, autoReady, tokenPresent, config, builtins: BUILTIN_CATEGORIES };
+  };
+
+  const publishUpdated = async () => {
+    const state = await describe();
+    broadcast('openchamber:routing.updated', { available: state.available, autoReady: state.autoReady, tokenPresent: state.tokenPresent });
+    return state;
+  };
+
+  const readHistory = async ({ sessionId, directory }) => {
+    const baseUrl = buildOpenCodeUrl('/', '').replace(/\/$/, '');
+    const client = createOpencodeClient({ baseUrl, headers: getOpenCodeAuthHeaders(), throwOnError: true });
+    const signal = AbortSignal.timeout(HISTORY_TIMEOUT_MS);
+    return loadRoutingHistory({
+      signal,
+      readPage: (page) => client.session.messages({ sessionID: sessionId, directory, ...page }, { signal }),
+    });
+  };
+
+  // A category without a model of its own means "the fallback pair"; a variant
+  // only travels with the model it was chosen for.
+  const applyChoice = (body, config, choice) => {
+    const own = Boolean(choice?.model);
+    const model = own ? choice.model : config.fallback.model;
+    const variant = own ? choice.variant : config.fallback.variant;
+    // Keep the wire shape the route uses: a string on /command, an object on the prompt routes.
+    body.model = z.string().safeParse(body.model).success
+      ? `${model.providerID}/${model.modelID}`
+      : { providerID: model.providerID, modelID: model.modelID };
+    if (variant) body.variant = variant;
+    else delete body.variant;
+    if (choice?.agent) body.agent = choice.agent;
+    return { providerID: model.providerID, modelID: model.modelID, variant: variant ?? null, agent: choice?.agent ?? null };
+  };
+
+  /**
+   * Rewrites `body.model` in place when it is the Auto sentinel. Returns the
+   * decision that was applied, or null when the body named a real model.
+   * Throws only when Auto cannot be honoured at all (no fallback configured):
+   * the sentinel must never reach OpenCode.
+   */
+  const resolvePromptBody = async (body, { sessionId, directory }) => {
+    if (!isAutoModel(body?.model)) return null;
+    const state = await describe();
+    const config = state.config;
+    if (!config?.fallback) {
+      throw Object.assign(new Error('Auto routing is selected but no fallback model is configured'), { status: 400 });
+    }
+    const decision = { sessionId, at: now(), category: null, confidence: 0, reason: 'not-ready', ms: 0 };
+    if (state.autoReady) {
+      const request = requestTextOf(body);
+      let history = [];
+      try {
+        history = await readHistory({ sessionId, directory });
+      } catch (error) {
+        console.warn('[routing] history unavailable, routing on the request alone:', errorMessage(error));
+      }
+      try {
+        const token = await store.readToken();
+        const { answers, ms } = await jev.ask(buildRoutingRequest({ categories: enabledCategories(config), history, request }), token);
+        const result = decideRouting(answers.category, { categories: enabledCategories(config), minConfidence: config.minConfidence });
+        decision.category = result.category?.id ?? null;
+        decision.confidence = result.confidence;
+        decision.reason = result.reason;
+        decision.ms = ms;
+        Object.assign(decision, applyChoice(body, config, result.category));
+      } catch (error) {
+        decision.reason = 'error';
+        decision.error = errorMessage(error);
+        Object.assign(decision, applyChoice(body, config, null));
+      }
+    } else {
+      Object.assign(decision, applyChoice(body, config, null));
+    }
+    broadcast('openchamber:routing.decision', decision);
+    return decision;
+  };
+
+  /**
+   * Consulted by permission auto-accept before it replies. `accept` keeps the
+   * reply; `hold` leaves the request for the user; `skipped` is `accept` with
+   * a reason the UI surfaces (Jev unreachable, bad key).
+   */
+  const evaluatePermission = async (permission, directory) => {
+    if (!permission?.id) return { action: 'accept' };
+    const cached = permissionDecisions.get(permission.id);
+    if (cached && now() - cached.at < PERMISSION_DECISION_TTL_MS) return cached.result;
+    const state = await describe();
+    if (!state.available || !state.config?.enabled || !state.config.safetyNet.enabled || !state.tokenPresent) return { action: 'accept' };
+    let result;
+    try {
+      const token = await store.readToken();
+      const { answers } = await jev.ask(buildPermissionRequest(permission), token);
+      const verdict = decidePermission(answers, { threshold: state.config.safetyNet.threshold });
+      result = verdict.hold
+        ? { action: 'hold', score: verdict.score, kind: verdict.kind }
+        : { action: 'accept', score: verdict.score, kind: verdict.kind };
+      if (verdict.hold) {
+        broadcast('openchamber:routing.permission-held', {
+          permissionId: permission.id, sessionId: permission.sessionID, directory: directory ?? null, score: verdict.score, kind: verdict.kind,
+        });
+      }
+    } catch (error) {
+      result = { action: 'accept', skipped: errorMessage(error) };
+      broadcast('openchamber:routing.safety-skipped', {
+        permissionId: permission.id, sessionId: permission.sessionID, directory: directory ?? null, error: result.skipped,
+      });
+    }
+    permissionDecisions.set(permission.id, { at: now(), result });
+    return result;
+  };
+
+  const forgetPermission = (permissionId) => {
+    permissionDecisions.delete(permissionId);
+  };
+
+  const updateConfig = async (input) => {
+    const config = parseEffectiveConfig(input);
+    await store.writeConfig(config);
+    return publishUpdated();
+  };
+
+  const setToken = async (token) => {
+    const parsed = z.string().trim().min(1).max(4000).safeParse(token);
+    if (!parsed.success) throw Object.assign(new Error('A Jev API key is required'), { status: 400 });
+    await store.writeToken(parsed.data);
+    return publishUpdated();
+  };
+
+  const clearToken = async () => {
+    await store.clearToken();
+    return publishUpdated();
+  };
+
+  /** Held permissions the UI can read back after a reload. */
+  const heldPermissions = () => {
+    const held = [];
+    for (const [permissionId, entry] of permissionDecisions) {
+      if (entry.result.action === 'hold') held.push({ permissionId, score: entry.result.score, kind: entry.result.kind });
+    }
+    return held;
+  };
+
+  return { describe, resolvePromptBody, evaluatePermission, forgetPermission, heldPermissions, updateConfig, setToken, clearToken };
+}

package/server/lib/routing/runtime.test.js

@@ -0,0 +1,188 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createRoutingRuntime, requestTextOf } from './runtime.js';
+import { resolveEffectiveConfig } from './store.js';
+import { excerptHead, excerptHeadTail, turnsToHistory } from './history.js';
+import { decidePermission, decideRouting } from './jev.js';
+
+const AUTO = { providerID: 'openchamber', modelID: 'auto' };
+const FALLBACK = { model: { providerID: 'anthropic', modelID: 'claude-sonnet-5' }, variant: 'medium' };
+
+const readyConfig = () => {
+  const config = resolveEffectiveConfig(null);
+  config.enabled = true;
+  config.fallback = FALLBACK;
+  config.safetyNet = { enabled: true, threshold: 0.6 };
+  config.categories = config.categories.map((c) => (c.id === 'hard'
+    ? { ...c, model: { providerID: 'openai', modelID: 'gpt-6-astra' }, variant: 'high', agent: 'plan' }
+    : c));
+  return config;
+};
+
+const makeRuntime = ({ config = readyConfig(), token = 'key', answers, askError, flag = '1' } = {}) => {
+  process.env.OPENCHAMBER_ROUTING_ENABLE = flag;
+  const events = [];
+  const store = {
+    readConfig: vi.fn(async () => config),
+    writeConfig: vi.fn(async (next) => next),
+    readToken: vi.fn(async () => token),
+    writeToken: vi.fn(async () => undefined),
+    clearToken: vi.fn(async () => undefined),
+  };
+  const jev = { ask: vi.fn(async () => { if (askError) throw askError; return { answers, ms: 12 }; }) };
+  const runtime = createRoutingRuntime({
+    dataDir: '/unused',
+    buildOpenCodeUrl: () => 'http://127.0.0.1:1/',
+    getOpenCodeAuthHeaders: () => ({}),
+    broadcastGlobalUiEvent: (event) => events.push(event),
+    store,
+    jev,
+  });
+  return { runtime, store, jev, events };
+};
+
+describe('requestTextOf', () => {
+  it('joins authored text parts and ignores synthetic ones and files', () => {
+    expect(requestTextOf({ parts: [
+      { type: 'text', text: 'fix the typo' },
+      { type: 'text', text: 'injected', synthetic: true },
+      { type: 'file', url: 'data:...' },
+      { type: 'text', text: 'in README' },
+    ] })).toBe('fix the typo\n\nin README');
+  });
+  it('renders a slash command with its arguments', () => {
+    expect(requestTextOf({ command: 'review', arguments: ' 3650 ' })).toBe('/review 3650');
+  });
+});
+
+describe('history excerpts', () => {
+  it('keeps the head of a user message and head plus tail of an answer', () => {
+    const long = 'a'.repeat(1000);
+    expect(excerptHead(long, 600)).toBe(`${'a'.repeat(600)} […]`);
+    expect(excerptHeadTail(`${'h'.repeat(400)}${'m'.repeat(400)}${'t'.repeat(400)}`, 300, 300)).toBe(`${'h'.repeat(300)} […] ${'t'.repeat(300)}`);
+    expect(excerptHead('short', 600)).toBe('short');
+  });
+  it('flattens the last three turns oldest first', () => {
+    const turns = [1, 2, 3, 4].map((n) => ({ user: { text: `u${n}` }, assistant: { text: `a${n}` } }));
+    expect(turnsToHistory(turns)).toEqual([
+      { role: 'user', text: 'u2' }, { role: 'assistant', text: 'a2' },
+      { role: 'user', text: 'u3' }, { role: 'assistant', text: 'a3' },
+      { role: 'user', text: 'u4' }, { role: 'assistant', text: 'a4' },
+    ]);
+  });
+});
+
+describe('decisions', () => {
+  const categories = readyConfig().categories;
+  it('routes a confident known category and falls back otherwise', () => {
+    expect(decideRouting({ choice: 'hard', confidence: 0.9 }, { categories, minConfidence: 0.6 }).reason).toBe('routed');
+    expect(decideRouting({ choice: 'hard', confidence: 0.4 }, { categories, minConfidence: 0.6 })).toMatchObject({ category: null, reason: 'low-confidence' });
+    expect(decideRouting({ choice: 'nope', confidence: 0.99 }, { categories, minConfidence: 0.6 })).toMatchObject({ category: null, reason: 'unknown-category' });
+  });
+  it('holds a permission at or above the threshold', () => {
+    expect(decidePermission({ ask: { noul: 0.61 }, kind: { choice: 'git_history' } }, { threshold: 0.6 })).toEqual({ hold: true, score: 0.61, kind: 'git_history' });
+    expect(decidePermission({ ask: { noul: 0.2 }, kind: { choice: 'read_only' } }, { threshold: 0.6 }).hold).toBe(false);
+    expect(() => decidePermission({}, { threshold: 0.6 })).toThrow(/ask score/);
+  });
+});
+
+describe('resolvePromptBody', () => {
+  it('leaves a real model untouched and does not consult Jev', async () => {
+    const { runtime, jev } = makeRuntime({ answers: {} });
+    const body = { model: { providerID: 'anthropic', modelID: 'claude-opus-5' }, parts: [] };
+    expect(await runtime.resolvePromptBody(body, { sessionId: 's1' })).toBeNull();
+    expect(body.model.modelID).toBe('claude-opus-5');
+    expect(jev.ask).not.toHaveBeenCalled();
+  });
+
+  it('rewrites the sentinel with the routed category model, variant and agent', async () => {
+    const { runtime, events } = makeRuntime({ answers: { category: { choice: 'hard', confidence: 0.97 } } });
+    const body = { model: AUTO, variant: 'low', agent: 'build', parts: [{ type: 'text', text: 'find the root cause' }] };
+    const decision = await runtime.resolvePromptBody(body, { sessionId: 's1' });
+    expect(body).toMatchObject({ model: { providerID: 'openai', modelID: 'gpt-6-astra' }, variant: 'high', agent: 'plan' });
+    expect(decision).toMatchObject({ category: 'hard', reason: 'routed', confidence: 0.97 });
+    expect(events.at(-1)).toMatchObject({ type: 'openchamber:routing.decision', properties: { sessionId: 's1', category: 'hard' } });
+  });
+
+  it('rewrites the string sentinel the command route sends, keeping the string shape', async () => {
+    const { runtime } = makeRuntime({ answers: { category: { choice: 'hard', confidence: 0.97 } } });
+    const body = { model: 'openchamber/auto', command: 'review', arguments: '3650' };
+    await runtime.resolvePromptBody(body, { sessionId: 's1' });
+    expect(body.model).toBe('openai/gpt-6-astra');
+    expect(body.agent).toBe('plan');
+  });
+
+  it('uses the fallback and keeps the composer agent when the category has no model', async () => {
+    const { runtime } = makeRuntime({ answers: { category: { choice: 'trivial', confidence: 0.99 } } });
+    const body = { model: AUTO, variant: 'high', agent: 'build', parts: [{ type: 'text', text: 'fix typo' }] };
+    await runtime.resolvePromptBody(body, { sessionId: 's1' });
+    expect(body).toMatchObject({ model: FALLBACK.model, variant: 'medium', agent: 'build' });
+  });
+
+  it('falls back on low confidence and on a Jev failure, and records why', async () => {
+    const low = makeRuntime({ answers: { category: { choice: 'hard', confidence: 0.3 } } });
+    const body = { model: AUTO, parts: [] };
+    expect((await low.runtime.resolvePromptBody(body, { sessionId: 's1' })).reason).toBe('low-confidence');
+    expect(body.model).toEqual(FALLBACK.model);
+
+    const failing = makeRuntime({ askError: Object.assign(new Error('Jev responded 401'), { status: 401 }) });
+    const body2 = { model: AUTO, parts: [] };
+    const decision = await failing.runtime.resolvePromptBody(body2, { sessionId: 's1' });
+    expect(decision).toMatchObject({ reason: 'error', error: 'Jev responded 401' });
+    expect(body2.model).toEqual(FALLBACK.model);
+  });
+
+  it('falls back without asking Jev while Auto is not ready, and refuses without a fallback', async () => {
+    const config = readyConfig();
+    config.enabled = false;
+    const notReady = makeRuntime({ config, answers: {} });
+    const body = { model: AUTO, parts: [] };
+    expect((await notReady.runtime.resolvePromptBody(body, { sessionId: 's1' })).reason).toBe('not-ready');
+    expect(body.model).toEqual(FALLBACK.model);
+    expect(notReady.jev.ask).not.toHaveBeenCalled();
+
+    const noFallback = makeRuntime({ config: { ...readyConfig(), fallback: null }, answers: {} });
+    await expect(noFallback.runtime.resolvePromptBody({ model: AUTO, parts: [] }, { sessionId: 's1' })).rejects.toMatchObject({ status: 400 });
+  });
+});
+
+describe('evaluatePermission', () => {
+  const permission = { id: 'p1', sessionID: 's1', permission: 'bash', patterns: ['git push --force'], metadata: { command: 'git push --force origin main' } };
+
+  it('holds a risky permission and remembers the decision', async () => {
+    const { runtime, jev, events } = makeRuntime({ answers: { ask: { noul: 0.9 }, kind: { choice: 'git_history' } } });
+    expect(await runtime.evaluatePermission(permission, '/repo')).toEqual({ action: 'hold', score: 0.9, kind: 'git_history' });
+    expect(await runtime.evaluatePermission(permission, '/repo')).toEqual({ action: 'hold', score: 0.9, kind: 'git_history' });
+    expect(jev.ask).toHaveBeenCalledTimes(1);
+    expect(events.filter((e) => e.type === 'openchamber:routing.permission-held')).toHaveLength(1);
+    expect(runtime.heldPermissions()).toEqual([{ permissionId: 'p1', score: 0.9, kind: 'git_history' }]);
+    runtime.forgetPermission('p1');
+    expect(runtime.heldPermissions()).toEqual([]);
+  });
+
+  it('accepts when Jev is unreachable and tells the UI it skipped', async () => {
+    const { runtime, events } = makeRuntime({ askError: Object.assign(new Error('Jev timed out after 4000ms'), { code: 'timeout' }) });
+    expect(await runtime.evaluatePermission(permission, '/repo')).toEqual({ action: 'accept', skipped: 'Jev timed out after 4000ms' });
+    expect(events.at(-1)).toMatchObject({ type: 'openchamber:routing.safety-skipped', properties: { permissionId: 'p1', error: 'Jev timed out after 4000ms' } });
+  });
+
+  it('accepts without asking when the safety net is off, the key is missing, or the flag is unset', async () => {
+    const off = readyConfig();
+    off.safetyNet.enabled = false;
+    for (const setup of [{ config: off }, { token: null }, { flag: '' }]) {
+      const { runtime, jev } = makeRuntime({ ...setup, answers: {} });
+      expect(await runtime.evaluatePermission(permission, '/repo')).toEqual({ action: 'accept' });
+      expect(jev.ask).not.toHaveBeenCalled();
+    }
+  });
+});
+
+describe('describe', () => {
+  it('reports Auto ready only with the flag, enabled config, key, fallback and two categories', async () => {
+    expect((await makeRuntime({ answers: {} }).runtime.describe()).autoReady).toBe(true);
+    expect((await makeRuntime({ token: null, answers: {} }).runtime.describe())).toMatchObject({ autoReady: false, tokenPresent: false });
+    const one = readyConfig();
+    one.categories = one.categories.map((c, i) => ({ ...c, enabled: i === 0 }));
+    expect((await makeRuntime({ config: one, answers: {} }).runtime.describe()).autoReady).toBe(false);
+    expect(await makeRuntime({ flag: '', answers: {} }).runtime.describe()).toEqual({ available: false, autoReady: false, tokenPresent: false, config: null, builtins: [] });
+  });
+});

package/server/lib/routing/store.js

@@ -0,0 +1,249 @@
+/**
+ * Routing configuration on disk.
+ *
+ * `routing.json` holds only deviations from the built-in defaults: a patched or
+ * disabled built-in category, a user category, the fallback model, thresholds.
+ * `routing-auth.json` holds the Jev API key alone, mode 0600, so the config
+ * file can be read, shown and exported without carrying a secret.
+ *
+ * Reads never throw on a missing file (a fresh install is the defaults); a
+ * malformed file is an error, not an empty config, so a bad write cannot
+ * silently reset the user's categories.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import {
+  BUILTIN_CATEGORIES,
+  DEFAULT_MIN_CONFIDENCE,
+  DEFAULT_SAFETY_THRESHOLD,
+  THINKING_LEVELS,
+  isAutoModel,
+} from './defaults.js';
+
+const FILE_VERSION = 1;
+const CATEGORY_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// The Auto sentinel is what routing resolves *from*; as a fallback or category
+// model it would send itself to OpenCode.
+const modelSchema = z.object({
+  providerID: z.string().trim().min(1).max(200),
+  modelID: z.string().trim().min(1).max(200),
+}).strict().refine((model) => !isAutoModel(model), { message: 'The Auto model cannot be a routing target' });
+
+const variantSchema = z.string().trim().min(1).max(80).nullable();
+const agentSchema = z.string().trim().min(1).max(80).nullable();
+
+/** A built-in category on disk carries only what the user changed. */
+const builtinOverrideSchema = z.object({
+  builtin: z.literal(true),
+  disabled: z.boolean().optional(),
+  deleted: z.boolean().optional(),
+  name: z.string().trim().min(1).max(60).optional(),
+  description: z.string().trim().min(1).max(2000).optional(),
+  model: modelSchema.nullable().optional(),
+  variant: variantSchema.optional(),
+  agent: agentSchema.optional(),
+}).strict();
+
+const userCategorySchema = z.object({
+  builtin: z.literal(false),
+  disabled: z.boolean().optional(),
+  name: z.string().trim().min(1).max(60),
+  description: z.string().trim().min(1).max(2000),
+  model: modelSchema.nullable().optional(),
+  variant: variantSchema.optional(),
+  agent: agentSchema.optional(),
+}).strict();
+
+const fileSchema = z.object({
+  version: z.literal(FILE_VERSION),
+  enabled: z.boolean().optional(),
+  fallback: z.object({ model: modelSchema, variant: variantSchema.optional() }).strict().nullable().optional(),
+  minConfidence: z.number().min(0).max(1).optional(),
+  safetyNet: z.object({ enabled: z.boolean(), threshold: z.number().min(0).max(1) }).strict().optional(),
+  categories: z.record(z.string().regex(CATEGORY_ID), z.discriminatedUnion('builtin', [builtinOverrideSchema, userCategorySchema])).optional(),
+}).strict();
+
+/** The effective category the runtime and the UI work with. */
+const effectiveCategorySchema = z.object({
+  id: z.string().regex(CATEGORY_ID),
+  builtin: z.boolean(),
+  enabled: z.boolean(),
+  name: z.string().trim().min(1).max(60),
+  description: z.string().trim().min(1).max(2000),
+  model: modelSchema.nullable(),
+  variant: variantSchema,
+  agent: agentSchema,
+}).strict();
+
+const effectiveConfigSchema = z.object({
+  enabled: z.boolean(),
+  fallback: z.object({ model: modelSchema, variant: variantSchema }).strict().nullable(),
+  minConfidence: z.number().min(0).max(1),
+  safetyNet: z.object({ enabled: z.boolean(), threshold: z.number().min(0).max(1) }).strict(),
+  categories: z.array(effectiveCategorySchema).max(32),
+}).strict();
+
+const authSchema = z.object({ token: z.string().min(1).max(4000) }).strict();
+
+const routingConfigPath = (dataDir) => path.join(dataDir, 'routing.json');
+const routingAuthPath = (dataDir) => path.join(dataDir, 'routing-auth.json');
+
+const readJsonFile = async (file, schema) => {
+  let raw;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  const text = raw.replace(/^/, '').trim();
+  if (text === '') return null;
+  const parsed = schema.safeParse(JSON.parse(text));
+  if (!parsed.success) throw new Error(`Invalid ${path.basename(file)}: ${parsed.error.issues[0]?.message ?? 'schema mismatch'}`);
+  return parsed.data;
+};
+
+const writeJsonFile = async (file, value, mode) => {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode });
+  await fs.rename(tmp, file);
+  if (mode) await fs.chmod(file, mode);
+};
+
+const emptyFile = () => ({ version: FILE_VERSION });
+
+/** Built-ins plus the stored deviations, in built-in order followed by user categories. */
+export const resolveEffectiveConfig = (stored) => {
+  const file = stored ?? emptyFile();
+  const overrides = file.categories ?? {};
+  const categories = [];
+  for (const builtin of BUILTIN_CATEGORIES) {
+    const override = overrides[builtin.id];
+    if (override && override.builtin !== true) continue; // a user id colliding with a built-in is ignored
+    if (override?.deleted) continue;
+    categories.push({
+      id: builtin.id,
+      builtin: true,
+      enabled: !(override?.disabled === true),
+      name: override?.name ?? builtin.name,
+      description: override?.description ?? builtin.description,
+      model: override?.model ?? null,
+      variant: override?.variant ?? null,
+      agent: override?.agent ?? null,
+    });
+  }
+  for (const [id, entry] of Object.entries(overrides)) {
+    if (entry.builtin !== false) continue;
+    categories.push({
+      id,
+      builtin: false,
+      enabled: !(entry.disabled === true),
+      name: entry.name,
+      description: entry.description,
+      model: entry.model ?? null,
+      variant: entry.variant ?? null,
+      agent: entry.agent ?? null,
+    });
+  }
+  return {
+    enabled: file.enabled ?? false,
+    fallback: file.fallback ? { model: file.fallback.model, variant: file.fallback.variant ?? null } : null,
+    minConfidence: file.minConfidence ?? DEFAULT_MIN_CONFIDENCE,
+    safetyNet: file.safetyNet ?? { enabled: false, threshold: DEFAULT_SAFETY_THRESHOLD },
+    categories,
+  };
+};
+
+/** The stored shape for an effective config: built-ins keep only their deviations. */
+export const toStoredConfig = (config) => {
+  const categories = {};
+  const builtinIds = new Set(BUILTIN_CATEGORIES.map((c) => c.id));
+  const present = new Set();
+  for (const category of config.categories) {
+    present.add(category.id);
+    if (category.builtin) {
+      const builtin = BUILTIN_CATEGORIES.find((c) => c.id === category.id);
+      if (!builtin) continue;
+      const override = { builtin: true };
+      if (!category.enabled) override.disabled = true;
+      if (category.name !== builtin.name) override.name = category.name;
+      if (category.description !== builtin.description) override.description = category.description;
+      if (category.model) override.model = category.model;
+      if (category.variant) override.variant = category.variant;
+      if (category.agent) override.agent = category.agent;
+      if (Object.keys(override).length > 1) categories[category.id] = override;
+      continue;
+    }
+    if (builtinIds.has(category.id)) continue;
+    const entry = { builtin: false, name: category.name, description: category.description };
+    if (!category.enabled) entry.disabled = true;
+    if (category.model) entry.model = category.model;
+    if (category.variant) entry.variant = category.variant;
+    if (category.agent) entry.agent = category.agent;
+    categories[category.id] = entry;
+  }
+  for (const builtin of BUILTIN_CATEGORIES) {
+    if (!present.has(builtin.id)) categories[builtin.id] = { builtin: true, deleted: true };
+  }
+  const stored = { version: FILE_VERSION, enabled: config.enabled, minConfidence: config.minConfidence, safetyNet: config.safetyNet };
+  if (config.fallback) {
+    stored.fallback = { model: config.fallback.model };
+    if (config.fallback.variant) stored.fallback.variant = config.fallback.variant;
+  }
+  if (Object.keys(categories).length > 0) stored.categories = categories;
+  return stored;
+};
+
+/** Parses an untrusted effective config (a PUT body) into the trusted shape, or throws. */
+export const parseEffectiveConfig = (input) => {
+  const parsed = effectiveConfigSchema.safeParse(input);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    throw Object.assign(new Error(`Invalid routing config at ${issue?.path.join('.') || 'root'}: ${issue?.message ?? 'schema mismatch'}`), { status: 400 });
+  }
+  const config = parsed.data;
+  const ids = new Set();
+  for (const category of config.categories) {
+    if (ids.has(category.id)) throw Object.assign(new Error(`Duplicate category id ${category.id}`), { status: 400 });
+    ids.add(category.id);
+    if (category.variant && !THINKING_LEVELS.includes(category.variant) && !/^[\w.-]+$/.test(category.variant)) {
+      throw Object.assign(new Error(`Invalid variant for ${category.id}`), { status: 400 });
+    }
+  }
+  return config;
+};
+
+export const createRoutingStore = ({ dataDir }) => {
+  const configFile = routingConfigPath(dataDir);
+  const authFile = routingAuthPath(dataDir);
+  let writeChain = Promise.resolve();
+  const serialize = (run) => {
+    const next = writeChain.catch(() => undefined).then(run);
+    writeChain = next;
+    return next;
+  };
+
+  return {
+    /** Effective config; a missing file is the defaults, a broken file throws. */
+    readConfig: async () => resolveEffectiveConfig(await readJsonFile(configFile, fileSchema)),
+    writeConfig: (config) => serialize(async () => {
+      await writeJsonFile(configFile, toStoredConfig(config));
+      return config;
+    }),
+    readToken: async () => {
+      try {
+        return (await readJsonFile(authFile, authSchema))?.token ?? null;
+      } catch (error) {
+        console.warn('[routing] routing-auth.json is unreadable:', error?.message ?? error);
+        return null;
+      }
+    },
+    writeToken: (token) => serialize(() => writeJsonFile(authFile, { token }, 0o600)),
+    clearToken: () => serialize(async () => {
+      await fs.rm(authFile, { force: true });
+    }),
+  };
+};