@oar-sh/oar 0.9.19 → 0.9.20

package/shared/plan-board-actions.mjs

@@ -0,0 +1,130 @@
+/**
+ * The buttons of a `plan_ready` card, one list for every provider: the Claude,
+ * Copilot, Cursor and Grok workers post it, the CLI extension adds
+ * "Approve plan" to the Copilot CLI's own list, and the relay's action route
+ * builds the follow-up message from the same table.
+ *
+ * - `approve_only` marks the plan approved. Its follow-up runs one turn in
+ *   agent mode (plan mode blocks writes, and the plan doc still has to be
+ *   committed); the session's saved mode stays plan.
+ * - `autopilot` / `autopilot_fleet` and `interactive` leave plan mode: the
+ *   session goes on in the mode the follow-up runs in.
+ * - `exit_only` only settles the card.
+ *
+ * No follow-up carries the plan: the session wrote it, and repeating it read
+ * as a new instruction to carry it out.
+ */
+
+export const PLAN_BOARD_APPROVE_ONLY = 'approve_only';
+
+export const PLAN_BOARD_ACTIONS = Object.freeze([
+  Object.freeze({ id: 'approve_only', label: 'Approve plan', mode: 'agent' }),
+  Object.freeze({ id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' }),
+  Object.freeze({ id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' }),
+  Object.freeze({ id: 'exit_only', label: 'Stop here', mode: 'agent' }),
+]);
+
+/** The actions that take the session out of plan mode for good. */
+export const PLAN_BOARD_LEAVES_PLAN = Object.freeze(['autopilot', 'autopilot_fleet', 'interactive']);
+
+export const PLAN_BOARD_LABELS = Object.freeze({
+  approve_only: 'Approve plan',
+  autopilot: 'Implement in autopilot',
+  autopilot_fleet: 'Implement with autopilot fleet',
+  interactive: 'Stop here and prompt myself',
+  exit_only: 'Stop here',
+});
+
+const FOLLOWUP_TEXTS = Object.freeze({
+  approve_only: 'Plan approved by the user. Do not implement. Finish only the plan-only steps you were given, then stop.',
+  autopilot: 'Please implement the approved plan now.',
+  autopilot_fleet: 'Please implement the approved plan using autopilot_fleet where useful.',
+  interactive: 'I approved the plan. Let\'s proceed interactively with implementation.',
+});
+
+const FOLLOWUP_MODES = Object.freeze({
+  approve_only: 'agent',
+  autopilot: 'autopilot',
+  autopilot_fleet: 'autopilot',
+  interactive: 'agent',
+});
+
+function actionId(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+/** Whether `id` is one of the actions this table knows. */
+export function isKnownPlanBoardAction(id) {
+  return Object.prototype.hasOwnProperty.call(PLAN_BOARD_LABELS, actionId(id));
+}
+
+/** The button's label; an id the table does not know is spelled out. */
+export function planBoardActionLabel(id) {
+  const key = actionId(id);
+  if (Object.prototype.hasOwnProperty.call(PLAN_BOARD_LABELS, key)) return PLAN_BOARD_LABELS[key];
+  return key.replace(/[_-]+/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase()) || 'Select';
+}
+
+/** The message the action queues, or '' when it queues none. */
+export function planBoardFollowupText(id) {
+  const key = actionId(id);
+  return Object.prototype.hasOwnProperty.call(FOLLOWUP_TEXTS, key) ? FOLLOWUP_TEXTS[key] : '';
+}
+
+/** The relay mode the follow-up runs in, or null for an action without one. */
+export function planBoardFollowupMode(id) {
+  const key = actionId(id);
+  return Object.prototype.hasOwnProperty.call(FOLLOWUP_MODES, key) ? FOLLOWUP_MODES[key] : null;
+}
+
+/**
+ * `actions` with "Approve plan" first when it is missing. The others keep
+ * their order and their entries (a CLI's own list, a card stored before the
+ * button existed). Entries may be ids or `{ id }` objects.
+ */
+export function withApproveOnly(actions) {
+  const list = Array.isArray(actions) ? actions : [];
+  const has = list.some((entry) => actionId(typeof entry === 'string' ? entry : entry?.id) === PLAN_BOARD_APPROVE_ONLY);
+  if (has) return list.slice();
+  return [{ ...PLAN_BOARD_ACTIONS[0] }, ...list];
+}
+
+/** Whether a card is a pending plan card, the one kind "Approve plan" is added to. */
+export function isPendingPlanBoard(board) {
+  return String(board?.boardType || '').trim().toLowerCase() === 'plan_ready'
+    && (String(board?.status || 'pending').trim().toLowerCase() || 'pending') === 'pending';
+}
+
+/**
+ * The actions a card shows: a pending plan card gets "Approve plan" even when
+ * it was stored before the button existed. A settled card shows what it was
+ * stored with.
+ */
+export function planBoardShownActions(board, actions = board?.actions) {
+  return isPendingPlanBoard(board) ? withApproveOnly(actions) : (Array.isArray(actions) ? actions : []);
+}
+
+/**
+ * The card's actions from the Copilot CLI's own `exit_plan_mode` arguments
+ * (ids or `{ id | actionId | value }` entries), in the CLI's order, each id
+ * once, with "Approve plan" added. Without any, the shared list. An id the
+ * table does not know keeps no mode: pressing it only settles the card.
+ */
+export function planBoardActionsFromCli(rawActions) {
+  const ids = Array.isArray(rawActions)
+    ? rawActions
+      .map((entry) => {
+        if (typeof entry === 'string') return actionId(entry);
+        if (entry && typeof entry === 'object') return actionId(entry.id || entry.actionId || entry.value);
+        return '';
+      })
+      .filter(Boolean)
+    : [];
+  if (!ids.length) return PLAN_BOARD_ACTIONS.map((entry) => ({ ...entry }));
+  const unique = [...new Set(ids)];
+  return withApproveOnly(unique.map((id) => ({
+    id,
+    label: planBoardActionLabel(id),
+    mode: id === 'exit_only' ? 'agent' : planBoardFollowupMode(id),
+  })));
+}

package/shared/plan-only.mjs

@@ -0,0 +1,43 @@
+/**
+ * Plan-only sessions: a conversation flagged `plan_only` stays in
+ * plan mode as far as agents go. A relay_tool send or update_session that
+ * names another mode is refused with 409 and this code; the owner's own
+ * controls still change the mode, and clearing the flag frees the session.
+ * The lock protects against mistakes, not against an agent that clears it.
+ */
+
+import { planBoardFollowupMode, planBoardFollowupText } from './plan-board-actions.mjs';
+
+export const PLAN_ONLY_ERROR_CODE = 'plan_only';
+
+export const PLAN_ONLY_REFUSAL_TEXT = 'This session is plan-only; agents can\'t change its mode. Clear planOnly first, or ask the user.';
+
+export const PLAN_ONLY_REFUSAL = Object.freeze({ ok: false, code: PLAN_ONLY_ERROR_CODE, error: PLAN_ONLY_REFUSAL_TEXT });
+
+/**
+ * Whether naming `mode` is refused on a plan-only session: any mode but plan,
+ * one the relay does not know included (it must not fall back to a writing
+ * mode). No mode named refuses nothing.
+ */
+export function planOnlyRefusesMode(mode) {
+  const text = String(mode ?? '').trim().toLowerCase();
+  return !!text && text !== 'plan';
+}
+
+/**
+ * The mode a turn cut off (a usage limit, a relay restart) goes on in. As it
+ * ran, except on a plan-only session: there only the "Approve plan" turn
+ * finishes in the agent mode it ran in (the same single turn); any other
+ * goes on in plan. The session's saved mode is not touched either way.
+ * The board does not store the message it queued, so that turn is known by
+ * both its exact line and its agent mode; anything else goes on in plan.
+ */
+export function resumeRelayMode({ relayMode = '', text = '', planOnly = false } = {}) {
+  const stored = String(relayMode || '').trim().toLowerCase();
+  const mode = stored || 'agent';
+  if (!planOnly || mode === 'plan') return mode;
+  // The mode as stored: the board stores agent, never an empty one.
+  const approveTurn = stored === planBoardFollowupMode('approve_only')
+    && String(text || '').trim() === planBoardFollowupText('approve_only');
+  return approveTurn ? mode : 'plan';
+}

package/shared/relay-asks.mjs

@@ -35,6 +35,9 @@ export const RELAY_ASK_CLOSED_STATUSES = Object.freeze(['answered', 'dismissed']
 // Socket event the relay sends on every change of an ask (`{ ask }`) and
 // of the Inbox's count (`{ pending }`).
 export const RELAY_ASK_SOCKET_EVENT = 'relay_ask_updated';
+// Socket event (no payload) the relay sends when the pending items of its
+// paired relays' Inboxes changed (remote-inbox-watch-service.mjs).
+export const INBOX_REMOTE_CHANGED_EVENT = 'inbox_remote_changed';
 
 export const RELAY_ASK_LIMITS = Object.freeze({
   questionMax: 500,

package/shared/relay-events.mjs

@@ -33,6 +33,9 @@ export const RELAY_EVENT_TYPES = Object.freeze([
   'task_failed',
   'stalled',
   'all_idle',
+  // The user settled a plan card (board) of the session: its action, and the
+  // message it queued (none for exit_only).
+  'board_settled',
 ]);
 
 // Not one a subscription names in `events`: `heartbeat_minutes` turns it on.
@@ -97,6 +100,26 @@ export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze([
   'all_idle',
 ]);
 
+// The default from subagent_finished until board_settled (0.9.19): a
+// subscription made without events then stored exactly this list, and takes
+// today's default as well. Unlike the older one, a watcher who names exactly
+// this list now gets it read as the default too (board_settled added): there
+// is no type to add beside it that changes nothing.
+export const RELAY_EVENT_PRE_BOARD_DEFAULT_TYPES = Object.freeze([
+  'question_asked',
+  'error',
+  'turn_end',
+  'subagent_finished',
+  'task_failed',
+  'stalled',
+  'all_idle',
+]);
+
+function sameTypeSet(types, reference) {
+  const unique = new Set((Array.isArray(types) ? types : []).map(toText).filter(Boolean));
+  return unique.size === reference.length && reference.every((type) => unique.has(type));
+}
+
 /**
  * The events a stored subscription takes. A list that is exactly the old
  * default (any order, no more, no less) was the default, not a choice, and
@@ -106,14 +129,14 @@ export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze([
  */
 export function effectiveRelayEventTypes(types) {
   const list = Array.isArray(types) ? types.map(toText).filter(Boolean) : [];
-  return isLegacyDefaultRelayEventTypes(list) ? [...RELAY_EVENT_DEFAULT_TYPES] : list;
+  return isLegacyDefaultRelayEventTypes(list) || sameTypeSet(list, RELAY_EVENT_PRE_BOARD_DEFAULT_TYPES)
+    ? [...RELAY_EVENT_DEFAULT_TYPES]
+    : list;
 }
 
 /** Whether a list is exactly the old default as a set (any order, repeats ignored). */
 export function isLegacyDefaultRelayEventTypes(types) {
-  const unique = new Set((Array.isArray(types) ? types : []).map(toText).filter(Boolean));
-  return unique.size === RELAY_EVENT_LEGACY_DEFAULT_TYPES.length
-    && RELAY_EVENT_LEGACY_DEFAULT_TYPES.every((type) => unique.has(type));
+  return sameTypeSet(types, RELAY_EVENT_LEGACY_DEFAULT_TYPES);
 }
 
 /**
@@ -403,6 +426,9 @@ export function relayEventMatchText(event) {
   if (event?.type === 'task_finished' || event?.type === 'task_failed') {
     return [detail.description, detail.summary].map(toText).filter(Boolean).join('\n');
   }
+  if (event?.type === 'board_settled') {
+    return [detail.action, detail.actionLabel, detail.title].map(toText).filter(Boolean).join('\n');
+  }
   return null;
 }
 
@@ -576,6 +602,14 @@ export function formatRelayEventLine(event) {
       const what = oneLine(detail.what, 80) || 'work';
       return `${head}: no activity for ${Number.isFinite(minutes) ? minutes : '?'} min while ${what} is still running`;
     }
+    case 'board_settled': {
+      const action = oneLine(detail.action, 80);
+      const label = oneLine(detail.actionLabel, 120) || action || 'settled';
+      const ids = [action ? `action ${action}` : '', oneLine(detail.boardId, 80) ? `board_id ${oneLine(detail.boardId, 80)}` : ''].filter(Boolean);
+      // exit_only queues nothing: the session stops there.
+      ids.push(oneLine(detail.queuedMessageId, 80) ? `queued message ${oneLine(detail.queuedMessageId, 80)}` : 'nothing queued');
+      return `${head} ${quote(detail.title || 'plan card', 200)} → ${quote(label, 120)} (${ids.join(', ')})`;
+    }
     default:
       return head;
   }

package/shared/remote-relay-contract.mjs

@@ -153,6 +153,9 @@ export const REMOTE_RELAY_SESSION_SETTINGS = Object.freeze([
   'thinking_display',
   // The working directory: the session's CLI restarts there.
   'cwd',
+  // Plan-only: agents may set and clear it; set, a send or an
+  // update_session naming another mode is refused.
+  'planOnly',
 ]);
 export const REMOTE_RELAY_THINKING_DISPLAYS = THINKING_DISPLAY_MODES;
 // update_session's `group` value that takes a session out of its group (JSON
@@ -333,13 +336,17 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'show the group. Agents can name an existing group when they create a session (group: an id '
   + 'or name relay_info lists, on this relay or a paired one). update_session {session, ...} sets '
   + 'another session\'s model, effort, mode, auto_compact_window, title, group (an id or name; a name '
-  + 'not there yet makes a new group; "none" takes the session out), thinking and cwd (its CLI restarts '
-  + 'there; not while it works) for its next turns without prompting it, and answers the settings and '
+  + 'not there yet makes a new group; "none" takes the session out), thinking, cwd (its CLI restarts '
+  + 'there; not while it works) and planOnly for its next turns without prompting it, and answers the settings and '
   + 'what changed. A session this conversation started may be changed freely; any other (the owner\'s, '
   + 'another agent\'s, the one that started you) needs the owner\'s Allow once per conversation and relay; '
   + 'your own conversation never. A group the owner made is never removed that way (it may stay empty). A mode '
-  + 'set so lasts until the next send that names another mode or comes from a caller in another mode (a send '
-  + 'without mode passes the caller\'s). Renaming and dissolving groups stay the owner\'s. An argument an action does not '
+  + 'set so stays the session\'s own: a send without mode runs in it, and a send that names a mode runs that '
+  + 'turn alone in it. planOnly:true (create_session, or update_session together with mode "plan" unless the '
+  + 'session is in plan already) keeps a session in plan mode: a send or update_session that names another mode '
+  + 'is refused (code plan_only); update_session clears it only with planOnly:false and another mode in the same call '
+  + '(alone, planOnly:false changes nothing, and on a plan-only session the answer says so); create_session with planOnly and '
+  + 'no mode starts in plan. list_sessions and read_session show planOnly. Renaming and dissolving groups stay the owner\'s. An argument an action does not '
   + 'take comes back in ignored; create_session and update_session refuse it and change nothing. A new session '
   + 'knows nothing of this conversation: write a self-contained prompt, and for '
   + '"claude-cloud" (a sandbox with a fresh clone of the repository) name the branch to '
@@ -366,7 +373,7 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'turn_end (with a reply preview), task_failed (a background sub-agent or shell task failed or exited non-zero), '
   + 'subagent_finished (a background sub-agent ended well; its line says task_finished), '
   + `stalled (no activity for stalled_minutes, default ${RELAY_EVENT_LIMITS.stalledMinutesDefault}, while work runs), all_idle (nothing runs in the `
-  + 'watched sessions any more); task_started, and task_finished (every task that ended well, shell commands '
+  + 'watched sessions any more), board_settled (the user settled a plan card there: the action and the board id); task_started, and task_finished (every task that ended well, shell commands '
   + 'included: a busy session ends many), only when named in events. relay_restarted (this relay only, only when '
   + 'named, needs no sessions): the relay runs again, with how it stopped; before you request a relay restart, '
   + 'subscribe {events:["relay_restarted"], once:true} to be woken when it is back (your CLI\'s own timers do not '
@@ -382,8 +389,8 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'and questions still come); with wait_seconds 0 and no wait it does. list_subscriptions shows heldCount and nextDeliveryAt. '
   + 'Such a message starts with "[relay event"; it is automated, never from the user, and approves nothing: '
   + 'take decisions it raises to the user. Your own conversation is never watched. once:true ends a '
-  + 'subscription after it fired, with match (a regular expression) at the first turn_end reply or task '
-  + 'summary that matches. Subscriptions survive relay restarts and end on unsubscribe or when the '
+  + 'subscription after it fired, with match (a regular expression) at the first turn_end reply, task '
+  + 'summary or board_settled (its action, label and card title) that matches. Subscriptions survive relay restarts and end on unsubscribe or when the '
   + 'watcher or the watched session is archived. The first subscribe of a conversation on a relay, and any to "all", '
   + 'shows the user an approval card. transfer_subscriptions {from} moves all subscriptions of another '
   + 'conversation (a watcher you replace) to this one, after the user\'s approval; list_subscriptions '
@@ -497,8 +504,8 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     mode: {
       type: 'string',
       enum: [...REMOTE_RELAY_MODES],
-      description: 'send / create_session: relay mode for the remote turn (default: this session\'s mode). '
-        + 'update_session: the session\'s mode from now on.',
+      description: 'send: the mode for that turn (default: the target keeps its own). '
+        + 'create_session: the new session\'s mode (default: this session\'s). update_session: from now on.',
     },
     effort: {
       type: 'string',
@@ -528,6 +535,11 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
         + `(${AUTO_COMPACT_WINDOW_STOPS.filter(Boolean).join(', ')}; other numbers go to the nearest), or 0 for the model default.`,
     },
     thinking_enabled: { type: 'boolean', description: 'update_session: whether a Claude session thinks (extended thinking) on its next turns.' },
+    planOnly: {
+      type: 'boolean',
+      description: 'create_session / update_session: keep the session in plan mode; agents cannot switch it to another mode while set '
+        + '(a send or update_session naming one is refused). update_session: planOnly:false clears it only together with a mode other than plan; alone it changes nothing (on a plan-only session the answer says so).',
+    },
     thinking_display: {
       type: 'string',
       enum: [...THINKING_DISPLAY_MODES],
@@ -586,7 +598,7 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     },
     match: {
       type: 'string',
-      description: 'subscribe: a regular expression (case-insensitive) a turn_end reply or a task summary must match; other events pass.',
+      description: 'subscribe: a regular expression (case-insensitive) a turn_end reply, a task summary or a board_settled (its action, label and card title) must match; other events pass.',
     },
     stalled_minutes: {
       type: 'integer',
@@ -685,7 +697,7 @@ export const REMOTE_RELAY_ACTION_ARGUMENTS = Object.freeze({
   read_task_output: Object.freeze(['session', 'task_id', 'lines']),
   wait: Object.freeze(['session', 'message_id', 'wait_seconds']),
   send: Object.freeze(['session', 'text', 'wait_seconds', 'model', 'mode', 'effort', 'if_busy', 'provider']),
-  create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds']),
+  create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds', 'planOnly']),
   update_session: Object.freeze(['session', ...REMOTE_RELAY_SESSION_SETTINGS]),
   answer_question: Object.freeze(['question_id', 'answer', 'choices']),
   stop: Object.freeze(['session']),
@@ -942,6 +954,13 @@ function validateToolInput(input, { maxWaitSeconds, now, providers, sendProvider
         if (!isValidBranchName(branchText)) return invalid(`branch "${branchText.slice(0, 80)}" is not a valid branch name`);
         args.branch = branchText;
       }
+      // Plan-only: kept in plan mode; false (or left out) is no lock.
+      const planOnly = input?.planOnly;
+      if (planOnly !== undefined && planOnly !== null && toText(planOnly) !== '') {
+        const flag = readBoolean(planOnly);
+        if (flag === null) return invalid('planOnly must be true or false');
+        if (flag) args.planOnly = true;
+      }
     }
   } else if (action === 'update_session') {
     const settings = validateRemoteRelaySessionSettings(input);
@@ -1030,6 +1049,12 @@ export function validateRemoteRelaySessionSettings(input) {
     if (enabled === null) return invalid('thinking_enabled must be true or false');
     values.thinking_enabled = enabled;
   }
+  const planOnly = input?.planOnly;
+  if (planOnly !== undefined && planOnly !== null && toText(planOnly) !== '') {
+    const flag = readBoolean(planOnly);
+    if (flag === null) return invalid('planOnly must be true or false');
+    values.planOnly = flag;
+  }
   const display = toText(input?.thinking_display).toLowerCase();
   if (display) {
     if (!THINKING_DISPLAY_MODES.includes(display)) return invalid(`thinking_display must be one of: ${THINKING_DISPLAY_MODES.join(', ')}`);
@@ -1267,6 +1292,36 @@ export function formatSessionGroupList(groups, max = REMOTE_RELAY_GROUP_LIMITS.r
 // a dispatcher never offers one to its agent. Defined in relay-asks.mjs.
 export { REMOTE_RELAY_APPROVAL_SOURCE };
 
+// What an approval card is about: its context carries one of these
+// as `variant`, and a `summary` of at most this many characters (kind,
+// requesting session, reason; never the prompt, answer or question text). A
+// paired relay's Inbox shows them in place of the card text it never gets.
+export const REMOTE_RELAY_APPROVAL_VARIANTS = Object.freeze([
+  'create_session', 'loop_guard', 'write', 'session_settings', 'watch', 'local_sessions',
+]);
+export const REMOTE_RELAY_APPROVAL_SUMMARY_MAX = 160;
+// Each variant's kind label, without titles: the Inbox row's head, and the
+// push body of a device whose preview preference is off.
+export const REMOTE_RELAY_APPROVAL_VARIANT_LABELS = Object.freeze({
+  create_session: 'New session',
+  loop_guard: 'Loop guard',
+  write: 'Write',
+  session_settings: 'Session settings',
+  watch: 'Watch',
+  local_sessions: 'Start sessions',
+});
+
+// Who pushes a card a turn waits on (an approval, a blocking ask_user) when a
+// paired relay that can push reads this relay's Inbox (`?push=1`): `notice`
+// on each such pending item. `here`: this relay's own push reached a device;
+// `wait`: its push is not settled yet; `you`: the caller holds the claim and
+// pushes; `other`: another paired relay holds it. With `you`, `claimed` says
+// whether this request recorded the claim (`now`, the caller pushes) or the
+// caller held it already (`before`, e.g. after the caller restarted: no
+// second push).
+export const REMOTE_INBOX_NOTICES = Object.freeze({ here: 'here', wait: 'wait', you: 'you', other: 'other' });
+export const REMOTE_INBOX_CLAIMS = Object.freeze({ now: 'now', before: 'before' });
+
 /** True for such a card: a formatted question, or a stored request envelope (both carry `context`). */
 export function isRemoteRelayApprovalQuestion(question) {
   const context = question && typeof question === 'object' ? question.context : null;

package/shared/turn-token-usage.mjs

@@ -0,0 +1,144 @@
+import { claudeBaseModelId } from './model-id.mjs';
+
+// The token report a worker posts after a turn (POST /api/turn-token-usage),
+// checked and normalised. Shared by the relay (the route and
+// services/token-usage-service.mjs) and the workers that build it.
+//
+// A token field a provider did not report is null; a negative, non-finite
+// or unsafely large one is not a count either and becomes null, and a
+// fraction is cut to the integer. 0 always means the provider reported zero. `inputTokens` is fresh
+// input: without the tokens read from or written to the prompt cache.
+
+export const TURN_TOKEN_FIELDS = Object.freeze([
+  'inputTokens',
+  'outputTokens',
+  'cacheWriteTokens',
+  'cacheReadTokens',
+  'reasoningTokens',
+]);
+
+export const TURN_TOKEN_COST_SOURCES = Object.freeze(['claude-code', 'provider', 'oar-deepseek-table']);
+
+export const TURN_TOKEN_PROVIDERS = Object.freeze(['github', 'claude', 'claude-api', 'claude-cloud', 'deepseek', 'cursor', 'grok']);
+
+// One report names at most this many models; more is not a turn.
+export const TURN_TOKEN_MAX_MODELS = 32;
+const ID_MAX_LENGTH = 200;
+const BILLING_PATTERN = /^byok-[a-z0-9][a-z0-9_-]{0,39}$/;
+
+/** A provider's model id as the tables keep it: lower case, without `[1m]`. */
+export function tokenUsageModel(value) {
+  return claudeBaseModelId(String(value ?? '').trim()).toLowerCase();
+}
+
+// Past these a value is not a count or a cost but a broken report.
+const MAX_COST_USD = 1e9;
+
+/** A token count, or null when the value is not one. */
+export function tokenCount(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) return null;
+  return Math.trunc(value);
+}
+
+function costValue(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > MAX_COST_USD) return null;
+  return value;
+}
+
+/** a + b where either may be null: null only when both are. */
+export function addNullable(a, b) {
+  if (a == null) return b == null ? null : b;
+  if (b == null) return a;
+  return a + b;
+}
+
+/** '' or `byok-<provider type>`; null for anything else. */
+export function normalizeTurnTokenBilling(value) {
+  const billing = String(value || '').trim().toLowerCase();
+  if (!billing) return '';
+  return BILLING_PATTERN.test(billing) ? billing : null;
+}
+
+/**
+ * `[{ model, inputTokens, …, costUsd, costSource, costUnknown }]`, one per
+ * model: the same model named twice (also `x` and `x[1m]`) is summed.
+ */
+export function normalizeTurnTokenEntries(entries) {
+  const byModel = new Map();
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const model = tokenUsageModel(entry?.model);
+    if (!model || model.length > ID_MAX_LENGTH) continue;
+    const next = {
+      model,
+      ...Object.fromEntries(TURN_TOKEN_FIELDS.map((field) => [field, tokenCount(entry?.[field])])),
+      costUsd: costValue(entry?.costUsd),
+      costSource: TURN_TOKEN_COST_SOURCES.includes(entry?.costSource) ? entry.costSource : null,
+      costUnknown: entry?.costUnknown === true,
+    };
+    const current = byModel.get(model);
+    if (!current) {
+      byModel.set(model, next);
+      continue;
+    }
+    // The caps hold for the sum too, not only for each entry.
+    for (const field of TURN_TOKEN_FIELDS) {
+      const sum = addNullable(current[field], next[field]);
+      current[field] = sum === null ? null : tokenCount(sum);
+    }
+    const costSum = addNullable(current.costUsd, next.costUsd);
+    current.costUsd = costSum === null ? null : costValue(costSum);
+    current.costSource = current.costSource || next.costSource;
+    current.costUnknown = current.costUnknown || next.costUnknown;
+  }
+  return [...byModel.values()];
+}
+
+function idValue(value) {
+  const id = String(value ?? '').trim();
+  return id.length > ID_MAX_LENGTH ? null : id;
+}
+
+/**
+ * The report a worker posts, checked: `{ ok, report }` or `{ ok: false,
+ * error }`. `models` carries the turn's own counts; `sessionTotals` (Claude
+ * cloud) the session's running totals, of which the relay books the growth.
+ * Who the provider and billing are is the relay's to settle; the body's are
+ * only stated.
+ */
+export function normalizeTurnTokenUsageReport(body = {}) {
+  const conversationId = idValue(body?.conversationId);
+  const turnId = idValue(body?.turnId);
+  const runId = idValue(body?.runId);
+  if (!conversationId) return { ok: false, error: 'Missing conversationId' };
+  if (!turnId) return { ok: false, error: 'Missing turnId' };
+  if (runId === null) return { ok: false, error: 'Invalid runId' };
+  const provider = String(body?.provider || '').trim().toLowerCase();
+  if (provider && !TURN_TOKEN_PROVIDERS.includes(provider)) return { ok: false, error: 'Unknown provider' };
+  const billing = normalizeTurnTokenBilling(body?.billing);
+  if (billing === null) return { ok: false, error: 'Invalid billing' };
+  const at = body?.at == null || body?.at === '' ? null : String(body.at).trim();
+  if (at !== null && !Number.isFinite(Date.parse(at))) return { ok: false, error: 'Invalid at' };
+  const hasModels = Array.isArray(body?.models);
+  const hasSessionTotals = Array.isArray(body?.sessionTotals);
+  if (hasModels === hasSessionTotals) return { ok: false, error: 'Send either models or sessionTotals' };
+  const raw = hasModels ? body.models : body.sessionTotals;
+  if (raw.length > TURN_TOKEN_MAX_MODELS) return { ok: false, error: `More than ${TURN_TOKEN_MAX_MODELS} models` };
+  const entries = normalizeTurnTokenEntries(raw);
+  if (!entries.length) return { ok: false, error: 'Missing models' };
+  const nativeSessionId = idValue(body?.nativeSessionId) || null;
+  if (hasSessionTotals && !nativeSessionId) return { ok: false, error: 'Missing nativeSessionId' };
+  return {
+    ok: true,
+    report: {
+      conversationId,
+      turnId,
+      runId,
+      provider,
+      billing,
+      nativeSessionId,
+      responseMessageId: idValue(body?.responseMessageId) || null,
+      at: at === null ? null : new Date(Date.parse(at)).toISOString(),
+      ...(hasModels ? { models: entries } : { sessionTotals: entries }),
+    },
+  };
+}