@oar-sh/oar 0.9.16 → 0.9.18

package/server/claude-worker/claude-turn-publisher.mjs

@@ -1,10 +1,16 @@
 import fs from 'node:fs';
-import { classifyClaudeResultFailure, claudeFailureGuidance } from './claude-turn-failure.mjs';
+import {
+  CLAUDE_LIVE_FLAG_SETTINGS_CODE,
+  CLAUDE_LIVE_FLAG_SETTINGS_GUIDANCE,
+  classifyClaudeResultFailure,
+  claudeFailureGuidance,
+} from './claude-turn-failure.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
 import { buildSteerSettleFailure, steerSettleFailureText } from '../../shared/steer-settle-failure.mjs';
 import { buildUsageLimitFailure } from '../../shared/claude-usage-limit.mjs';
 import { WORKING_DIRECTORY_MISSING_CODE, isWorkingDirectoryMissingError } from '../../shared/worker-runtime/working-directory.mjs';
+import { claudeBillingTotals, claudeSearchTotals, claudeToolRequests, claudeUsageTotals } from './claude-usage-totals.mjs';
 
 const PLAN_BOARD_ACTIONS = [
   { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
@@ -61,7 +67,60 @@ export function buildClaudePlanReadyBoardPayload({ message, planText = '' } = {}
  * mutable turn state, so the session process can run any number of turns
  * (delivered or background-continuation) through one publisher.
  */
-export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRuns = null } = {}) {
+export function createClaudeTurnPublisher({
+  api,
+  dbg = () => {},
+  takeWorkflowRuns = null,
+  // A backend's own reading of a failed request (`{ code, guidance }` or
+  // null) and its name in the notes; null for Claude. It gets the error a
+  // turn ended with, when there is one, beside its text and status.
+  describeFailure = null,
+  runtimeLabel = 'Claude',
+  // The namespace of a backend's failure codes (DeepSeek: `deepseek`): its
+  // failures print as `relay.deepseek-<code>`, which the browser's buttons
+  // key on (relay-error-ctas.mjs), not as Claude's `relay.claude-<code>`.
+  failureCodePrefix = null,
+  // False for a backend that is not Claude's: no Claude plan windows or cost.
+  reportsPlanUsage = true,
+  // A backend's own usage route (DeepSeek: /api/deepseek-plan-usage), which
+  // takes the CLI's token totals per model in place of the Claude plan
+  // usage, and the relay's id of a model the CLI names.
+  usageRoute = null,
+  usageModelKey = null,
+  // The relay's id of a model the backend's CLI names ("deepseek-flash[1m]"
+  // → "deepseek-flash"); identity for Claude, whose `[1m]` is a real tier.
+  relayModel = (value) => value,
+  // The Claude API booking (POST /api/claude-api-usage), which both Claude
+  // workers report to after every turn, whatever else they report: a chat
+  // moves between the subscription and the key and keeps its session.
+  // `billingKind` is the worker's kind.
+  billingUsageRoute = null,
+  billingKind = null,
+} = {}) {
+  /** `{ code, stableCode }` of a failure code, in the backend's namespace. */
+  function failureCodes(code) {
+    if (!failureCodePrefix) return { code, stableCode: `claude.${code}` };
+    const prefixed = String(code).startsWith(`${failureCodePrefix}-`) ? code : `${failureCodePrefix}-${String(code).replace(/_/g, '-')}`;
+    return { code: prefixed, stableCode: prefixed };
+  }
+
+  /**
+   * The Claude reading of a failed result, in the backend's namespace. A
+   * backend gets no Claude account or sign-in advice: the relay's default
+   * fits where the backend has none of its own.
+   */
+  function classifyResultFailure(result) {
+    const classified = classifyClaudeResultFailure(result);
+    if (!failureCodePrefix) return classified;
+    return { ...failureCodes(classified.code), guidance: classified.code === 'model_not_found' ? classified.guidance : null };
+  }
+
+  function backendFailure(errorText, status = null, error = null) {
+    if (typeof describeFailure !== 'function') return null;
+    const described = describeFailure(errorText, { status, ...(error ? { error } : {}) });
+    return described?.code ? described : null;
+  }
+
   function drainWorkflowRuns({ terminal = false } = {}) {
     if (terminal || typeof takeWorkflowRuns !== 'function') return null;
     return takeWorkflowRuns();
@@ -150,11 +209,14 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
    */
   async function publishContextUsage({ message, state, model, sdkSessionId }) {
     if (!state.contextUsage && !state.modelUsage) return;
+    const contextUsage = state.contextUsage && typeof state.contextUsage === 'object' && state.contextUsage.model
+      ? { ...state.contextUsage, model: relayModel(state.contextUsage.model) }
+      : state.contextUsage;
     await api('POST', '/api/claude-context-usage', {
       conversationId: message.conversationId,
       sdkSessionId,
-      model: state.responseModel || model || null,
-      contextUsage: state.contextUsage,
+      model: relayModel(state.responseModel || model || null),
+      contextUsage,
       modelUsage: state.modelUsage,
     }).catch((error) => {
       dbg('context usage publish failed', error?.message || String(error));
@@ -167,7 +229,13 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
    * control request is unavailable, so the card still gets session cost.
    * Advisory: a failure here must not disturb the turn's response.
    */
-  async function publishPlanUsage({ message, state, sdkSessionId }) {
+  async function publishPlanUsage({ message, state, sdkSessionId, runId = '', resumedSessionId = '' }) {
+    if (billingUsageRoute) await publishBillingUsage({ message, state, sdkSessionId, runId, resumedSessionId });
+    if (usageRoute) {
+      await publishBackendUsage({ message, state, sdkSessionId, runId, resumedSessionId });
+      return;
+    }
+    if (!reportsPlanUsage) return;
     const totalCostUsd = state.result?.totalCostUsd ?? null;
     // A cost with no per-model breakdown is still a usable fallback payload, so
     // it has to count as a reason to publish or the card loses session cost on
@@ -184,6 +252,283 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
     });
   }
 
+  // The CLI process's own token totals and web search and fetch counts per
+  // model, counted from zero for each process (`runId`) and CLI session id
+  // (a `/clear` changes it and starts the CLI's totals over). `lastSession`
+  // is the CLI's running totals per model at the last result they were taken
+  // from, `lastSearches` its running search counts the same way, `results`
+  // how many results the process has reported, and
+  // `countedStates` the turn states already added: a turn published twice
+  // (a stopped turn's chain and the stream's end) counts once.
+  const run = { key: '', runId: '', results: 0, totals: new Map(), requests: new Map(), lastSession: new Map(), lastSearches: new Map() };
+  const countedStates = new WeakSet();
+
+  const addTotals = (into, entries) => {
+    for (const entry of entries) {
+      const current = into.get(entry.model) || { model: entry.model, hitTokens: 0, missTokens: 0, outputTokens: 0 };
+      current.hitTokens += entry.hitTokens;
+      current.missTokens += entry.missTokens;
+      current.outputTokens += entry.outputTokens;
+      into.set(entry.model, current);
+    }
+  };
+
+  /**
+   * The process's running totals and request counts after this turn, as
+   * `{ totals: [{ model, hitTokens, missTokens, outputTokens }], requests:
+   * [{ model, searchRequests, fetchRequests }] }` without the all-zero
+   * models. Without a run id (a caller that has none) the CLI's own totals
+   * and the turn's counts, as before.
+   *
+   * A result's `modelUsage` is the CLI session's running total per model
+   * (sub-agents included), so the turn's share is what it grew by since the
+   * process's last result. The first result of a process spawned to resume
+   * a session carries that session's earlier turns too, which the relay has
+   * already booked: that turn's share is the result's `usage`, the turn's
+   * own count, under the turn's model (it leaves out what sub-agents spent
+   * in that one turn). A process spawned fresh, or a session the CLI
+   * started over, reports from zero: its first result is all its own. A
+   * result without `modelUsage` adds its `usage`. The baseline the growth
+   * is measured from only rises, field by field per model: a result's
+   * totals below it belong to an older turn published late.
+   *
+   * Web searches come from the same place as the tokens: the CLI counts
+   * them per model in `modelUsage`, the WebSearch tool's own API request
+   * included, which the message stream (`serverToolUse`) never shows. They
+   * grow, rise and resume like the tokens; the stream's count stands in
+   * where the tokens fall back to `usage` (no `modelUsage`, the resumed
+   * first result) and for a CLI that reports no search count. Fetches only
+   * the stream counts.
+   */
+  function runningCounts(state, result, { runId, sessionId, resumedSessionId, modelKey }) {
+    const model = result.model || state.responseModel;
+    const turnRequests = claudeToolRequests(result.serverToolUse, modelKey);
+    if (!runId) return { totals: claudeUsageTotals(result.modelUsage, { usage: result.usage, model, ...modelKey }), requests: turnRequests };
+    if (run.runId !== runId) {
+      run.runId = runId;
+      run.results = 0;
+    }
+    const key = `${runId}\n${sessionId}`;
+    if (run.key !== key) {
+      run.key = key;
+      run.totals = new Map();
+      run.requests = new Map();
+      run.lastSession = new Map();
+      run.lastSearches = new Map();
+    }
+    if (!countedStates.has(state)) {
+      countedStates.add(state);
+      const hasModelUsage = Boolean(result.modelUsage) && typeof result.modelUsage === 'object' && !Array.isArray(result.modelUsage);
+      const turnUsage = claudeUsageTotals(null, { usage: result.usage, model, ...modelKey });
+      const sessionSearches = hasModelUsage ? claudeSearchTotals(result.modelUsage, modelKey) : [];
+      // The searches this turn adds, per model: the stream's unless the
+      // CLI's running count below says more reliably.
+      let turnSearches = turnRequests.map((entry) => ({ model: entry.model, searchRequests: entry.searchRequests }));
+      if (!hasModelUsage) {
+        // The CLI's running totals grew by the turn, as far as this goes.
+        addTotals(run.totals, turnUsage);
+        addTotals(run.lastSession, turnUsage);
+        for (const entry of turnSearches) {
+          run.lastSearches.set(entry.model, (run.lastSearches.get(entry.model) || 0) + entry.searchRequests);
+        }
+      } else {
+        const session = claudeUsageTotals(result.modelUsage, modelKey);
+        const resumed = run.results === 0 && Boolean(resumedSessionId) && sessionId === resumedSessionId;
+        if (resumed) {
+          addTotals(run.totals, turnUsage);
+        } else {
+          const grown = session.map((entry) => {
+            const last = run.lastSession.get(entry.model) || { hitTokens: 0, missTokens: 0, outputTokens: 0 };
+            return {
+              model: entry.model,
+              hitTokens: Math.max(0, entry.hitTokens - last.hitTokens),
+              missTokens: Math.max(0, entry.missTokens - last.missTokens),
+              outputTokens: Math.max(0, entry.outputTokens - last.outputTokens),
+            };
+          });
+          addTotals(run.totals, grown);
+          if (sessionSearches.length) {
+            turnSearches = sessionSearches.map((entry) => ({
+              model: entry.model,
+              searchRequests: Math.max(0, entry.searchRequests - (run.lastSearches.get(entry.model) || 0)),
+            }));
+          }
+        }
+        // The baseline only ever rises: the CLI's totals are cumulative, so a
+        // snapshot below the last one is an older result arriving late (a
+        // stopped turn's publish chain behind a newer turn's), and taking it
+        // as the baseline would book the newer turn's growth a second time.
+        for (const entry of session) {
+          const last = run.lastSession.get(entry.model) || { model: entry.model, hitTokens: 0, missTokens: 0, outputTokens: 0 };
+          run.lastSession.set(entry.model, {
+            model: entry.model,
+            hitTokens: Math.max(last.hitTokens, entry.hitTokens),
+            missTokens: Math.max(last.missTokens, entry.missTokens),
+            outputTokens: Math.max(last.outputTokens, entry.outputTokens),
+          });
+        }
+        for (const entry of sessionSearches) {
+          run.lastSearches.set(entry.model, Math.max(run.lastSearches.get(entry.model) || 0, entry.searchRequests));
+        }
+      }
+      const addRequests = (entryModel, searchRequests, fetchRequests) => {
+        const current = run.requests.get(entryModel) || { model: entryModel, searchRequests: 0, fetchRequests: 0 };
+        current.searchRequests += searchRequests;
+        current.fetchRequests += fetchRequests;
+        run.requests.set(entryModel, current);
+      };
+      for (const entry of turnSearches) addRequests(entry.model, entry.searchRequests, 0);
+      for (const entry of turnRequests) addRequests(entry.model, 0, entry.fetchRequests);
+      run.results += 1;
+    }
+    // Copies: the running entries go on changing after the post.
+    return {
+      totals: [...run.totals.values()].filter((entry) => entry.hitTokens + entry.missTokens + entry.outputTokens > 0).map((entry) => ({ ...entry })),
+      requests: [...run.requests.values()].filter((entry) => entry.searchRequests + entry.fetchRequests > 0).map((entry) => ({ ...entry })),
+    };
+  }
+
+  /**
+   * Ship the CLI process's token totals per model after a turn, with the
+   * CLI's session id, the id of the process (`runId`) and the time. They are
+   * the process's own running totals, counted from zero (runningCounts): the
+   * relay books what each report adds under the run id, a report below the
+   * last one under it is stale, and a new run id is booked in full. The
+   * process's running counts of web searches and fetches ride along as
+   * `requests`, per model, booked the same way. A caller without a run id
+   * sends the CLI's session totals and the turn's counts, which the relay
+   * books as an older worker's. `resumedSessionId` is the session the process
+   * was spawned to resume, if any. Advisory, like the plan usage.
+   */
+  async function publishBackendUsage({ message, state, sdkSessionId, runId = '', resumedSessionId = '' }) {
+    const result = state.result;
+    const claudeNativeSessionId = String(result?.sessionId || '').trim();
+    if (!usageRoute || !claudeNativeSessionId) return;
+    const modelKey = typeof usageModelKey === 'function' ? { modelKey: usageModelKey } : {};
+    const { totals, requests } = runningCounts(state, result, {
+      runId: String(runId || ''),
+      sessionId: claudeNativeSessionId,
+      resumedSessionId: String(resumedSessionId || '').trim(),
+      modelKey,
+    });
+    if (!totals.length && !requests.length) return;
+    await api('POST', usageRoute, {
+      conversationId: message.conversationId,
+      sdkSessionId,
+      claudeNativeSessionId,
+      ...(runId ? { runId } : {}),
+      at: new Date().toISOString(),
+      totals,
+      ...(requests.length ? { requests } : {}),
+    }).catch((error) => {
+      dbg('backend usage publish failed', error?.message || String(error));
+    });
+  }
+
+  // The process's own totals per model with their cost, for the Claude API
+  // booking: counted like `run` above, per process and CLI session, with the
+  // CLI's cost estimate beside the tokens. A resumed process's first result
+  // adds the turn's `usage` (its main agent loop, no cost); the relay books
+  // that turn from the session totals the report carries as well.
+  const billingRun = { key: '', results: 0, totals: new Map(), lastSession: new Map() };
+  const billedStates = new WeakSet();
+
+  function billingCounts(state, result, { runId, sessionId, resumedSessionId }) {
+    const model = result.model || state.responseModel;
+    const key = `${runId}\n${sessionId}`;
+    if (billingRun.key !== key) {
+      billingRun.key = key;
+      billingRun.results = 0;
+      billingRun.totals = new Map();
+      billingRun.lastSession = new Map();
+    }
+    const firstResultOfRun = billingRun.results === 0;
+    const session = claudeBillingTotals(result.modelUsage, { usage: result.usage, model });
+    const add = (entries) => {
+      for (const entry of entries) {
+        const current = billingRun.totals.get(entry.model) || { model: entry.model, hitTokens: 0, missTokens: 0, outputTokens: 0, costUsd: 0, costUnknown: false };
+        current.hitTokens += entry.hitTokens;
+        current.missTokens += entry.missTokens;
+        current.outputTokens += entry.outputTokens;
+        current.costUsd += entry.costUsd;
+        current.costUnknown = current.costUnknown || entry.costUnknown;
+        billingRun.totals.set(entry.model, current);
+      }
+    };
+    if (!billedStates.has(state)) {
+      billedStates.add(state);
+      const hasModelUsage = Boolean(result.modelUsage) && typeof result.modelUsage === 'object' && !Array.isArray(result.modelUsage);
+      const resumed = firstResultOfRun && Boolean(resumedSessionId) && sessionId === resumedSessionId;
+      if (!hasModelUsage || resumed) {
+        add(claudeBillingTotals(null, { usage: result.usage, model }));
+      } else {
+        add(session.map((entry) => {
+          const last = billingRun.lastSession.get(entry.model) || { hitTokens: 0, missTokens: 0, outputTokens: 0, costUsd: 0 };
+          return {
+            model: entry.model,
+            hitTokens: Math.max(0, entry.hitTokens - last.hitTokens),
+            missTokens: Math.max(0, entry.missTokens - last.missTokens),
+            outputTokens: Math.max(0, entry.outputTokens - last.outputTokens),
+            costUsd: Math.max(0, entry.costUsd - last.costUsd),
+            costUnknown: entry.costUnknown,
+          };
+        }));
+      }
+      // The baseline only rises: a late result of an older turn below it
+      // must not make the next one count twice.
+      if (hasModelUsage) {
+        for (const entry of session) {
+          const last = billingRun.lastSession.get(entry.model) || { hitTokens: 0, missTokens: 0, outputTokens: 0, costUsd: 0 };
+          billingRun.lastSession.set(entry.model, {
+            hitTokens: Math.max(last.hitTokens, entry.hitTokens),
+            missTokens: Math.max(last.missTokens, entry.missTokens),
+            outputTokens: Math.max(last.outputTokens, entry.outputTokens),
+            costUsd: Math.max(last.costUsd, entry.costUsd),
+          });
+        }
+      }
+      billingRun.results += 1;
+    }
+    return {
+      firstResultOfRun,
+      runCounts: [...billingRun.totals.values()].map((entry) => ({ ...entry })),
+      sessionTotals: session,
+    };
+  }
+
+  /**
+   * Ship the turn's counts to the Claude API booking: the process's own
+   * running totals (`runCounts`) and the CLI's session totals
+   * (`sessionTotals`), with the worker's kind, the process (`runId`), the
+   * session it resumed, and the turn (`turnId`). Advisory, like the plan usage.
+   */
+  async function publishBillingUsage({ message, state, sdkSessionId, runId = '', resumedSessionId = '' }) {
+    const result = state.result;
+    const claudeNativeSessionId = String(result?.sessionId || '').trim();
+    if (!billingUsageRoute || !claudeNativeSessionId || !runId) return;
+    const { firstResultOfRun, runCounts, sessionTotals } = billingCounts(state, result, {
+      runId: String(runId),
+      sessionId: claudeNativeSessionId,
+      resumedSessionId: String(resumedSessionId || '').trim(),
+    });
+    if (!runCounts.length && !sessionTotals.length) return;
+    await api('POST', billingUsageRoute, {
+      conversationId: message.conversationId,
+      sdkSessionId,
+      claudeNativeSessionId,
+      runId: String(runId),
+      billing: billingKind || null,
+      turnId: String(message.id || '') || null,
+      at: new Date().toISOString(),
+      firstResultOfRun,
+      ...(resumedSessionId ? { resumedSessionId: String(resumedSessionId) } : {}),
+      runCounts,
+      sessionTotals,
+    }).catch((error) => {
+      dbg('billing usage publish failed', error?.message || String(error));
+    });
+  }
+
   /**
    * Ship what the CLI reported about the subscription's usage limit: the
    * relay warns before the limit and shows the reset once it is reached.
@@ -353,7 +698,8 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
   async function publishErrorResult({ message, state, responseModel, consumedSteerIds = null }) {
     const result = state.result;
     const errorText = result.text
-      || `Claude turn failed (${result.subtype || 'unknown error'}).`;
+      || `${runtimeLabel} turn failed (${result.subtype || 'unknown error'}).`;
+    const described = backendFailure(errorText, result.apiErrorStatus);
     await publishFinalStream(message, state.lastStreamedText);
     // Refused at the usage limit: a relay that knows the kind pauses the turn
     // until the reset instead of failing it.
@@ -382,7 +728,8 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
         // Never built from the subtype alone: a refused turn ends with
         // subtype 'success'. An account failure brings its own advice, since
         // sending the message again cannot help before the account is fixed.
-        ...classifyClaudeResultFailure(result),
+        ...classifyResultFailure(result),
+        ...(described ? { ...failureCodes(described.code), guidance: described.guidance } : {}),
         message: errorText,
         failedAt: new Date().toISOString(),
         queueMessageId: String(message.id || '') || null,
@@ -400,6 +747,24 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
       });
       return;
     }
+    // Claude Code did not take a backend's connection settings (its key and
+    // endpoint pins): nothing was sent, and no sign-in changes that.
+    if (error?.code === CLAUDE_LIVE_FLAG_SETTINGS_CODE) {
+      await publishResponse(message, {
+        text: `System note: ${error.message} ${CLAUDE_LIVE_FLAG_SETTINGS_GUIDANCE}`,
+        model: null,
+        terminalError: {
+          kind: 'claude-turn-failed',
+          code: CLAUDE_LIVE_FLAG_SETTINGS_CODE,
+          stableCode: `claude.${CLAUDE_LIVE_FLAG_SETTINGS_CODE}`,
+          message: error.message,
+          guidance: CLAUDE_LIVE_FLAG_SETTINGS_GUIDANCE,
+          failedAt: new Date().toISOString(),
+          queueMessageId: String(message.id || '') || null,
+        },
+      });
+      return;
+    }
     // The conversation's folder is gone: the error names it and says what to
     // do, which neither a retry nor a sign-in changes.
     if (isWorkingDirectoryMissingError(error)) {
@@ -408,8 +773,7 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
         model: null,
         terminalError: {
           kind: 'claude-turn-failed',
-          code: WORKING_DIRECTORY_MISSING_CODE,
-          stableCode: `claude.${WORKING_DIRECTORY_MISSING_CODE}`,
+          ...failureCodes(WORKING_DIRECTORY_MISSING_CODE),
           message: error.message,
           guidance: error.guidance,
           failedAt: new Date().toISOString(),
@@ -418,16 +782,33 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
       });
       return;
     }
-    const isAuthError = /authentication|logged in|login|credential|api key/i.test(errorText);
+    const described = backendFailure(errorText, null, error);
+    if (described) {
+      await publishResponse(message, {
+        text: `System note: the ${runtimeLabel} turn failed (${errorText}). ${described.guidance}`,
+        model: null,
+        terminalError: {
+          kind: 'claude-turn-failed',
+          ...failureCodes(described.code),
+          message: errorText,
+          guidance: described.guidance,
+          failedAt: new Date().toISOString(),
+          queueMessageId: String(message.id || '') || null,
+        },
+      });
+      return;
+    }
+    // A backend's sign-in failures are its describeFailure's; Claude's sign-in
+    // advice is never a backend's.
+    const isAuthError = !failureCodePrefix && /authentication|logged in|login|credential|api key/i.test(errorText);
     await publishResponse(message, {
       text: isAuthError
         ? `System note: the Claude runtime could not authenticate (${errorText}). Log in again from Settings → Providers → Claude → Relogin (or run \`claude\` on the relay host), then retry.`
-        : `System note: the Claude turn failed (${errorText}). Retry or send a new message.`,
+        : `System note: the ${runtimeLabel} turn failed (${errorText}). Retry or send a new message.`,
       model: null,
       terminalError: {
         kind: 'claude-turn-failed',
-        code: isAuthError ? 'authentication_failed' : 'turn-error',
-        stableCode: isAuthError ? 'claude.authentication_failed' : 'claude.turn-error',
+        ...failureCodes(isAuthError ? 'authentication_failed' : 'turn-error'),
         message: errorText,
         ...(isAuthError ? { guidance: claudeFailureGuidance('authentication_failed') } : {}),
         failedAt: new Date().toISOString(),

package/server/claude-worker/claude-usage-totals.mjs

@@ -0,0 +1,161 @@
+// The CLI's token totals per model, out of a result message.
+//
+// A result's `modelUsage` is the CLI session's running total, not the turn's:
+// a long-lived CLI reports more on every turn, a CLI resumed on a session
+// starts from the totals that session's transcript saved (its first result
+// already carries the earlier turns), and a `/clear` starts it over. Its
+// `usage` is the turn's own, and the main agent loop's only (sub-agents and
+// auxiliary calls are left out). The publisher turns these into the
+// process's own running totals (claude-turn-publisher.mjs, runningCounts),
+// which the relay books per process (plan-usage-service.mjs,
+// recordDeepSeekUsageReport).
+
+function count(value) {
+  const number = Number(value ?? 0);
+  return Number.isFinite(number) && number > 0 ? Math.round(number) : 0;
+}
+
+function addTo(totals, model, hit, miss, output) {
+  const current = totals.get(model) || { model, hitTokens: 0, missTokens: 0, outputTokens: 0 };
+  current.hitTokens += hit;
+  current.missTokens += miss;
+  current.outputTokens += output;
+  totals.set(model, current);
+}
+
+/**
+ * `[{ model, hitTokens, missTokens, outputTokens }]`: cache reads are hits,
+ * fresh and cache-creation input are misses. `modelKey` maps the CLI's name
+ * of a model to the relay's (DeepSeek: without the `[1m]` suffix); entries
+ * that map to the same id are summed. `usage` stands in only for a result
+ * without `modelUsage`, under the turn's model (pass `modelUsage` as null to
+ * read `usage` alone). Models with no tokens are left out.
+ */
+export function claudeUsageTotals(modelUsage, {
+  usage = null,
+  model = '',
+  modelKey = (value) => String(value ?? '').trim(),
+} = {}) {
+  const keyOf = (value) => String(modelKey(value) ?? '').trim().toLowerCase();
+  const totals = new Map();
+  if (modelUsage && typeof modelUsage === 'object' && !Array.isArray(modelUsage)) {
+    for (const [name, entry] of Object.entries(modelUsage)) {
+      const key = keyOf(name);
+      if (!key || !entry || typeof entry !== 'object') continue;
+      addTo(
+        totals,
+        key,
+        count(entry.cacheReadInputTokens),
+        count(entry.inputTokens) + count(entry.cacheCreationInputTokens),
+        count(entry.outputTokens),
+      );
+    }
+  } else {
+    const key = keyOf(model);
+    if (key && usage && typeof usage === 'object') {
+      addTo(
+        totals,
+        key,
+        count(usage.cache_read_input_tokens),
+        count(usage.input_tokens) + count(usage.cache_creation_input_tokens),
+        count(usage.output_tokens),
+      );
+    }
+  }
+  return [...totals.values()].filter((entry) => entry.hitTokens + entry.missTokens + entry.outputTokens > 0);
+}
+
+/**
+ * The CLI's running count of web searches per model, `[{ model,
+ * searchRequests }]`, out of a result's `modelUsage`: the CLI adds every API
+ * request's `server_tool_use.web_search_requests` to it, the internal request
+ * its WebSearch tool makes included, which never shows up in the message
+ * stream. Same `modelKey` and summing as the token totals. Only the entries
+ * that carry the count, zero included, so an empty list means the CLI does
+ * not report it. It has no fetch count.
+ */
+export function claudeSearchTotals(modelUsage, { modelKey = (value) => String(value ?? '').trim() } = {}) {
+  const searches = new Map();
+  if (!modelUsage || typeof modelUsage !== 'object' || Array.isArray(modelUsage)) return [];
+  for (const [name, entry] of Object.entries(modelUsage)) {
+    const key = String(modelKey(name) ?? '').trim().toLowerCase();
+    if (!key || !entry || typeof entry !== 'object' || !Number.isFinite(Number(entry.webSearchRequests ?? NaN))) continue;
+    const current = searches.get(key) || { model: key, searchRequests: 0 };
+    current.searchRequests += count(entry.webSearchRequests);
+    searches.set(key, current);
+  }
+  return [...searches.values()];
+}
+
+/**
+ * The turn's web searches and fetches per model, `[{ model, searchRequests,
+ * fetchRequests }]`, from the result's `serverToolUse` (the normalizer's
+ * per-turn count, not a running total): the message stream's, which leaves
+ * out the WebSearch tool's own request. Same `modelKey` and summing as the
+ * token totals; models with no requests are left out.
+ */
+export function claudeToolRequests(serverToolUse, { modelKey = (value) => String(value ?? '').trim() } = {}) {
+  const requests = new Map();
+  for (const entry of Array.isArray(serverToolUse) ? serverToolUse : []) {
+    const key = String(modelKey(entry?.model) ?? '').trim().toLowerCase();
+    if (!key || !entry || typeof entry !== 'object') continue;
+    const current = requests.get(key) || { model: key, searchRequests: 0, fetchRequests: 0 };
+    current.searchRequests += count(entry.webSearchRequests);
+    current.fetchRequests += count(entry.webFetchRequests);
+    requests.set(key, current);
+  }
+  return [...requests.values()].filter((entry) => entry.searchRequests + entry.fetchRequests > 0);
+}
+
+function costOf(value) {
+  const number = Number(value ?? 0);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+/**
+ * The CLI's totals per model with Claude Code's own cost estimate, for the
+ * Claude API booking (claude-api-usage-service.mjs): `[{ model, hitTokens,
+ * missTokens, outputTokens, costUsd, costUnknown }]`. From `modelUsage` (the
+ * session's running totals, sub-agents and helper calls included; `costUSD`
+ * per model, `costBasis: 'unknown'` for a model the CLI has no price for), or
+ * from `usage` alone under the turn's model (pass `modelUsage` as null): the
+ * turn's main agent loop, which carries no cost. Model ids keep Claude's
+ * `[1m]` tier; the relay books them under the base id.
+ */
+export function claudeBillingTotals(modelUsage, { usage = null, model = '' } = {}) {
+  const totals = new Map();
+  const add = (name, hit, miss, output, costUsd, costUnknown) => {
+    const key = String(name ?? '').trim().toLowerCase();
+    if (!key) return;
+    const current = totals.get(key) || { model: key, hitTokens: 0, missTokens: 0, outputTokens: 0, costUsd: 0, costUnknown: false };
+    current.hitTokens += hit;
+    current.missTokens += miss;
+    current.outputTokens += output;
+    current.costUsd += costUsd;
+    current.costUnknown = current.costUnknown || costUnknown;
+    totals.set(key, current);
+  };
+  if (modelUsage && typeof modelUsage === 'object' && !Array.isArray(modelUsage)) {
+    for (const [name, entry] of Object.entries(modelUsage)) {
+      if (!entry || typeof entry !== 'object') continue;
+      add(
+        name,
+        count(entry.cacheReadInputTokens),
+        count(entry.inputTokens) + count(entry.cacheCreationInputTokens),
+        count(entry.outputTokens),
+        costOf(entry.costUSD),
+        entry.costBasis === 'unknown',
+      );
+    }
+  } else if (usage && typeof usage === 'object') {
+    add(
+      model,
+      count(usage.cache_read_input_tokens),
+      count(usage.input_tokens) + count(usage.cache_creation_input_tokens),
+      count(usage.output_tokens),
+      0,
+      false,
+    );
+  }
+  return [...totals.values()].filter((entry) => entry.hitTokens + entry.missTokens + entry.outputTokens > 0 || entry.costUsd > 0);
+}