@oar-sh/oar 0.9.16 → 0.9.18

package/server/services/plan-usage-service.mjs

@@ -12,10 +12,19 @@
  * has to be *derived*, so two small bookkeeping tables are kept — a cumulative
  * per-agent checkpoint (to diff against) and per-cycle pool totals (the
  * accumulated result). Neither grows with conversation history.
+ *
+ * DeepSeek's estimated spend is summed per model (migration 0024): one row
+ * per model. Its workers report the CLI's running totals, so a checkpoint per
+ * (conversation, CLI session, model) is kept to diff against, as for Cursor.
+ * The same sums go into a row per UTC day and model (migration 0025), for
+ * the card's daily chart and its monthly budget; that table grows by at most
+ * one row per model per day.
  */
 
 import {
   PLAN_USAGE_VERSION,
+  toFiniteNumber,
+  toIsoTimestamp,
   toTrimmedString,
 } from './plan-usage-contract.mjs';
 import { buildCopilotPlanCard } from './plan-usage-copilot.mjs';
@@ -35,6 +44,35 @@ import {
   normalizeGrokTurnUsage,
   resolveGrokBillingCycle,
 } from './plan-usage-grok.mjs';
+import { buildDeepSeekPlanCard } from './plan-usage-deepseek.mjs';
+import {
+  DEEPSEEK_USAGE_CHECKPOINTS_TABLE,
+  DEEPSEEK_USAGE_TOTALS_TABLE,
+  migrateDeepSeekUsageTotals,
+} from '../migrations/0024-deepseek-usage-totals.mjs';
+import {
+  DEEPSEEK_BALANCE_REFERENCE_TABLE,
+  DEEPSEEK_USAGE_DAYS_TABLE,
+  migrateDeepSeekUsageRequestsDaily,
+} from '../migrations/0025-deepseek-usage-requests-daily.mjs';
+import { migrateDeepSeekUsageServedModels } from '../migrations/0026-deepseek-usage-served-models.mjs';
+import { migrateDeepSeekUsageCheckpointRuns } from '../migrations/0027-deepseek-usage-checkpoint-runs.mjs';
+import { migrateDeepSeekUsageCheckpointRequestRuns } from '../migrations/0028-deepseek-usage-checkpoint-request-runs.mjs';
+import { migrateDeepSeekBalanceRises } from '../migrations/0029-deepseek-balance-rises.mjs';
+import { deepseekServedModel } from '../../shared/deepseek-models.mjs';
+import { estimateCost, estimateSearchCost } from '../../shared/deepseek-pricing.mjs';
+
+// A DeepSeek report's token fields and their checkpoint columns.
+const DEEPSEEK_TOKEN_FIELDS = Object.freeze([
+  ['hitTokens', 'hit_tokens'],
+  ['missTokens', 'miss_tokens'],
+  ['outputTokens', 'output_tokens'],
+]);
+// Its request fields (web searches and fetches) and their checkpoint columns.
+const DEEPSEEK_REQUEST_FIELDS = Object.freeze([
+  ['searchRequests', 'search_requests'],
+  ['fetchRequests', 'fetch_requests'],
+]);
 
 export const PROVIDER_USAGE_SNAPSHOT_TABLE = 'provider_usage_snapshots';
 export const CURSOR_USAGE_CHECKPOINT_TABLE = 'cursor_usage_checkpoints';
