@oar-sh/oar 0.9.15 → 0.9.17

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 { claudeSearchTotals, claudeToolRequests, claudeUsageTotals } from './claude-usage-totals.mjs';
 
 const PLAN_BOARD_ACTIONS = [
   { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
@@ -61,7 +67,53 @@ 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.
+  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,
+} = {}) {
+  /** `{ 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) {
+    if (typeof describeFailure !== 'function') return null;
+    const described = describeFailure(errorText, { status });
+    return described?.code ? described : null;
+  }
+
   function drainWorkflowRuns({ terminal = false } = {}) {
     if (terminal || typeof takeWorkflowRuns !== 'function') return null;
     return takeWorkflowRuns();
@@ -150,11 +202,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 +222,12 @@ 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 (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 +244,179 @@ 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));
+    });
+  }
+
   /**
    * 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 +586,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 +616,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 +635,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 +661,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 +670,33 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
       });
       return;
     }
-    const isAuthError = /authentication|logged in|login|credential|api key/i.test(errorText);
+    const described = backendFailure(errorText);
+    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,108 @@
+// 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);
+}

package/server/claude-worker/sdk-message-normalizer.mjs

@@ -198,6 +198,57 @@ export function createSdkMessageNormalizer() {
   // The `error` of the turn's last main-thread assistant message: the SDK's
   // name for the failure a refused turn ended on.
   let lastAssistantError = '';
+  // The turn's web searches and fetches, per API message id: the API counts
+  // them in each message's `usage.server_tool_use`, and the SDK repeats a
+  // message's usage with every content block it delivers, so a message is
+  // counted once. Summed per model on the result; DeepSeek bills them per
+  // request (shared/deepseek-pricing.mjs).
+  const serverToolUse = new Map(); // message id -> { model, webSearchRequests, webFetchRequests }
+  let unnamedServerToolUseMessages = 0;
+
+  function requestCount(value) {
+    const number = Number(value ?? 0);
+    return Number.isFinite(number) && number > 0 ? Math.round(number) : 0;
+  }
+
+  function noteServerToolUse(messageId, message) {
+    const use = message?.usage?.server_tool_use;
+    if (!use || typeof use !== 'object') return;
+    const webSearchRequests = requestCount(use.web_search_requests);
+    const webFetchRequests = requestCount(use.web_fetch_requests);
+    if (!webSearchRequests && !webFetchRequests) return;
+    const key = messageId || `unnamed-${++unnamedServerToolUseMessages}`;
+    const current = serverToolUse.get(key)
+      || { model: String(message?.model || '').trim() || initModel, webSearchRequests: 0, webFetchRequests: 0 };
+    // A message's usage is the message's total, so repeats do not add up.
+    current.webSearchRequests = Math.max(current.webSearchRequests, webSearchRequests);
+    current.webFetchRequests = Math.max(current.webFetchRequests, webFetchRequests);
+    serverToolUse.set(key, current);
+  }
+
+  /** The turn's `[{ model, webSearchRequests, webFetchRequests }]`, and the count starts over. */
+  function takeServerToolUse(resultUsage) {
+    const byModel = new Map();
+    const add = (model, webSearchRequests, webFetchRequests) => {
+      const key = String(model || '').trim() || initModel;
+      const current = byModel.get(key) || { model: key, webSearchRequests: 0, webFetchRequests: 0 };
+      current.webSearchRequests += webSearchRequests;
+      current.webFetchRequests += webFetchRequests;
+      byModel.set(key, current);
+    };
+    for (const entry of serverToolUse.values()) add(entry.model, entry.webSearchRequests, entry.webFetchRequests);
+    serverToolUse.clear();
+    unnamedServerToolUseMessages = 0;
+    // A result without assistant messages seen still carries the turn's
+    // counts in its own usage, under the turn's model.
+    const use = resultUsage?.server_tool_use;
+    if (!byModel.size && use && typeof use === 'object') {
+      const webSearchRequests = requestCount(use.web_search_requests);
+      const webFetchRequests = requestCount(use.web_fetch_requests);
+      if (webSearchRequests || webFetchRequests) add(initModel, webSearchRequests, webFetchRequests);
+    }
+    return [...byModel.values()];
+  }
 
   function threadKeyFor(parentToolUseId) {
     return String(parentToolUseId || '').trim() || 'main';
@@ -592,6 +643,7 @@ export function createSdkMessageNormalizer() {
       const content = Array.isArray(sdkMessage?.message?.content) ? sdkMessage.message.content : [];
       const messageId = String(sdkMessage?.message?.id || '').trim();
       if (!parentToolUseId) lastAssistantError = String(sdkMessage?.error || '').trim();
+      noteServerToolUse(messageId, sdkMessage?.message);
       return actionsForAssistantMessage(content, parentToolUseId, messageId);
     }
 
@@ -683,6 +735,9 @@ export function createSdkMessageNormalizer() {
           totalCostUsd: Number.isFinite(Number(sdkMessage.total_cost_usd))
             ? Number(sdkMessage.total_cost_usd)
             : null,
+          // This turn's web searches and fetches per model (not running
+          // totals): `[{ model, webSearchRequests, webFetchRequests }]`.
+          serverToolUse: takeServerToolUse(sdkMessage.usage),
         },
       }];
     }

