@oar-sh/oar 0.9.5 → 0.9.7

package/shared/claude-cloud/base-url.mjs

@@ -0,0 +1,47 @@
+// Where the cloud client sends its calls.
+//
+// Always the Anthropic API, with one exception for tests: the environment
+// variable below may point the client at a fake API on the same machine. The
+// client sends the Claude login as a bearer token to whatever its base URL
+// is, so an environment variable must never be able to name another host: a
+// value that is not a plain http(s) URL of the loopback interface is ignored
+// and the default stays. The relay's client and the cloud worker's both ask
+// here, so the rule lives in this one function.
+
+import { CLAUDE_CLOUD_BASE_URL } from './api-client.mjs';
+
+export const CLAUDE_CLOUD_BASE_URL_ENV = 'OAR_CLAUDE_CLOUD_API_BASE_URL';
+
+// Exactly these, as the URL parser writes them (it lower-cases the name and
+// puts the IPv6 address in brackets). No "anything in 127/8", no trailing dot,
+// no name that merely starts or ends like one of them.
+const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', '[::1]', 'localhost']);
+
+/**
+ * The origin of a loopback http(s) URL (`http://127.0.0.1:4010`), or null for
+ * anything else: another host, another scheme, a URL with a user or a
+ * password in it, or text that is no URL at all. A path, query or fragment is
+ * dropped: the client's routes start at the root.
+ */
+export function loopbackBaseUrlOrNull(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) return null;
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (url.username || url.password) return null;
+  if (!LOOPBACK_HOSTNAMES.has(url.hostname)) return null;
+  return url.origin;
+}
+
+/**
+ * The base URL for `createClaudeCloudClient`: the loopback URL named by
+ * `OAR_CLAUDE_CLOUD_API_BASE_URL`, else the Anthropic API.
+ */
+export function resolveClaudeCloudBaseUrl(env = process.env) {
+  return loopbackBaseUrlOrNull(env?.[CLAUDE_CLOUD_BASE_URL_ENV]) || CLAUDE_CLOUD_BASE_URL;
+}

package/shared/claude-cloud/credentials.mjs