@@ -103,9 +141,29 @@ const CHECKPOINT_COLUMNS = [
 export function ensurePlanUsageSchema(db) {
   if (typeof db?.exec !== 'function') return false;
   db.exec(PLAN_USAGE_SCHEMA_SQL);
+  // The boot runs the same migration (db-schema.mjs); a database the service
+  // is handed on its own (tests, tools) gets the table here.
+  migrateDeepSeekUsageTotals(db);
+  migrateDeepSeekUsageRequestsDaily(db);
+  migrateDeepSeekUsageServedModels(db);
+  migrateDeepSeekUsageCheckpointRuns(db);
+  migrateDeepSeekUsageCheckpointRequestRuns(db);
+  migrateDeepSeekBalanceRises(db);
   return true;
 }
 
+/**
+ * The model a DeepSeek report's entry is booked under: the DeepSeek model
+ * that served it. An older worker names a sub-agent's model as Claude Code
+ * requested it (`claude-opus-5-5`, which DeepSeek serves with V4 Pro); the
+ * table and the prices know DeepSeek's ids only. A name DeepSeek is not known
+ * to serve is booked as it is, without a price.
+ */
+function deepseekBookedModel(value) {
+  const model = toTrimmedString(value);
+  return deepseekServedModel(model) || model;
+}
+
 function rowToCheckpoint(row) {
   if (!row) return null;
   const checkpoint = { agentId: row.agent_id, capturedAt: row.updated_at };
@@ -201,6 +259,88 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
         updated_at = excluded.updated_at
     `),
     clearGrokCycle: db.prepare(`DELETE FROM ${GROK_USAGE_CYCLE_TABLE} WHERE cycle_key = ?`),
+    // A cost of NULL is "no estimate": it stays NULL until a turn of the
+    // model can be priced, and never turns a known sum into NULL. The tools
+    // cost (searches and fetches) is always known.
+    addDeepSeekTotals: db.prepare(`
+      INSERT INTO ${DEEPSEEK_USAGE_TOTALS_TABLE} (
+        model, hit_tokens, miss_tokens, output_tokens, search_requests, fetch_requests, turn_count,
+        cost_usd, cost_cny, tools_cost_usd, tools_cost_cny, first_seen_at, last_seen_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(model) DO UPDATE SET
+        hit_tokens = ${DEEPSEEK_USAGE_TOTALS_TABLE}.hit_tokens + excluded.hit_tokens,
+        miss_tokens = ${DEEPSEEK_USAGE_TOTALS_TABLE}.miss_tokens + excluded.miss_tokens,
+        output_tokens = ${DEEPSEEK_USAGE_TOTALS_TABLE}.output_tokens + excluded.output_tokens,
+        search_requests = ${DEEPSEEK_USAGE_TOTALS_TABLE}.search_requests + excluded.search_requests,
+        fetch_requests = ${DEEPSEEK_USAGE_TOTALS_TABLE}.fetch_requests + excluded.fetch_requests,
+        turn_count = ${DEEPSEEK_USAGE_TOTALS_TABLE}.turn_count + 1,
+        cost_usd = CASE WHEN excluded.cost_usd IS NULL THEN ${DEEPSEEK_USAGE_TOTALS_TABLE}.cost_usd
+          ELSE COALESCE(${DEEPSEEK_USAGE_TOTALS_TABLE}.cost_usd, 0) + excluded.cost_usd END,
+        cost_cny = CASE WHEN excluded.cost_cny IS NULL THEN ${DEEPSEEK_USAGE_TOTALS_TABLE}.cost_cny
+          ELSE COALESCE(${DEEPSEEK_USAGE_TOTALS_TABLE}.cost_cny, 0) + excluded.cost_cny END,
+        tools_cost_usd = ${DEEPSEEK_USAGE_TOTALS_TABLE}.tools_cost_usd + excluded.tools_cost_usd,
+        tools_cost_cny = ${DEEPSEEK_USAGE_TOTALS_TABLE}.tools_cost_cny + excluded.tools_cost_cny,
+        first_seen_at = MIN(${DEEPSEEK_USAGE_TOTALS_TABLE}.first_seen_at, excluded.first_seen_at),
+        last_seen_at = MAX(${DEEPSEEK_USAGE_TOTALS_TABLE}.last_seen_at, excluded.last_seen_at),
+        updated_at = excluded.updated_at
+    `),
+    // The same sums per UTC day, for the daily chart and the month's spend.
+    addDeepSeekDay: db.prepare(`
+      INSERT INTO ${DEEPSEEK_USAGE_DAYS_TABLE} (
+        day, model, hit_tokens, miss_tokens, output_tokens, search_requests, fetch_requests, turn_count,
+        cost_usd, cost_cny, tools_cost_usd, tools_cost_cny, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?)
+      ON CONFLICT(day, model) DO UPDATE SET
+        hit_tokens = ${DEEPSEEK_USAGE_DAYS_TABLE}.hit_tokens + excluded.hit_tokens,
+        miss_tokens = ${DEEPSEEK_USAGE_DAYS_TABLE}.miss_tokens + excluded.miss_tokens,
+        output_tokens = ${DEEPSEEK_USAGE_DAYS_TABLE}.output_tokens + excluded.output_tokens,
+        search_requests = ${DEEPSEEK_USAGE_DAYS_TABLE}.search_requests + excluded.search_requests,
+        fetch_requests = ${DEEPSEEK_USAGE_DAYS_TABLE}.fetch_requests + excluded.fetch_requests,
+        turn_count = ${DEEPSEEK_USAGE_DAYS_TABLE}.turn_count + 1,
+        cost_usd = CASE WHEN excluded.cost_usd IS NULL THEN ${DEEPSEEK_USAGE_DAYS_TABLE}.cost_usd
+          ELSE COALESCE(${DEEPSEEK_USAGE_DAYS_TABLE}.cost_usd, 0) + excluded.cost_usd END,
+        cost_cny = CASE WHEN excluded.cost_cny IS NULL THEN ${DEEPSEEK_USAGE_DAYS_TABLE}.cost_cny
+          ELSE COALESCE(${DEEPSEEK_USAGE_DAYS_TABLE}.cost_cny, 0) + excluded.cost_cny END,
+        tools_cost_usd = ${DEEPSEEK_USAGE_DAYS_TABLE}.tools_cost_usd + excluded.tools_cost_usd,
+        tools_cost_cny = ${DEEPSEEK_USAGE_DAYS_TABLE}.tools_cost_cny + excluded.tools_cost_cny,
+        updated_at = excluded.updated_at
+    `),
+    listDeepSeekTotals: db.prepare(`SELECT * FROM ${DEEPSEEK_USAGE_TOTALS_TABLE} ORDER BY last_seen_at DESC, model`),
+    listDeepSeekDays: db.prepare(`SELECT * FROM ${DEEPSEEK_USAGE_DAYS_TABLE} WHERE day >= ? ORDER BY day, model`),
+    firstDeepSeekDay: db.prepare(`SELECT MIN(day) AS day FROM ${DEEPSEEK_USAGE_DAYS_TABLE}`),
+    listDeepSeekBalanceReferences: db.prepare(`SELECT * FROM ${DEEPSEEK_BALANCE_REFERENCE_TABLE} ORDER BY currency`),
+    getDeepSeekBalanceReference: db.prepare(`SELECT * FROM ${DEEPSEEK_BALANCE_REFERENCE_TABLE} WHERE currency = ?`),
+    upsertDeepSeekBalanceReference: db.prepare(`
+      INSERT INTO ${DEEPSEEK_BALANCE_REFERENCE_TABLE} (currency, reference_total, last_total, reference_at, updated_at, rose_at, last_read_at, rose_from_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(currency) DO UPDATE SET
+        reference_total = excluded.reference_total,
+        last_total = excluded.last_total,
+        reference_at = excluded.reference_at,
+        updated_at = excluded.updated_at,
+        rose_at = excluded.rose_at,
+        last_read_at = excluded.last_read_at,
+        rose_from_at = excluded.rose_from_at
+    `),
+    getDeepSeekCheckpoint: db.prepare(`
+      SELECT * FROM ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE}
+      WHERE conversation_id = ? AND native_session_id = ? AND model = ?
+    `),
+    upsertDeepSeekCheckpoint: db.prepare(`
+      INSERT INTO ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} (
+        conversation_id, native_session_id, model, run_id, request_run_id,
+        hit_tokens, miss_tokens, output_tokens, search_requests, fetch_requests, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(conversation_id, native_session_id, model) DO UPDATE SET
+        run_id = excluded.run_id,
+        request_run_id = excluded.request_run_id,
+        hit_tokens = excluded.hit_tokens,
+        miss_tokens = excluded.miss_tokens,
+        output_tokens = excluded.output_tokens,
+        search_requests = excluded.search_requests,
+        fetch_requests = excluded.fetch_requests,
+        updated_at = excluded.updated_at
+    `),
   };
 
   function nowIso() {
@@ -384,6 +524,252 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
     return { cycle };
   }
 
+  /**
+   * Book one DeepSeek report (normalizeDeepSeekUsageReport): a worker's
+   * running token totals per model for one CLI session, with its estimate
+   * at the price of the report's time in both currencies. The checkpoint
+   * per (conversation, session, model) holds the totals last booked and the
+   * `runId` they came from, the id the worker gives each CLI process.
+   *
+   * With a run id the totals are that process's own, counted from zero when
+   * it started (the worker takes the CLI's session totals apart, so what a
+   * resumed CLI restored from its transcript is never in them). Under the
+   * run the checkpoint came from only the increase is booked, field by
+   * field, and a total below the checkpoint is a stale report (a post
+   * retried or delivered out of order): it books nothing and leaves the
+   * checkpoint at its high-water mark. Under another run the report is a
+   * new process, booked in full, from which the checkpoint starts over; a
+   * late report of the earlier process after that is booked in full too,
+   * since the relay cannot tell it from a process counting from zero.
+   *
+   * Without a run id (an older worker) the totals are the CLI's own, which
+   * a resumed CLI continues from its session's earlier ones: what they add
+   * is booked, and a drop is a CLI counting from zero again, booked in full.
+   *
+   * Web searches and fetches: a report with a run id carries the process's
+   * running counts per model, booked like the tokens under a run id of their
+   * own (`request_run_id`: an entry with counts only, as a sub-agent's model
+   * that searched without tokens of its own, leaves the token run alone).
+   * Without a run id they are the turn's counts, booked as they come.
+   * Returns what was booked: models with nothing new are left out.
+   */
+  function recordDeepSeekUsageReport(report) {
+    const at = toTrimmedString(report?.at);
+    const conversationId = toTrimmedString(report?.conversationId);
+    const nativeSessionId = toTrimmedString(report?.nativeSessionId);
+    const runId = toTrimmedString(report?.runId) || '';
+    const totals = Array.isArray(report?.totals) ? report.totals : [];
+    const requests = Array.isArray(report?.requests) ? report.requests : [];
+    if (!at || !conversationId || !nativeSessionId || (!totals.length && !requests.length)) return null;
+    const timestamp = nowIso();
+    const day = at.slice(0, 10);
+    // Entries that name one DeepSeek model in two ways (its own id and a
+    // Claude id it served) are summed, like the worker sums the CLI's names.
+    const totalsByModel = new Map();
+    for (const entry of totals) {
+      const model = deepseekBookedModel(entry?.model);
+      if (!model) continue;
+      const current = totalsByModel.get(model) || { hitTokens: 0, missTokens: 0, outputTokens: 0 };
+      for (const [field] of DEEPSEEK_TOKEN_FIELDS) current[field] += Math.max(0, Number(entry?.[field]) || 0);
+      totalsByModel.set(model, current);
+    }
+    const requestsByModel = new Map();
+    for (const entry of requests) {
+      const model = deepseekBookedModel(entry?.model);
+      if (!model) continue;
+      const current = requestsByModel.get(model) || { searchRequests: 0, fetchRequests: 0 };
+      current.searchRequests += Math.max(0, Number(entry.searchRequests) || 0);
+      current.fetchRequests += Math.max(0, Number(entry.fetchRequests) || 0);
+      requestsByModel.set(model, current);
+    }
+    const models = [...new Set([...totalsByModel.keys(), ...requestsByModel.keys()])];
+    const booked = [];
+    const persist = db.transaction(() => {
+      for (const model of models) {
+        const entry = totalsByModel.get(model);
+        const modelRequests = requestsByModel.get(model);
+        const delta = { model, hitTokens: 0, missTokens: 0, outputTokens: 0, searchRequests: 0, fetchRequests: 0 };
+        const previous = stmts.getDeepSeekCheckpoint.get(conversationId, nativeSessionId, model) || null;
+        // The checkpoint's totals (counts) came from this very process: they
+        // can only have grown since.
+        const sameRun = Boolean(runId) && Boolean(previous) && String(previous.run_id || '') === runId;
+        const sameRequestRun = Boolean(runId) && Boolean(previous) && String(previous.request_run_id || '') === runId;
+        // What the checkpoint will hold: the report's totals, or the
+        // high-water mark when the report is stale.
+        const checkpoint = { runId: String(previous?.run_id || ''), requestRunId: String(previous?.request_run_id || '') };
+        for (const [field, column] of DEEPSEEK_TOKEN_FIELDS) checkpoint[field] = Number(previous?.[column]) || 0;
+        for (const [field, column] of DEEPSEEK_REQUEST_FIELDS) checkpoint[field] = Number(previous?.[column]) || 0;
+        if (entry) {
+          const reported = {};
+          for (const [field] of DEEPSEEK_TOKEN_FIELDS) reported[field] = Number(entry[field]) || 0;
+          const drop = DEEPSEEK_TOKEN_FIELDS.some(([field]) => reported[field] < checkpoint[field]);
+          if (drop && sameRun) {
+            // Stale: a retried post, or one that arrived after a later one.
+          } else {
+            // A process's own totals under a new run are all new spend; an
+            // older worker's session totals add their increase, or are a CLI
+            // counting from zero again when they dropped.
+            const full = runId ? !sameRun : drop;
+            for (const [field] of DEEPSEEK_TOKEN_FIELDS) {
+              delta[field] = full ? reported[field] : reported[field] - checkpoint[field];
+              checkpoint[field] = reported[field];
+            }
+            checkpoint.runId = runId;
+          }
+        }
+        if (modelRequests && runId) {
+          // Running counts for this process: in full under a new run (the
+          // checkpoint's counts are another process's), the increase under
+          // the same one, nothing when they are at or below the checkpoint.
+          const drop = DEEPSEEK_REQUEST_FIELDS.some(([field]) => modelRequests[field] < checkpoint[field]);
+          if (!(drop && sameRequestRun)) {
+            for (const [field] of DEEPSEEK_REQUEST_FIELDS) {
+              delta[field] = sameRequestRun ? modelRequests[field] - checkpoint[field] : modelRequests[field];
+              checkpoint[field] = modelRequests[field];
+            }
+            checkpoint.requestRunId = runId;
+          }
+        } else if (modelRequests) {
+          // An older worker: the turn's counts, booked as they come.
+          delta.searchRequests = modelRequests.searchRequests;
+          delta.fetchRequests = modelRequests.fetchRequests;
+        }
+        if (entry || (modelRequests && runId)) {
+          stmts.upsertDeepSeekCheckpoint.run(
+            conversationId,
+            nativeSessionId,
+            model,
+            checkpoint.runId,
+            checkpoint.requestRunId,
+            checkpoint.hitTokens,
+            checkpoint.missTokens,
+            checkpoint.outputTokens,
+            checkpoint.searchRequests,
+            checkpoint.fetchRequests,
+            timestamp,
+          );
+        }
+        const tokenCount = delta.hitTokens + delta.missTokens + delta.outputTokens;
+        if (tokenCount <= 0 && delta.searchRequests + delta.fetchRequests <= 0) continue;
+        const tokens = { hitTokens: delta.hitTokens, missTokens: delta.missTokens, outputTokens: delta.outputTokens };
+        // No tokens booked (a request-only report) is no token estimate.
+        delta.costUsd = tokenCount > 0 ? estimateCost({ model, at, currency: 'USD', ...tokens }) : null;
+        delta.costCny = tokenCount > 0 ? estimateCost({ model, at, currency: 'CNY', ...tokens }) : null;
+        const requested = { at, searchRequests: delta.searchRequests, fetchRequests: delta.fetchRequests };
+        delta.toolsCostUsd = estimateSearchCost({ ...requested, currency: 'USD' }) || 0;
+        delta.toolsCostCny = estimateSearchCost({ ...requested, currency: 'CNY' }) || 0;
+        const values = [
+          delta.hitTokens,
+          delta.missTokens,
+          delta.outputTokens,
+          delta.searchRequests,
+          delta.fetchRequests,
+          delta.costUsd,
+          delta.costCny,
+          delta.toolsCostUsd,
+          delta.toolsCostCny,
+        ];
+        stmts.addDeepSeekTotals.run(model, ...values, at, at, timestamp);
+        stmts.addDeepSeekDay.run(day, model, ...values, timestamp);
+        booked.push(delta);
+      }
+    });
+    persist();
+    return { at, models: booked };
+  }
+
+  // Ten decimals, as each estimate is kept: the sum's binary-float tail goes.
+  const tenDecimals = (value) => Math.round(Number(value) * 1e10) / 1e10;
+  const nullableMoney = (value) => (value === null || value === undefined ? null : tenDecimals(value));
+
+  function deepseekSumsOf(row) {
+    return {
+      model: row.model,
+      hitTokens: Number(row.hit_tokens) || 0,
+      missTokens: Number(row.miss_tokens) || 0,
+      outputTokens: Number(row.output_tokens) || 0,
+      searchRequests: Number(row.search_requests) || 0,
+      fetchRequests: Number(row.fetch_requests) || 0,
+      turnCount: Number(row.turn_count) || 0,
+      costUsd: nullableMoney(row.cost_usd),
+      costCny: nullableMoney(row.cost_cny),
+      toolsCostUsd: tenDecimals(row.tools_cost_usd || 0),
+      toolsCostCny: tenDecimals(row.tools_cost_cny || 0),
+    };
+  }
+
+  function readDeepSeekUsageTotals() {
+    const models = stmts.listDeepSeekTotals.all().map((row) => ({
+      ...deepseekSumsOf(row),
+      firstSeenAt: row.first_seen_at || null,
+      lastSeenAt: row.last_seen_at || null,
+    }));
+    return { models };
+  }
+
+  /**
+   * The daily sums per model from `since` (a `YYYY-MM-DD` UTC day) on:
+   * `{ days: [{ day, model, ...sums }] }`, oldest first.
+   */
+  function readDeepSeekUsageDays({ since } = {}) {
+    const from = /^\d{4}-\d{2}-\d{2}$/.test(String(since ?? '')) ? String(since) : '0000-00-00';
+    const days = stmts.listDeepSeekDays.all(from).map((row) => ({ day: row.day, ...deepseekSumsOf(row) }));
+    // The first day the daily table holds: the history starts with the
+    // relay that brought it, not with the first DeepSeek turn.
+    const first = stmts.firstDeepSeekDay.get()?.day || null;
+    return { days, firstDay: first };
+  }
+
+  function deepseekBalanceReferenceOf(row) {
+    return {
+      currency: String(row.currency),
+      referenceTotal: Number(row.reference_total) || 0,
+      lastTotal: Number(row.last_total) || 0,
+      referenceAt: row.reference_at || null,
+      // When the balance last rose after the first read, and when the
+      // balance before that rise was read (migration 0029).
+      roseAt: row.rose_at || null,
+      roseFromAt: row.rose_from_at || null,
+    };
+  }
+
+  /** The balance references per currency (`recordDeepSeekBalance`). */
+  function readDeepSeekBalanceReferences() {
+    return stmts.listDeepSeekBalanceReferences.all().map(deepseekBalanceReferenceOf);
+  }
+
+  /**
+   * Notes a balance read (deepseek-balance-service.mjs's `{ ok: true,
+   * balances: [{ currency, total }] }`) for the balance meter, which shows
+   * what is left of the balance since the last top-up. Per currency the
+   * reference is the balance right after its latest rise (a top-up or a
+   * grant); before any rise was seen it is the highest balance seen, so the
+   * meter is full on the first read and fills with the spend. A failed read,
+   * or one repeated from the cache, changes nothing. Returns the references.
+   */
+  function recordDeepSeekBalance(balance) {
+    if (balance?.ok !== true || !Array.isArray(balance.balances)) return readDeepSeekBalanceReferences();
+    const readAt = toIsoTimestamp(balance.fetchedAt) || nowIso();
+    const timestamp = nowIso();
+    db.transaction(() => {
+      for (const entry of balance.balances) {
+        const currency = toTrimmedString(entry?.currency)?.toUpperCase();
+        const total = toFiniteNumber(entry?.total);
+        if (!currency || total === null || total < 0) continue;
+        const row = stmts.getDeepSeekBalanceReference.get(currency);
+        const rose = row ? total > Number(row.last_total) : false;
+        const reference = row && !rose ? Math.max(Number(row.reference_total) || 0, total) : total;
+        const referenceAt = !row || rose || reference !== Number(row.reference_total) ? readAt : (row.reference_at || readAt);
+        const roseAt = rose ? readAt : (row?.rose_at || null);
+        // The read before the rise: a row from before last_read_at was
+        // recorded at about the time it was read.
+        const roseFromAt = rose ? (row.last_read_at || row.updated_at || null) : (row?.rose_from_at || null);
+        stmts.upsertDeepSeekBalanceReference.run(currency, reference, total, referenceAt, timestamp, roseAt, readAt, roseFromAt);
+      }
+    })();
+    return readDeepSeekBalanceReferences();
+  }
+
   // Claude Cloud conversations keep their reported cost on the runtime
   // session row (migration 0007). That table is the relay's, not this
   // service's, so the statements are prepared on first use, and only once
@@ -464,6 +850,21 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
     grokConfigured = false,
     grokAllowances = null,
     grokBilling = null,
+    deepseekConfigured = false,
+    // The balance service's answer (deepseek-balance-service.mjs), or null.
+    deepseekBalance = null,
+    // The DeepSeek tab's monthly budget and its currency ('USD' or 'CNY'; null
+    // for a budget saved without one, read in the balance's currency), or null.
+    deepseekMonthlyBudget = null,
+    deepseekMonthlyBudgetCurrency = null,
+    deepseekStartingBalance = null,
+    // The imported DeepSeek export's figures of the saved key
+    // (deepseek-usage-import.mjs readActuals()), or null: read only, laid
+    // over the estimate by the card.
+    deepseekActuals = null,
+    // The Claude API card, built by its own module (plan-usage-claude-api.mjs)
+    // from the Claude API booking; null while Claude API has no key and is off.
+    claudeApiCard = null,
   } = {}) {
     const generatedAt = nowIso();
     const claudeSnapshot = readSnapshot('claude');
@@ -513,6 +914,8 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
           configured: true,
         })
         : null,
+      // Opt-in too, and next to the Claude cards: the same models on a key.
+      claudeApiCard || null,
       buildCursorPlanCard({
         totals: cursorCycle.totals,
         allowances,
@@ -544,6 +947,34 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
       }));
     }
 
+    // Opt-in like Grok: no card while DeepSeek is off.
+    if (deepseekConfigured === true) {
+      // The daily chart's 30 days and this calendar month, whichever reaches
+      // further back (UTC days, like the booking).
+      const today = generatedAt.slice(0, 10);
+      const monthStart = `${today.slice(0, 7)}-01`;
+      const thirtyDaysAgo = new Date(Date.parse(`${today}T00:00:00.000Z`) - 29 * 86_400_000).toISOString().slice(0, 10);
+      // The daily rows reach back to the export's first day too, so the card
+      // can take the estimate of every day the export covers out of the totals.
+      const firstActualDay = [
+        ...(Array.isArray(deepseekActuals?.rows) ? deepseekActuals.rows : []),
+        ...(Array.isArray(deepseekActuals?.coveredDays) ? deepseekActuals.coveredDays : []),
+      ].map((row) => String(row?.day || '')).filter((value) => /^\d{4}-\d{2}-\d{2}$/.test(value)).sort()[0] || null;
+      const since = [thirtyDaysAgo, monthStart, firstActualDay].filter(Boolean).sort()[0];
+      providers.push(buildDeepSeekPlanCard({
+        balance: deepseekBalance,
+        balanceReferences: recordDeepSeekBalance(deepseekBalance),
+        totals: readDeepSeekUsageTotals(),
+        days: readDeepSeekUsageDays({ since }),
+        monthlyBudget: deepseekMonthlyBudget,
+        monthlyBudgetCurrency: deepseekMonthlyBudgetCurrency,
+        startingBalance: deepseekStartingBalance,
+        now: generatedAt,
+        configured: true,
+        actuals: deepseekActuals,
+      }));
+    }
+
     return {
       version: PLAN_USAGE_VERSION,
       generatedAt,
@@ -560,6 +991,11 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
     recordGrokUsageReport,
     readGrokCycleTotals,
     resetGrokAccounting,
+    recordDeepSeekUsageReport,
+    readDeepSeekUsageTotals,
+    readDeepSeekUsageDays,
+    recordDeepSeekBalance,
+    readDeepSeekBalanceReferences,
     readClaudeCloudSpend,
     buildReport,
     pools: CURSOR_POOLS,

package/server/services/provider-model-selection.mjs

@@ -90,7 +90,7 @@ export function resolveProviderModelSelection({
   };
 }
 
-// ─── Checking a model an agent names (remote_relay create_session / send) ───
+// ─── Checking a model an agent names (relay_tool create_session / send) ───
 
 const PROVIDER_LABELS = Object.freeze({
   github: 'Copilot',
@@ -99,8 +99,10 @@ const PROVIDER_LABELS = Object.freeze({
   cursor: 'Cursor',
   grok: 'Grok',
   'claude-cloud': 'Claude Cloud',
+  deepseek: 'DeepSeek',
+  'claude-api': 'Claude API',
 });
-const CLAUDE_PROVIDERS = new Set(['claude', 'claude-cloud']);
+const CLAUDE_PROVIDERS = new Set(['claude', 'claude-cloud', 'claude-api']);
 const LONG_CONTEXT_SUFFIX = /\[1m\]$/i;
 // A Copilot model with its effort, as the composer sends it ("gpt-5.4-high").
 const EFFORT_VARIANT_SUFFIX = /-(none|minimal|low|medium|high|xhigh|max)$/i;

package/server/services/provider-reasoning-effort.mjs

@@ -1,5 +1,6 @@
 'use strict';
 
+import { DEEPSEEK_REASONING_EFFORTS } from '../../shared/deepseek-models.mjs';
 import { openAIReasoningEffortsForModel } from '../../shared/openai-reasoning.mjs';
 
 // 'ultracode' is not an Agent SDK EffortLevel: it is a relay-side sentinel for
@@ -44,6 +45,7 @@ export function supportedReasoningEffortsForProviderModel({
   model = '',
   cursorSettings = null,
   claudeSettings = null,
+  claudeApiSettings = null,
   grokSettings = null,
   reasoningByModel = null,
 } = {}) {
@@ -52,11 +54,21 @@ export function supportedReasoningEffortsForProviderModel({
   if (provider === 'claude') {
     return effortsForModel(claudeSettings?.effortsByModel, model) || [...DEFAULT_CLAUDE_REASONING_EFFORTS];
   }
+  // Claude API runs the same CLI as Claude: its levels are the Claude
+  // provider's (Ultracode included), narrowed by what Anthropic's model list
+  // says about the model (claude-api-settings-service.mjs).
+  if (provider === 'claude-api') {
+    return effortsForModel(claudeApiSettings?.effortsByModel, model)
+      || effortsForModel(claudeSettings?.effortsByModel, model)
+      || [...DEFAULT_CLAUDE_REASONING_EFFORTS];
+  }
   if (provider === 'grok') {
     return effortsForModel(grokSettings?.effortsByModel, model) || [...DEFAULT_GROK_REASONING_EFFORTS];
   }
   // A cloud session takes no effort choice: the only tier is the default one.
   if (provider === 'claude-cloud') return [...CLAUDE_CLOUD_REASONING_EFFORTS];
+  // DeepSeek's levels are the same for every model it serves.
+  if (provider === 'deepseek') return [...DEEPSEEK_REASONING_EFFORTS];
   if (provider === 'openai' || provider === 'openai-image') {
     const efforts = openAIReasoningEffortsForModel(model);
     return Array.isArray(efforts) && efforts.length ? efforts.map(normalizeEffort).filter(Boolean) : null;
@@ -72,18 +84,28 @@ export function supportedReasoningEffortsForProviderModel({
 // `strict` reproduces the one provider that refuses rather than clamps: OpenAI
 // answers an unsupported effort with a 400, so bootstrap must not store a value
 // the first send would reject.
+//
+// `defaultEffort` replaces the off-switch as the answer to an unstated effort
+// (DeepSeek thinks at `high` unless told otherwise), and `aliasFor` maps a
+// request into the provider's own levels before it is checked.
 export function resolveProviderReasoningEffort({
   requestedEffort = '',
   supportedEfforts = null,
   strict = false,
+  defaultEffort = '',
+  aliasFor = null,
 } = {}) {
-  const requested = normalizeEffort(requestedEffort);
+  const raw = normalizeEffort(requestedEffort);
+  const requested = raw && typeof aliasFor === 'function' ? (normalizeEffort(aliasFor(raw)) || raw) : raw;
   const supported = Array.isArray(supportedEfforts)
     ? supportedEfforts.map(normalizeEffort).filter(Boolean)
     : null;
   if (!supported) return { ok: true, effort: requested, supported: [] };
   const providerDefault = supported.includes('none') ? 'none' : (supported[0] || '');
-  if (!requested) return { ok: true, effort: providerDefault, supported };
+  const preferredDefault = normalizeEffort(defaultEffort);
+  if (!requested) {
+    return { ok: true, effort: supported.includes(preferredDefault) ? preferredDefault : providerDefault, supported };
+  }
   if (supported.includes(requested)) return { ok: true, effort: requested, supported };
   if (strict) {
     return {

package/server/services/relay-ask-service.mjs

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Questions that don't block: remote_relay's `ask` (shared/relay-asks.mjs).
+ * Questions that don't block: relay_tool's `ask` (shared/relay-asks.mjs).
  * An agent asks the owner something and goes on working; the question shows
  * as a card in its session and in the Inbox, and when the owner answers or
  * dismisses it the relay tells the session the ask is in and the

package/server/services/relay-event-service.mjs

@@ -107,6 +107,7 @@ import {
   relayEventQuietWindowEnd,
   relayEventTypesTake,
 } from '../../shared/relay-events.mjs';
+import { REMOTE_RELAY_APPROVAL_SOURCE } from '../../shared/relay-asks.mjs';
 
 export const RELAY_EVENT_SUBSCRIPTIONS_SOCKET_EVENT = 'relay_event_subscriptions';
 export const RELAY_EVENT_SELF_RELAY_ID = 'self';
@@ -2307,8 +2308,8 @@ export function createRelayEventService({
       prompt: String(question.prompt || question.question || '').slice(0, 2000),
       options,
       questionId: toText(question.id),
-      ...(toText(context?.source) === 'remote_relay' ? { approvalCard: true } : {}),
-      // A question that does not block (remote_relay ask).
+      ...(toText(context?.source) === REMOTE_RELAY_APPROVAL_SOURCE ? { approvalCard: true } : {}),
+      // A question that does not block (relay_tool ask).
       ...(toText(question.kind) === 'ask' ? { kind: 'ask' } : {}),
     });
   }

package/server/services/relay-schedule-service.mjs

@@ -2,7 +2,7 @@
 
 /**
  * Relay schedules: a prompt the relay queues into a session at a set time,
- * once or every N minutes (remote_relay's `schedule`). An agent's own timers
+ * once or every N minutes (relay_tool's `schedule`). An agent's own timers
  * die with the relay; these live in the database (migrations/0022-relay-schedules.mjs)
  * and their timers are rebuilt at boot.
  *

package/server/services/remote-relay-caller-context.mjs

@@ -118,6 +118,13 @@ function describeRemoteTurn(action, args, caller, group = null) {
     const provider = requested || (REMOTE_RELAY_PROVIDERS.includes(callerProvider) ? callerProvider : 'github');
     parts.push(`Provider: ${provider}`);
   }
+  // A send that names a Claude billing moves the session to it with the
+  // message: who pays for its turns changes, so the card says so.
+  if (action === 'send') {
+    const billing = toText(args.provider).toLowerCase();
+    if (billing === 'claude-api') parts.push('Switches billing to API key');
+    else if (billing === 'claude') parts.push('Switches billing to subscription');
+  }
   if (toText(args.model)) parts.push(`Model: ${excerpt(args.model)}`);
   if (toText(args.cwd)) parts.push(`Folder: ${excerpt(args.cwd)}`);
   if (action === 'create_session') {