package/server/copilot-worker/copilot-sdk-adapter.mjs

@@ -392,8 +392,11 @@ export function isCopilotQuotaError(data) {
  * "Open Check Usage" pointer shipped in 37d2899. The structured quota verdict
  * is passed to that classifier as a hint rather than smuggled in as forged
  * prose, so a quota error is non-retryable however GitHub worded it.
+ *
+ * `provider` is the worker's provider (`openai` for a BYOK worker): the note
+ * names it, so an OpenAI turn does not read as a Copilot one.
  */
-export function classifyCopilotSessionError(data) {
+export function classifyCopilotSessionError(data, { provider = '' } = {}) {
   const detail = String(data?.message || '').trim() || 'the Copilot runtime reported a session error';
   const quota = isCopilotQuotaError(data);
   const probe = new Error(detail);
@@ -420,7 +423,7 @@ export function classifyCopilotSessionError(data) {
   return {
     code,
     stableCode: `copilot.${code}`,
-    text: `System note: the Copilot turn failed (${detail}). Retry or send a new message.`,
+    text: turnFailedText(detail, provider),
     // Without one the relay adds its default, which advises a retry.
     guidance: COPILOT_TURN_FAILURE_GUIDANCE,
     detail,
@@ -490,6 +493,17 @@ export function isCopilotAuthError(error) {
   return AUTH_ERROR_RE.test(String(error?.message || error || ''));
 }
 
+/**
+ * The generic failure note. On the SDK engine the provider is GitHub Copilot or,
+ * for a BYOK worker, OpenAI; the note names the one the turn ran on.
+ */
+function turnFailedText(detail, provider) {
+  const subject = String(provider || '').trim().toLowerCase() === 'openai'
+    ? 'the OpenAI turn on the Copilot SDK engine'
+    : 'the Copilot turn';
+  return `System note: ${subject} failed (${detail}). Retry or send a new message.`;
+}
+
 /**
  * What the relay appends to a failed Copilot turn in place of its own default
  * (which advises a retry). The worker deals with its runtime itself: a delivered
@@ -509,7 +523,7 @@ export const COPILOT_TURN_CONTINUE_GUIDANCE =
  * than a `session.error` event. Auth gets its own branch because the fix is a
  * user action on the relay host, not a retry.
  */
-export function classifyCopilotTurnException(error) {
+export function classifyCopilotTurnException(error, { provider = '' } = {}) {
   const detail = String(error?.message || error || '').trim() || 'unknown error';
   // The conversation's folder is gone; the message names it.
   if (isWorkingDirectoryMissingError(error)) {
@@ -563,7 +577,7 @@ export function classifyCopilotTurnException(error) {
   return {
     code: 'turn-error',
     stableCode: 'copilot.turn-error',
-    text: `System note: the Copilot turn failed (${detail}). Retry or send a new message.`,
+    text: turnFailedText(detail, provider),
     guidance: COPILOT_TURN_FAILURE_GUIDANCE,
     detail,
   };