@oar-sh/oar 0.9.17 → 0.9.18

package/server/migrations/0031-queue-provider.mjs

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * Migration: a queue row names the billing it runs on (the Claude billing
+ * switch, services/claude-billing-switch-service.mjs).
+ *
+ * `queue.provider`: the provider the row was queued under, written at every
+ * insert from the chat's `runtime_sessions.provider_type`. A Claude chat can
+ * move between `claude` (the subscription) and `claude-api` (the saved API
+ * key); the switch re-stamps the chat's rows that have not started, and every
+ * requeue re-stamps to the chat's billing of that moment. The relay hands a
+ * row only to a worker of that kind, so a turn never runs on a billing nobody
+ * asked for. NULL (a row from before this column) means the chat's billing.
+ *
+ * Two triggers keep the stamp without every writer having to know it:
+ * - `queue_provider_after_insert`: a row inserted without a provider (the
+ *   send route, schedules, events, restart-resume, the board, the usage-limit
+ *   follow-up) takes its chat's provider when the chat is a Claude or Claude
+ *   API one. A writer that names one (a continuation: the kind of the worker
+ *   that runs it) keeps it.
+ * - `queue_provider_after_requeue`: a row going back from processing to
+ *   pending or parked (the stale sweep, dead-worker recovery, a hand-back) is
+ *   a new turn, and takes the chat's provider of that moment.
+ *
+ * The back-fill gives the unfinished rows of Claude and Claude API chats
+ * (pending, parked, processing) their chat's provider. It touches only rows
+ * without one, so it is idempotent; finished rows stay NULL.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0031-queue-provider.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const QUEUE_PROVIDER_COLUMN = 'provider';
+export const QUEUE_PROVIDER_TRIGGERS = Object.freeze(['queue_provider_after_insert', 'queue_provider_after_requeue']);
+
+// The chat's billing, when it is a Claude one: NULL for every other provider.
+const chatClaudeBillingSql = (conversationIdSql) => `(
+  SELECT LOWER(TRIM(rs.provider_type)) FROM runtime_sessions rs
+  WHERE rs.conversation_id = ${conversationIdSql}
+    AND LOWER(TRIM(rs.provider_type)) IN ('claude', 'claude-api')
+)`;
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the relay from stamping rows: '' when nothing does. */
+export function queueProviderProblem(db) {
+  if (!tableExists(db, 'queue')) return 'no queue table';
+  if (!columnNames(db, 'queue').has(QUEUE_PROVIDER_COLUMN)) return 'queue lacks provider';
+  const triggers = new Set(db.prepare(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND tbl_name = 'queue'`).all().map((row) => row.name));
+  const missing = QUEUE_PROVIDER_TRIGGERS.filter((name) => !triggers.has(name));
+  if (missing.length) return `queue lacks the trigger ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateQueueProvider(db) {
+  if (!tableExists(db, 'queue')) return { applied: false, columnsAdded: 0, triggersAdded: 0, rowsFilled: 0 };
+  // The triggers and the back-fill read provider_type: a table without it
+  // waits for the schema boot to add it.
+  if (!tableExists(db, 'runtime_sessions') || !columnNames(db, 'runtime_sessions').has('provider_type')) {
+    return { applied: false, columnsAdded: 0, triggersAdded: 0, rowsFilled: 0 };
+  }
+  let columnsAdded = 0;
+  if (!columnNames(db, 'queue').has(QUEUE_PROVIDER_COLUMN)) {
+    db.exec(`ALTER TABLE queue ADD COLUMN ${QUEUE_PROVIDER_COLUMN} TEXT`);
+    columnsAdded += 1;
+  }
+  const present = new Set(db.prepare(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND tbl_name = 'queue'`).all().map((row) => row.name));
+  let triggersAdded = 0;
+  if (!present.has('queue_provider_after_insert')) {
+    db.exec(`
+      CREATE TRIGGER queue_provider_after_insert
+      AFTER INSERT ON queue
+      WHEN NEW.provider IS NULL
+      BEGIN
+        UPDATE queue SET provider = ${chatClaudeBillingSql('NEW.conversation_id')} WHERE id = NEW.id;
+      END
+    `);
+    triggersAdded += 1;
+  }
+  if (!present.has('queue_provider_after_requeue')) {
+    db.exec(`
+      CREATE TRIGGER queue_provider_after_requeue
+      AFTER UPDATE OF status ON queue
+      WHEN OLD.status = 'processing' AND NEW.status IN ('pending', 'parked')
+      BEGIN
+        UPDATE queue SET provider = COALESCE(${chatClaudeBillingSql('NEW.conversation_id')}, NEW.provider) WHERE id = NEW.id;
+      END
+    `);
+    triggersAdded += 1;
+  }
+  const rowsFilled = db.prepare(`
+    UPDATE queue
+    SET provider = ${chatClaudeBillingSql('queue.conversation_id')}
+    WHERE provider IS NULL
+      AND status IN ('pending', 'parked', 'processing')
+      AND ${chatClaudeBillingSql('queue.conversation_id')} IS NOT NULL
+  `).run().changes;
+  return { applied: columnsAdded > 0 || triggersAdded > 0 || rowsFilled > 0, columnsAdded, triggersAdded, rowsFilled };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateQueueProvider(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0031 on ${dbPath}`);
+    console.log(result.applied
+      ? `  queue provider: columns added ${result.columnsAdded}, triggers added ${result.triggersAdded}, rows filled ${result.rowsFilled}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0031 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0032-runtime-session-billing-switch.mjs

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * Migration: a runtime session remembers its last billing switch (the Claude
+ * billing switch, services/claude-billing-switch-service.mjs).
+ *
+ * `runtime_sessions` gains two columns:
+ * - `billing_switched_at`: when the chat last moved between `claude` (the
+ *   subscription) and `claude-api` (the saved API key); NULL for a chat that
+ *   never did. A worker started before the switch existed reports no kind, and
+ *   on a chat with this set the relay cannot assume the kind from
+ *   `provider_type`: it replaces that worker once, when it is idle. A chat
+ *   never switched has had one billing, which also settles whose turns its
+ *   older messages are.
+ * - `billing_switched_by`: who asked: `user` (the toggle), `agent` (an
+ *   agent's `send` with a provider) or `usage-limit` (the button on the
+ *   usage-limit note).
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0032-runtime-session-billing-switch.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+// Added to runtime_sessions, with their DDL.
+export const RUNTIME_SESSION_BILLING_SWITCH_COLUMNS = Object.freeze([
+  ['billing_switched_at', 'TEXT'],
+  ['billing_switched_by', 'TEXT'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the switch from recording itself: '' when nothing does. */
+export function runtimeSessionBillingSwitchProblem(db) {
+  if (!tableExists(db, 'runtime_sessions')) return 'no runtime_sessions table';
+  const present = columnNames(db, 'runtime_sessions');
+  const missing = RUNTIME_SESSION_BILLING_SWITCH_COLUMNS.map(([name]) => name).filter((name) => !present.has(name));
+  if (missing.length) return `runtime_sessions lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateRuntimeSessionBillingSwitch(db) {
+  if (!tableExists(db, 'runtime_sessions')) return { applied: false, columnsAdded: 0 };
+  let columnsAdded = 0;
+  const present = columnNames(db, 'runtime_sessions');
+  for (const [name, ddl] of RUNTIME_SESSION_BILLING_SWITCH_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE runtime_sessions ADD COLUMN ${name} ${ddl}`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateRuntimeSessionBillingSwitch(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0032 on ${dbPath}`);
+    console.log(result.applied
+      ? `  runtime session billing switch: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0032 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0033-claude-api-usage-checkpoints.mjs

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Migration: Claude API usage checkpoints (services/plan-usage-service.mjs,
+ * recordClaudeApiUsageReport; the booking behind the Claude API card and its
+ * monthly cap).
+ *
+ * Both Claude workers, the subscription one and the Claude API one, post
+ * after every turn (POST /api/claude-api-usage). A chat can move between the
+ * two billings and keeps its Claude Code session, so what one billing ran
+ * shows up in the totals the other one reports after the switch. One row per
+ * (conversation, Claude Code session, CLI process, model):
+ *
+ * - `conversation_id`, `native_session_id` (the CLI's session id), `run_id`
+ *   (the id the worker gives each CLI process it spawns), `model`.
+ * - `billing`: the kind of the worker that posted: `claude` or `claude-api`.
+ * - `run_hit_tokens`, `run_miss_tokens`, `run_output_tokens`, `run_cost_usd`:
+ *   what this process has run so far, counted from zero, as far as it was
+ *   booked. A post books its rise over these; one at or below them is a
+ *   retried or reordered post and books nothing. Only `claude-api` rows book
+ *   spend.
+ * - `session_hit_tokens`, `session_miss_tokens`, `session_output_tokens`,
+ *   `session_cost_usd`: the CLI's own cumulative totals for the session at
+ *   that post. The row of a session with the latest `last_turn_at` is the
+ *   session's mark: a CLI resumed on the session, under either billing,
+ *   re-reports the earlier turns in its first result, and the mark is what
+ *   that first result is measured against.
+ * - `cost_unknown`: 1 when the CLI had no price for the model.
+ * - `last_turn_id` (the queue row of the turn), `last_turn_at` (when its
+ *   result came): the turn the row covers. A mark is used only when no
+ *   completed turn of the session is newer than it.
+ * - `updated_at`.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0033-claude-api-usage-checkpoints.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const CLAUDE_API_USAGE_CHECKPOINTS_TABLE = 'claude_api_usage_checkpoints';
+
+export const CLAUDE_API_USAGE_CHECKPOINT_COLUMNS = Object.freeze([
+  'conversation_id',
+  'native_session_id',
+  'run_id',
+  'model',
+  'billing',
+  'run_hit_tokens',
+  'run_miss_tokens',
+  'run_output_tokens',
+  'run_cost_usd',
+  'session_hit_tokens',
+  'session_miss_tokens',
+  'session_output_tokens',
+  'session_cost_usd',
+  'cost_unknown',
+  'last_turn_id',
+  'last_turn_at',
+  'updated_at',
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+/** What keeps the service from using the table: '' when nothing does. */
+export function claudeApiUsageCheckpointsProblem(db) {
+  if (!tableExists(db, CLAUDE_API_USAGE_CHECKPOINTS_TABLE)) return `no ${CLAUDE_API_USAGE_CHECKPOINTS_TABLE} table`;
+  const present = new Set(db.prepare(`PRAGMA table_info(${CLAUDE_API_USAGE_CHECKPOINTS_TABLE})`).all().map((column) => column.name));
+  const missing = CLAUDE_API_USAGE_CHECKPOINT_COLUMNS.filter((name) => !present.has(name));
+  if (missing.length) return `${CLAUDE_API_USAGE_CHECKPOINTS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateClaudeApiUsageCheckpoints(db) {
+  if (tableExists(db, CLAUDE_API_USAGE_CHECKPOINTS_TABLE)) return { applied: false, tablesAdded: 0 };
+  db.exec(`
+    CREATE TABLE ${CLAUDE_API_USAGE_CHECKPOINTS_TABLE} (
+      conversation_id        TEXT NOT NULL,
+      native_session_id      TEXT NOT NULL,
+      run_id                 TEXT NOT NULL,
+      model                  TEXT NOT NULL,
+      billing                TEXT NOT NULL,
+      run_hit_tokens         INTEGER NOT NULL DEFAULT 0,
+      run_miss_tokens        INTEGER NOT NULL DEFAULT 0,
+      run_output_tokens      INTEGER NOT NULL DEFAULT 0,
+      run_cost_usd           REAL NOT NULL DEFAULT 0,
+      session_hit_tokens     INTEGER NOT NULL DEFAULT 0,
+      session_miss_tokens    INTEGER NOT NULL DEFAULT 0,
+      session_output_tokens  INTEGER NOT NULL DEFAULT 0,
+      session_cost_usd       REAL NOT NULL DEFAULT 0,
+      cost_unknown           INTEGER NOT NULL DEFAULT 0,
+      last_turn_id           TEXT,
+      last_turn_at           TEXT,
+      updated_at             TEXT NOT NULL,
+      PRIMARY KEY (conversation_id, native_session_id, run_id, model)
+    )
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_claude_api_usage_checkpoints_mark
+      ON ${CLAUDE_API_USAGE_CHECKPOINTS_TABLE}(native_session_id, last_turn_at)
+  `);
+  return { applied: true, tablesAdded: 1 };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateClaudeApiUsageCheckpoints(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0033 on ${dbPath}`);
+    console.log(result.applied ? `  claude api usage checkpoints: tables added ${result.tablesAdded}` : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0033 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0034-claude-api-usage-totals.mjs

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * Migration: Claude API usage totals (services/plan-usage-service.mjs, the
+ * Claude API card in Check Usage and its monthly cap).
+ *
+ * `claude_api_usage_totals`: what this relay's turns on the saved Claude API
+ * key ran, per day and model; a row only ever grows. Subscription turns are
+ * never booked here. The card shows today and this month, and the cap is a
+ * calendar month in relay local time, so the day is the relay's local date.
+ *
+ * - `day`: `YYYY-MM-DD`, the relay's local date of the turn's result.
+ * - `model`: the model's id as the CLI reported it, without the `[1m]`
+ *   suffix, lower case.
+ * - `hit_tokens`, `miss_tokens`, `output_tokens`: input read from the
+ *   prompt cache, other input (cache writes included), and output.
+ * - `cost_usd`: Claude Code's own estimate (`modelUsage[*].costUSD`) of what
+ *   the booked turns cost, for the turns it could price.
+ * - `unknown_cost_tokens`: the tokens of turns it could not price
+ *   (`costBasis: unknown`), which `cost_usd` leaves out.
+ * - `turn_count`: the posts that booked something for the model.
+ * - `first_seen_at`, `last_seen_at`, `updated_at`.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0034-claude-api-usage-totals.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const CLAUDE_API_USAGE_TOTALS_TABLE = 'claude_api_usage_totals';
+
+export const CLAUDE_API_USAGE_TOTALS_COLUMNS = Object.freeze([
+  'day',
+  'model',
+  'hit_tokens',
+  'miss_tokens',
+  'output_tokens',
+  'cost_usd',
+  'unknown_cost_tokens',
+  'turn_count',
+  'first_seen_at',
+  'last_seen_at',
+  'updated_at',
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+/** What keeps the service from using the table: '' when nothing does. */
+export function claudeApiUsageTotalsProblem(db) {
+  if (!tableExists(db, CLAUDE_API_USAGE_TOTALS_TABLE)) return `no ${CLAUDE_API_USAGE_TOTALS_TABLE} table`;
+  const present = new Set(db.prepare(`PRAGMA table_info(${CLAUDE_API_USAGE_TOTALS_TABLE})`).all().map((column) => column.name));
+  const missing = CLAUDE_API_USAGE_TOTALS_COLUMNS.filter((name) => !present.has(name));
+  if (missing.length) return `${CLAUDE_API_USAGE_TOTALS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateClaudeApiUsageTotals(db) {
+  if (tableExists(db, CLAUDE_API_USAGE_TOTALS_TABLE)) return { applied: false, tablesAdded: 0 };
+  db.exec(`
+    CREATE TABLE ${CLAUDE_API_USAGE_TOTALS_TABLE} (
+      day                  TEXT NOT NULL,
+      model                TEXT NOT NULL,
+      hit_tokens           INTEGER NOT NULL DEFAULT 0,
+      miss_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens        INTEGER NOT NULL DEFAULT 0,
+      cost_usd             REAL NOT NULL DEFAULT 0,
+      unknown_cost_tokens  INTEGER NOT NULL DEFAULT 0,
+      turn_count           INTEGER NOT NULL DEFAULT 0,
+      first_seen_at        TEXT NOT NULL,
+      last_seen_at         TEXT NOT NULL,
+      updated_at           TEXT NOT NULL,
+      PRIMARY KEY (day, model)
+    )
+  `);
+  return { applied: true, tablesAdded: 1 };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateClaudeApiUsageTotals(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0034 on ${dbPath}`);
+    console.log(result.applied ? `  claude api usage totals: tables added ${result.tablesAdded}` : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0034 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/public/app/activity-replay-state.mjs

@@ -26,12 +26,13 @@ export function isCompactBoundaryActivityEntry(item) {
 
 // The live list of one turn keeps its newest ordinary lines only, but every
 // structured row a line of the transcript is built from: the turn's
-// compaction entries and the session-restart note would otherwise scroll out
-// of a busy turn and take their line with them until the next reload.
+// compaction entries and the session-restart notes (a compaction window, a
+// billing switch) would otherwise scroll out of a busy turn and take their
+// line with them until the next reload.
 export const LIVE_ACTIVITY_CAP = 24;
 function isKeptLiveActivityEntry(item) {
   const kind = normalizeRelayActivityEntry(item)?.metadata?.kind;
-  return kind === 'compact_boundary' || kind === 'compact_window_respawn';
+  return kind === 'compact_boundary' || kind === 'compact_window_respawn' || kind === 'billing_switch_respawn';
 }
 export function capLiveActivityEntries(items, cap = LIVE_ACTIVITY_CAP) {
   const list = Array.isArray(items) ? items : [];

package/server/public/app/agent-sessions-settings-ui.js

@@ -1,5 +1,5 @@
 // Settings → Relays → Agent sessions: the switch that lets agents start and use
-// sessions on this relay through the remote_relay tool, and the slider for the
+// sessions on this relay through the relay_tool, and the slider for the
 // longest wait of one tool call. The decisions live in
 // agent-sessions-settings.mjs; this file only moves them into the markup in
 // index.html. The static controls use inline handlers that bootstrap.js

package/server/public/app/agent-sessions-settings.mjs

@@ -1,5 +1,5 @@
 // Pure helpers for Settings → Relays → Agent sessions: whether agents may
-// start and use sessions on this relay, and the longest time one remote_relay
+// start and use sessions on this relay, and the longest time one relay_tool
 // call may wait. DOM-free on purpose, like claude-cloud-ui.mjs: the section
 // (agent-sessions-settings-ui.js) owns the elements, this module the decisions.
 //

package/server/public/app/api-client.js

@@ -575,6 +575,37 @@ export async function updateDeepSeekSettings({
   return settingsRequest('/api/settings/deepseek', payload, 'Failed to update DeepSeek settings');
 }
 
+export async function loadClaudeApiSettings() {
+  return apiFetch('/api/settings/claude-api');
+}
+
+/**
+ * Saves what the caller names on the Claude API tab: a key (written, never
+ * read back), the switch, the default model, the enabled models and the
+ * monthly cap in US dollars (null = no cap); `remove` takes the key out.
+ */
+export async function updateClaudeApiSettings({
+  apiKey = '',
+  model = undefined,
+  enabled = undefined,
+  enabledModels = undefined,
+  monthlyCapUsd = undefined,
+  remove = false,
+} = {}) {
+  // Only the fields named here reach the relay: a field the Claude API tab
+  // shows needs its line below (api-client.claude-api-settings.test.mjs).
+  const payload = remove === true ? { remove: true } : {};
+  if (!payload.remove) {
+    const key = String(apiKey || '').trim();
+    if (key) payload.apiKey = key;
+    if (typeof model === 'string' && model.trim()) payload.model = model.trim();
+    if (typeof enabled === 'boolean') payload.enabled = enabled;
+    if (Array.isArray(enabledModels)) payload.enabledModels = enabledModels;
+    if (monthlyCapUsd === null || (typeof monthlyCapUsd === 'number' && Number.isFinite(monthlyCapUsd))) payload.monthlyCapUsd = monthlyCapUsd;
+  }
+  return settingsRequest('/api/settings/claude-api', payload, 'Failed to update Claude API settings');
+}
+
 /**
  * Imports DeepSeek's usage export: the texts of its amount and cost files.
  * Answers `{ ok, summary }`; a refused export throws with the relay's reason.
@@ -1479,6 +1510,27 @@ export async function resumeUsageLimitPause(conversationId) {
   });
 }
 
+// Move a Claude chat between the subscription ("claude") and the saved API
+// key ("claude-api"), from its next turn. `by: "usage-limit"` is the
+// usage-limit note's button. `{ ok: true, ... }`, else `{ ok: false, error,
+// code }` with the relay's reason (the key, the model, the cap).
+export async function switchConversationBilling(conversationId, { to, by = 'user' } = {}) {
+  let refusal = null;
+  const result = await apiFetch(`/api/conversation/${encodeURIComponent(String(conversationId || ''))}/billing`, {
+    method: 'POST',
+    body: JSON.stringify({ to, by }),
+    onErrorResponse: async (response) => {
+      const payload = await response.json().catch(() => null);
+      refusal = {
+        ok: false,
+        error: readableServerError(payload?.error) || `The relay answered ${response.status}.`,
+        code: payload?.code || null,
+      };
+    },
+  });
+  return result || refusal || { ok: false, error: 'The relay could not be reached.', code: null };
+}
+
 export async function cancelUsageLimitPause(conversationId) {
   return apiFetch('/api/usage-limit/cancel', {
     method: 'POST',