@@ -0,0 +1,221 @@
+// The Claude login a cloud session runs on.
+//
+// Claude Cloud sessions are created with the claude.ai login the Claude CLI
+// keeps in `<CLAUDE_CONFIG_DIR | ~/.claude>/.credentials.json`. This module is
+// the only place that reads it. It hands out the access token, says what it
+// found (never the token itself), and takes the token back out of any text
+// that is about to leave the process.
+//
+// What it never does: use the refresh token. A refresh from here would rotate
+// the login under the CLI and log it out. When the token has run out the file
+// is read again (the CLI rewrites it while it works), then the caller's
+// `nudge` may run the CLI once so that it refreshes its own login, and after
+// that the answer is `login_expired`.
+//
+// Nothing here logs, and no error it throws carries the token.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CLAUDE_CLOUD_ERROR_CODES = Object.freeze([
+  'login_missing',
+  'login_expired',
+  'github_not_connected',
+  'repo_access_denied',
+  'environment_missing',
+  'not_found',
+  'rate_limited',
+  'bad_request',
+  'transient',
+]);
+
+const DEFAULT_ERROR_MESSAGES = Object.freeze({
+  login_missing: 'No Claude login was found on this machine. Log in with the Claude CLI first.',
+  login_expired: 'The Claude login has expired or was rejected. Log in to Claude again.',
+  github_not_connected: 'GitHub is not connected to this Claude account.',
+  repo_access_denied: 'The Claude GitHub app has no access to this repository.',
+  environment_missing: 'The Claude Cloud environment was not found.',
+  not_found: 'Claude Cloud did not find the session or resource.',
+  rate_limited: 'Claude Cloud is rate limiting this account. Try again later.',
+  bad_request: 'Claude Cloud refused the request.',
+  transient: 'Claude Cloud is not answering right now.',
+});
+
+/** The plain sentence for an error code; the fallback of every ClaudeCloudError. */
+export function claudeCloudErrorMessage(code) {
+  return DEFAULT_ERROR_MESSAGES[code] || DEFAULT_ERROR_MESSAGES.transient;
+}
+
+/**
+ * Every failure of the cloud client and of the credentials: `code` (one of
+ * CLAUDE_CLOUD_ERROR_CODES), `status` (the HTTP status, or null when no answer
+ * was involved) and `detail` (what the API said, already redacted, or null).
+ *
+ * `new ClaudeCloudError(code, message?, { status, detail })`; also accepted:
+ * `(message, { code, … })` and `({ code, message, … })`.
+ */
+export class ClaudeCloudError extends Error {
+  constructor(code, message, options) {
+    let fields;
+    if (code && typeof code === 'object') fields = code;
+    else if (message && typeof message === 'object') {
+      fields = message.code ? { ...message, message: code } : { ...message, code };
+    } else fields = { ...(options || {}), code, message };
+    const errorCode = String(fields.code || 'transient');
+    super(String(fields.message || '') || claudeCloudErrorMessage(errorCode));
+    this.name = 'ClaudeCloudError';
+    this.code = errorCode;
+    this.status = Number.isFinite(fields.status) ? fields.status : null;
+    this.detail = fields.detail ? String(fields.detail) : null;
+  }
+}
+
+export const CLAUDE_CLOUD_TOKEN_ENV = 'CLAUDE_CODE_OAUTH_TOKEN';
+/** The cached token is trusted until this long before it runs out. */
+export const CLAUDE_CLOUD_TOKEN_MARGIN_MS = 60_000;
+/** The CLI is asked to refresh its login at most this often. */
+export const CLAUDE_CLOUD_NUDGE_INTERVAL_MS = 5 * 60_000;
+
+const REDACTED = '[redacted]';
+/** Tokens handed out earlier stay redactable after the file moved on. */
+const MAX_REMEMBERED_TOKENS = 16;
+
+/** Where the CLI keeps its login: `CLAUDE_CONFIG_DIR`, else `.claude` in the home directory. */
+export function resolveClaudeCredentialsPath({ env = process.env, homedir = os.homedir, pathImpl = path } = {}) {
+  const configDir = String(env?.CLAUDE_CONFIG_DIR || '').trim();
+  if (configDir) return pathImpl.join(configDir, '.credentials.json');
+  const home = String((typeof homedir === 'function' ? homedir() : homedir) || '').trim();
+  return pathImpl.join(home, '.claude', '.credentials.json');
+}
+
+function textOrNull(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  return text || null;
+}
+
+function isoOrNull(ms) {
+  if (ms === null) return null;
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+/**
+ * `nudge`: an async function that makes the Claude CLI refresh its own login
+ * (the caller decides which command). Called at most once per five minutes,
+ * and only when the login in the file is about to run out or has.
+ */
+export function createClaudeCloudCredentials({
+  env = process.env,
+  homedir = os.homedir,
+  fsImpl = fs,
+  now = Date.now,
+  nudge = null,
+  pathImpl = path,
+} = {}) {
+  let cached = null;
+  let loading = null;
+  let lastNudgeAt = null;
+  const remembered = [];
+
+  function remember(token) {
+    if (!token || remembered.includes(token)) return;
+    remembered.push(token);
+    if (remembered.length > MAX_REMEMBERED_TOKENS) remembered.shift();
+  }
+
+  function readEnvToken() {
+    const token = textOrNull(env?.[CLAUDE_CLOUD_TOKEN_ENV]);
+    if (token) remember(token);
+    return token;
+  }
+
+  /** The login in the file, or null when there is no file, no JSON or no token in it. */
+  function readFileLogin() {
+    let oauth = null;
+    try {
+      const filePath = resolveClaudeCredentialsPath({ env, homedir, pathImpl });
+      oauth = JSON.parse(fsImpl.readFileSync(filePath, 'utf8'))?.claudeAiOauth;
+    } catch {
+      return null;
+    }
+    const accessToken = textOrNull(oauth?.accessToken);
+    if (!accessToken) return null;
+    remember(accessToken);
+    const expiresAt = Number(oauth.expiresAt);
+    return {
+      accessToken,
+      expiresAt: Number.isFinite(expiresAt) && expiresAt > 0 ? expiresAt : null,
+      subscriptionType: textOrNull(oauth.subscriptionType),
+      rateLimitTier: textOrNull(oauth.rateLimitTier),
+    };
+  }
+
+  // A login without an expiry time is taken as it is and read again each time.
+  const isExpired = (login) => login.expiresAt !== null && now() >= login.expiresAt;
+  const isFresh = (login) => login.expiresAt !== null && now() < login.expiresAt - CLAUDE_CLOUD_TOKEN_MARGIN_MS;
+  const needsRefresh = (login) => login.expiresAt !== null && !isFresh(login);
+
+  async function loadFromFile() {
+    let login = readFileLogin();
+    if (login && needsRefresh(login) && typeof nudge === 'function'
+      && (lastNudgeAt === null || now() - lastNudgeAt >= CLAUDE_CLOUD_NUDGE_INTERVAL_MS)) {
+      lastNudgeAt = now();
+      // A nudge that fails changes nothing: the file decides.
+      try { await nudge(); } catch {}
+      login = readFileLogin();
+    }
+    cached = null;
+    if (!login) throw new ClaudeCloudError('login_missing');
+    if (isExpired(login)) throw new ClaudeCloudError('login_expired');
+    // Inside the last minute the token still works, so it is handed out, but
+    // `isFresh` keeps it from being served from the cache.
+    cached = login;
+    return login.accessToken;
+  }
+
+  /**
+   * The bearer token. `forceReload` skips the cache (the API refused the
+   * cached token: the CLI may have replaced it early). Throws ClaudeCloudError
+   * `login_missing` or `login_expired`.
+   */
+  async function getAccessToken({ forceReload = false } = {}) {
+    const envToken = readEnvToken();
+    if (envToken) return envToken;
+    if (!forceReload && cached && isFresh(cached)) return cached.accessToken;
+    // One read (and one nudge) for everybody who asks while it runs.
+    if (!loading) loading = loadFromFile().finally(() => { loading = null; });
+    return loading;
+  }
+
+  /** What there is to say about the login without saying the token. Never throws. */
+  function describe() {
+    const none = { source: 'none', hasToken: false, expiresAt: null, subscriptionType: null, rateLimitTier: null, expired: false };
+    if (readEnvToken()) return { ...none, source: 'env', hasToken: true };
+    const login = readFileLogin();
+    if (!login) return none;
+    return {
+      source: 'file',
+      hasToken: true,
+      expiresAt: isoOrNull(login.expiresAt),
+      subscriptionType: login.subscriptionType,
+      rateLimitTier: login.rateLimitTier,
+      expired: isExpired(login),
+    };
+  }
+
+  /**
+   * The text without any token this module has handed out or seen, and
+   * without anything that has the shape of a bearer header or a Claude token.
+   */
+  function redact(text) {
+    let out = String(text ?? '');
+    readEnvToken();
+    for (const token of remembered) out = out.split(token).join(REDACTED);
+    return out
+      .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`)
+      .replace(/\bsk-ant-[A-Za-z0-9_-]{8,}/g, REDACTED);
+  }
+
+  return { getAccessToken, describe, redact };
+}

package/shared/claude-cloud/repo-url.mjs

@@ -0,0 +1,111 @@
+// Repository, branch and model strings for Claude Cloud sessions.
+//
+// A cloud session clones a GitHub repository by its https URL and, when one is
+// named, checks out a branch. Both arrive as free text (the New Chat fields,
+// an `origin` remote read from a folder), so everything is brought to one form
+// here before it is stored or sent: the server validates with these, the
+// browser shows what they return, the client sends it.
+//
+// Pure functions, no I/O.
+
+const GITHUB_HOSTS = new Set(['github.com', 'www.github.com']);
+// GitHub's own rules: an account name is letters, digits and single hyphens
+// (never leading), at most 39 characters; a repository name is letters,
+// digits, `.`, `_` and `-`, at most 100.
+const OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;
+const MAX_BRANCH_LENGTH = 255;
+
+function ownerAndRepoFromPath(pathText) {
+  const parts = String(pathText || '').split('/').filter(Boolean);
+  // Exactly owner/repo: a pasted page URL (…/tree/main, /orgs/<name>/…) would
+  // otherwise be read as some other repository.
+  if (parts.length !== 2) return null;
+  const owner = parts[0];
+  const repo = parts[1].replace(/\.git$/i, '');
+  if (!OWNER_PATTERN.test(owner) || owner.endsWith('-')) return null;
+  if (!REPO_PATTERN.test(repo) || repo === '.' || repo === '..') return null;
+  return { owner, repo };
+}
+
+/**
+ * The canonical https form of a GitHub repository reference, or null when the
+ * text is not one. Accepts `https://github.com/owner/repo` (with `.git`, a
+ * trailing slash, or credentials in front of the host, which are dropped),
+ * `git@github.com:owner/repo.git`, `ssh://git@github.com/owner/repo`,
+ * `git://…` and the scheme-less `github.com/owner/repo`.
+ */
+export function normalizeGitHubRepoUrl(input) {
+  const text = String(input ?? '').trim();
+  if (!text || /\s/.test(text)) return null;
+
+  let host = '';
+  let pathText = '';
+  // scp-like: [user@]host:owner/repo(.git). A scheme is followed by `//`, so
+  // `https://…` and `ssh://…` never match here.
+  const scp = text.match(/^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9.-]+):(?!\/\/)(.+)$/);
+  if (scp) {
+    host = scp[1];
+    pathText = scp[2];
+  } else {
+    const withScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(text) ? text : `https://${text}`;
+    let url;
+    try {
+      url = new URL(withScheme);
+    } catch {
+      return null;
+    }
+    if (!['https:', 'http:', 'ssh:', 'git:', 'git+ssh:'].includes(url.protocol)) return null;
+    host = url.hostname;
+    pathText = url.pathname;
+  }
+
+  if (!GITHUB_HOSTS.has(host.toLowerCase())) return null;
+  const parsed = ownerAndRepoFromPath(pathText);
+  if (!parsed) return null;
+  const slug = `${parsed.owner}/${parsed.repo}`;
+  return { repoUrl: `https://github.com/${slug}`, owner: parsed.owner, repo: parsed.repo, slug };
+}
+
+/**
+ * Whether git would accept the text as a branch name (the rules of
+ * `git check-ref-format --branch`). Nothing is trimmed: a name with a space
+ * around it is not a branch name.
+ */
+export function isValidBranchName(value) {
+  if (typeof value !== 'string') return false;
+  if (!value || value.length > MAX_BRANCH_LENGTH) return false;
+  if (value === '@' || value.startsWith('-')) return false;
+  // Control characters, space, and the characters git reserves for revisions.
+  if (/[\u0000- \u007f~^:?*[\\]/.test(value)) return false;
+  if (value.includes('..') || value.includes('@{') || value.includes('//')) return false;
+  if (value.startsWith('/') || value.endsWith('/') || value.endsWith('.')) return false;
+  return value.split('/').every((part) => !part.startsWith('.') && !part.endsWith('.lock'));
+}
+
+/**
+ * A model id without its tier suffix: "claude-opus-5[1m]" → "claude-opus-5".
+ * The cloud takes plain ids only.
+ */
+export function stripModelTierSuffix(model) {
+  return String(model ?? '').trim().replace(/\s*\[[^\]]*\]$/, '').trim();
+}
+
+function encodeRefForUrl(ref) {
+  return ref.split('/').map((part) => encodeURIComponent(part)).join('/');
+}
+
+/**
+ * Where GitHub shows what a pushed branch changed: the compare page against
+ * `base`, the compare page against the default branch when no base is known,
+ * and the branch itself when it is the base (a compare of a branch with itself
+ * is empty). Null when the slug or the branch is not usable.
+ */
+export function compareUrl(slug, base, branch) {
+  const repo = normalizeGitHubRepoUrl(`https://github.com/${String(slug ?? '').trim()}`);
+  if (!repo || !isValidBranchName(branch)) return null;
+  const head = encodeRefForUrl(branch);
+  if (base === branch) return `${repo.repoUrl}/tree/${head}`;
+  if (!isValidBranchName(base)) return `${repo.repoUrl}/compare/${head}`;
+  return `${repo.repoUrl}/compare/${encodeRefForUrl(base)}...${head}`;
+}

package/shared/claude-usage-limit.mjs

@@ -0,0 +1,257 @@
+// The Claude subscription's usage limit, as the CLI reports it.
+//
+// The CLI sends a `rate_limit_event` at the start of every turn of a
+// claude.ai subscription session. At the limit it refuses the request without
+// waiting or retrying (captured live, CLI 2.1.283 / SDK 0.3.283):
+//
+//   rate_limit_event   { status: 'rejected', rateLimitType: 'five_hour',
+//                        resetsAt: <unix seconds>, unifiedWindows: {...} }
+//   assistant          { model: '<synthetic>', error: 'rate_limit',
+//                        is_api_error_message: true, text: "You've hit your
+//                        session limit · resets 10pm (UTC)" }
+//   result             { is_error: true, subtype: 'success',
+//                        api_error_status: 429, terminal_reason: 'api_error' }
+//
+// Shared by the Claude worker (which sees the stream) and the relay (which
+// pauses the turn and resumes it at the reset).
+
+export const USAGE_LIMIT_CODE = 'usage-limit';
+export const USAGE_LIMIT_STABLE_CODE = `claude.${USAGE_LIMIT_CODE}`;
+export const USAGE_LIMIT_KIND = 'claude-usage-limit';
+
+// A wait up to this long resumes by itself. A longer one (a weekly window can
+// be days away) stays paused until the user resumes it.
+export const USAGE_LIMIT_AUTO_RESUME_MAX_MS = 6 * 60 * 60 * 1000;
+
+// The reset time is the server's; the first request after it must not race
+// the window's own bookkeeping.
+export const USAGE_LIMIT_RESUME_MARGIN_MS = 60 * 1000;
+
+// A rejected report that names no reset still ahead counts for this long
+// after it arrived. Right after a reset the CLI can refuse once more and name
+// the reset that has just passed.
+export const USAGE_LIMIT_REPORT_FRESH_MS = 10 * 60 * 1000;
+
+const STATUSES = new Set(['allowed', 'allowed_warning', 'rejected']);
+
+const WINDOW_LABELS = Object.freeze({
+  five_hour: '5-hour limit',
+  seven_day: 'weekly limit',
+  seven_day_opus: 'weekly Opus limit',
+  seven_day_sonnet: 'weekly Sonnet limit',
+  seven_day_overage_included: 'weekly limit',
+  overage: 'extra usage limit',
+});
+
+const LIMIT_TEXT = /\b(?:hit|reached)\s+your\s+(?:\w+\s+){0,3}limit\b|\busage limit\b/i;
+
+function toFraction(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.min(n, 1);
+}
+
+// Unix seconds (what the CLI sends), milliseconds or an ISO string.
+function toIso(value) {
+  if (value === null || value === undefined || value === '') return null;
+  let ms = NaN;
+  if (typeof value === 'number' || /^\d+(\.\d+)?$/.test(String(value).trim())) {
+    const n = Number(value);
+    ms = n < 1e11 ? n * 1000 : n;
+  } else {
+    ms = Date.parse(String(value));
+  }
+  return Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : null;
+}
+
+function normalizeWindows(raw) {
+  if (!raw || typeof raw !== 'object') return [];
+  return Object.entries(raw)
+    .map(([id, window]) => ({
+      id: String(id),
+      utilization: toFraction(window?.utilization),
+      resetsAt: toIso(window?.resetsAt ?? window?.resets_at),
+    }))
+    .filter((window) => window.utilization !== null || window.resetsAt);
+}
+
+export function usageLimitWindowLabel(rateLimitType) {
+  return WINDOW_LABELS[String(rateLimitType || '').trim()] || 'usage limit';
+}
+
+/**
+ * The `rate_limit_info` of a `rate_limit_event`, in the shape the relay keeps.
+ * Returns null for anything that is not one.
+ */
+export function normalizeRateLimitInfo(raw, { now = Date.now() } = {}) {
+  if (!raw || typeof raw !== 'object') return null;
+  const status = String(raw.status || '').trim();
+  if (!STATUSES.has(status)) return null;
+  const rateLimitType = String(raw.rateLimitType || '').trim() || null;
+  const windows = normalizeWindows(raw.unifiedWindows);
+  const own = windows.find((window) => window.id === rateLimitType) || null;
+  return {
+    status,
+    rateLimitType,
+    resetsAt: toIso(raw.resetsAt) || own?.resetsAt || null,
+    // A rejected event carries no utilization of its own: the window is full.
+    utilization: toFraction(raw.utilization) ?? own?.utilization ?? (status === 'rejected' ? 1 : null),
+    surpassedThreshold: toFraction(raw.surpassedThreshold),
+    overageStatus: STATUSES.has(String(raw.overageStatus || '')) ? String(raw.overageStatus) : null,
+    isUsingOverage: raw.isUsingOverage === true || raw.overageInUse === true,
+    windows,
+    observedAt: new Date(now).toISOString(),
+  };
+}
+
+export function isRateLimitEvent(sdkMessage) {
+  return String(sdkMessage?.type || '') === 'rate_limit_event';
+}
+
+/** What makes two reports the same to a reader: a repeat is not published. */
+export function rateLimitInfoKey(info) {
+  if (!info) return '';
+  const percent = info.utilization === null ? '' : Math.round(info.utilization * 100);
+  return [info.status, info.rateLimitType || '', info.resetsAt || '', percent, info.isUsingOverage ? 'overage' : ''].join('|');
+}
+
+/**
+ * Did the CLI refuse this turn because the usage limit is reached?
+ *
+ * The ONE place that decides it. Returns null, or what the relay needs to
+ * pause the turn: `{ rateLimitType, resetsAt, text }`. `resetsAt` is null
+ * when the report names no reset still ahead; the relay then tries again
+ * shortly.
+ *
+ * - `rateLimit`: the latest normalized `rate_limit_info` of the process.
+ * - `result`: the raw SDK `result` message the turn ended with, if any.
+ * - `assistantError`: the `error` field of the turn's last assistant message.
+ * - `errorText`: the text of an exception, when the stream threw instead.
+ *
+ * A refusal needs both halves: the turn ended in an error that names the
+ * limit, and the CLI reported a rejected window, with its reset still ahead
+ * or just now. Without a rejected report (the limit reached in the middle of
+ * a long turn, under the report the turn began with) the error has to name
+ * the limit twice over: by its kind and in its words. A plain API 429 (an
+ * API key's requests per minute) comes with no report at all and stays the
+ * failure it is; a rejected window the account's extra usage covers ends no
+ * turn.
+ */
+export function classifyUsageLimitRefusal({
+  rateLimit = null,
+  result = null,
+  assistantError = '',
+  errorText = '',
+  now = Date.now(),
+} = {}) {
+  if (!rateLimit) return null;
+  const resultText = String(result?.result || '').trim();
+  const thrownText = String(errorText || '').trim();
+  const endedInError = result ? result.is_error === true || String(result.subtype || '') !== 'success' : Boolean(thrownText);
+  if (!endedInError) return null;
+
+  const byKind = String(assistantError || '') === 'rate_limit' || Number(result?.api_error_status) === 429;
+  const inWords = LIMIT_TEXT.test(resultText) || LIMIT_TEXT.test(thrownText);
+  const rejected = rateLimit.status === 'rejected';
+  const resetsAtMs = Date.parse(rateLimit.resetsAt || '');
+  const resetAhead = Number.isFinite(resetsAtMs) && resetsAtMs > now;
+
+  if (rejected) {
+    if (!byKind && !inWords) return null;
+    if (!resetAhead) {
+      const observedAtMs = Date.parse(rateLimit.observedAt || '');
+      if (!Number.isFinite(observedAtMs) || now - observedAtMs > USAGE_LIMIT_REPORT_FRESH_MS) return null;
+    }
+  } else if (!byKind || !inWords) {
+    return null;
+  }
+
+  // A warning names the window that was about to run out; a report that
+  // allowed everything says nothing about which reset to wait for.
+  const namesTheReset = resetAhead && (rejected || rateLimit.status === 'allowed_warning');
+  return {
+    rateLimitType: rejected || namesTheReset ? rateLimit.rateLimitType : null,
+    resetsAt: namesTheReset ? rateLimit.resetsAt : null,
+    text: resultText || thrownText,
+  };
+}
+
+/** When a paused turn is sent again: the reset plus a margin. */
+export function usageLimitResumeAt(resetsAt, { marginMs = USAGE_LIMIT_RESUME_MARGIN_MS } = {}) {
+  const ms = Date.parse(resetsAt || '');
+  return Number.isFinite(ms) ? new Date(ms + marginMs).toISOString() : null;
+}
+
+/** Whether a pause ends by itself, or waits for the user (a reset days away). */
+export function usageLimitResumesByItself(resetsAt, { now = Date.now(), maxWaitMs = USAGE_LIMIT_AUTO_RESUME_MAX_MS } = {}) {
+  const ms = Date.parse(resetsAt || '');
+  return Number.isFinite(ms) && ms - now <= maxWaitMs;
+}
+
+/**
+ * What the worker reports for a refused turn, inside the response's
+ * `terminalError`. A relay that knows the kind pauses the row; an older one
+ * fails the turn with this message, as before.
+ */
+export function buildUsageLimitFailure(message, refusal) {
+  const label = usageLimitWindowLabel(refusal?.rateLimitType);
+  return {
+    kind: USAGE_LIMIT_KIND,
+    code: USAGE_LIMIT_CODE,
+    stableCode: USAGE_LIMIT_STABLE_CODE,
+    message: String(refusal?.text || '').trim() || `The Claude ${label} is reached.`,
+    guidance: 'The turn carries on by itself after the reset.',
+    rateLimitType: refusal?.rateLimitType || null,
+    resetsAt: refusal?.resetsAt || null,
+    failedAt: new Date().toISOString(),
+    queueMessageId: String(message?.id || '') || null,
+  };
+}
+
+/**
+ * Per-process bookkeeping for the worker: the latest report, what the turn's
+ * last assistant message said, and which reports are worth publishing.
+ */
+export function createUsageLimitTracker({ now = () => Date.now() } = {}) {
+  let latest = null;
+  let publishedKey = '';
+  let assistantError = '';
+
+  /** Returns the normalized report when it is news to the relay, else null. */
+  function observe(sdkMessage) {
+    const type = String(sdkMessage?.type || '');
+    if (type === 'rate_limit_event') {
+      const info = normalizeRateLimitInfo(sdkMessage.rate_limit_info, { now: now() });
+      if (!info) return null;
+      latest = info;
+      const key = rateLimitInfoKey(info);
+      if (key === publishedKey) return null;
+      publishedKey = key;
+      return info;
+    }
+    if (type === 'assistant' && !sdkMessage.parent_tool_use_id) {
+      assistantError = String(sdkMessage.error || '').trim();
+    }
+    return null;
+  }
+
+  function classifyResult(sdkResult) {
+    return classifyUsageLimitRefusal({ rateLimit: latest, result: sdkResult, assistantError, now: now() });
+  }
+
+  function classifyException(error) {
+    return classifyUsageLimitRefusal({
+      rateLimit: latest,
+      assistantError,
+      errorText: String(error?.message || error || ''),
+      now: now(),
+    });
+  }
+
+  return {
+    observe,
+    classifyResult,
+    classifyException,
+    get latest() { return latest; },
+  };
+}