@jameslovespancakes/pi-plus 1.0.0

package/src/core/anthropic/quota.ts

@@ -0,0 +1,253 @@
+import { loadAccounts, saveAccount, type Account, type QuotaSnapshot } from "./store.ts";
+import { refreshToken } from "./oauth.ts";
+
+/**
+ * Quota tracking.
+ *
+ * There are two sources, and the cheap one is strongly preferred:
+ *
+ *   1. Response headers. Every `/v1/messages` reply carries the same numbers
+ *      as the usage endpoint, so the account actually serving traffic keeps
+ *      its snapshot current at no request cost at all.
+ *   2. The usage endpoint. Only needed for accounts that are NOT serving
+ *      traffic, since routing compares accounts and an idle one would
+ *      otherwise never update.
+ *
+ * Polling used to run on a 5 minute timer regardless of activity. That is what
+ * the backoff below exists for: the endpoint rate limits, it answers 429 with
+ * `retry-after: 0`, and `pollQuota` reports failure as `undefined`, so the
+ * throttling was invisible and simply left routing on stale data.
+ */
+
+const QUOTA_URL = "https://api.anthropic.com/api/oauth/usage";
+const TIMEOUT_MS = 10_000;
+/**
+ * Selection tolerates a snapshot this old before it is worth re-polling.
+ *
+ * This doubles as the poll rate limiter. Polling is triggered by sending a
+ * message, so this is the floor between polls however fast you type: send a
+ * message after the window and it polls, send ten inside it and it polls once.
+ */
+export const QUOTA_FRESH_MS = 10 * 60_000;
+/** After a 429, wait at least this long before touching the endpoint again. */
+export const QUOTA_BACKOFF_MS = 15 * 60_000;
+
+/** Per-account earliest next poll, set when the endpoint rate limits us. */
+const blockedUntil = new Map<string, number>();
+
+/** True when a recent 429 means this account must not be polled yet. */
+export function isPollBlocked(accountId: string, now = Date.now()): boolean {
+  const until = blockedUntil.get(accountId);
+  if (until === undefined) return false;
+  if (now >= until) { blockedUntil.delete(accountId); return false; }
+  return true;
+}
+
+/** Visible for tests; clears the backoff table. */
+export function resetPollBackoff(): void {
+  blockedUntil.clear();
+}
+
+const pct = (value: unknown): number | undefined => {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? Math.min(100, Math.max(0, n)) : undefined;
+};
+
+/** Normalises Anthropic's payload into the snapshot shape the store holds. */
+export function parseQuota(body: any, now = Date.now()): QuotaSnapshot {
+  const window = (raw: any) => {
+    const used = pct(raw?.utilization);
+    if (used === undefined) return undefined;
+    return {
+      usedPercent: used,
+      remainingPercent: 100 - used,
+      resetsAt: typeof raw?.resets_at === "string" ? raw.resets_at : undefined,
+      checkedAt: now,
+    };
+  };
+
+  const scoped = (Array.isArray(body?.limits) ? body.limits : [])
+    .map((limit: any) => {
+      const used = pct(limit?.percent);
+      if (used === undefined) return undefined;
+      return {
+        id: String(limit?.scope?.model?.display_name ?? limit?.id ?? "scoped").toLowerCase(),
+        usedPercent: used,
+        remainingPercent: 100 - used,
+        resetsAt: typeof limit?.resets_at === "string" ? limit.resets_at : undefined,
+        checkedAt: now,
+      };
+    })
+    .filter(Boolean);
+
+  return {
+    five_hour: window(body?.five_hour),
+    seven_day: window(body?.seven_day),
+    scoped: scoped.length ? scoped : undefined,
+    checkedAt: now,
+    source: "poll",
+  };
+}
+
+export function isFresh(quota: QuotaSnapshot | undefined, now = Date.now()): boolean {
+  const at = quota?.checkedAt ?? 0;
+  return at > 0 && now - at < QUOTA_FRESH_MS;
+}
+
+/**
+ * Reads a quota snapshot out of `/v1/messages` response headers.
+ *
+ * Anthropic reports utilisation here as a FRACTION (`0.16`), while the usage
+ * endpoint reports a PERCENT (`16`). Verified against the same account at the
+ * same moment, including matching reset timestamps. Scaling by 100 is what
+ * makes the two sources comparable, so do not drop it.
+ *
+ * Returns undefined when the headers are absent, which is normal: they do not
+ * appear on 4xx replies, and non-Anthropic transports may not expose them.
+ */
+export function parseQuotaHeaders(
+  headers: Record<string, unknown> | undefined,
+  now = Date.now(),
+): QuotaSnapshot | undefined {
+  if (!headers) return undefined;
+
+  // Header casing is not guaranteed across transports.
+  const get = (name: string): string | undefined => {
+    const key = `anthropic-ratelimit-unified-${name}`;
+    const direct = headers[key] ?? headers[key.toUpperCase()];
+    if (direct !== undefined && direct !== null) return String(direct);
+    const found = Object.keys(headers).find((k) => k.toLowerCase() === key);
+    return found === undefined ? undefined : String(headers[found]);
+  };
+
+  const window = (prefix: string) => {
+    const raw = get(`${prefix}-utilization`);
+    if (raw === undefined) return undefined;
+    const fraction = Number(raw);
+    if (!Number.isFinite(fraction)) return undefined;
+
+    const used = Math.min(100, Math.max(0, fraction * 100));
+    const resetSeconds = Number(get(`${prefix}-reset`));
+    return {
+      usedPercent: used,
+      remainingPercent: 100 - used,
+      resetsAt: Number.isFinite(resetSeconds) && resetSeconds > 0
+        ? new Date(resetSeconds * 1000).toISOString()
+        : undefined,
+      checkedAt: now,
+    };
+  };
+
+  const five_hour = window("5h");
+  const seven_day = window("7d");
+  if (!five_hour && !seven_day) return undefined;
+
+  return { five_hour, seven_day, checkedAt: now, source: "headers" };
+}
+
+/**
+ * Merges a header-derived snapshot into an account.
+ *
+ * Scoped per-model limits only come from the usage endpoint, so they are
+ * carried over from the previous snapshot rather than dropped.
+ */
+export function applyQuotaHeaders(
+  accountId: string,
+  headers: Record<string, unknown> | undefined,
+  now = Date.now(),
+): boolean {
+  const fresh = parseQuotaHeaders(headers, now);
+  if (!fresh) return false;
+
+  const storage = loadAccounts();
+  const account = storage?.accounts.find((a) => a.id === accountId);
+  if (!account) return false;
+
+  saveAccount({ ...account, quota: { ...fresh, scoped: account.quota?.scoped } });
+  return true;
+}
+
+/**
+ * Polls one account. Returns undefined rather than throwing on failure.
+ *
+ * Pass `accountId` so a 429 registers backoff; without it the caller can
+ * hammer a throttled endpoint and silently keep stale quota.
+ */
+export async function pollQuota(
+  accessToken: string,
+  accountId?: string,
+): Promise<QuotaSnapshot | undefined> {
+  if (accountId && isPollBlocked(accountId)) return undefined;
+  try {
+    const response = await fetch(QUOTA_URL, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "anthropic-beta": "oauth-2025-04-20",
+        Accept: "application/json",
+      },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (response.status === 429 && accountId) {
+      // `retry-after` is commonly 0 here, which is not a usable hint, so the
+      // floor is ours rather than the server's.
+      const hint = Number(response.headers.get("retry-after")) * 1000;
+      const wait = Number.isFinite(hint) && hint > 0 ? hint : QUOTA_BACKOFF_MS;
+      blockedUntil.set(accountId, Date.now() + Math.max(wait, QUOTA_BACKOFF_MS));
+      return undefined;
+    }
+    if (!response.ok) return undefined;
+    return parseQuota(await response.json());
+  } catch {
+    return undefined;
+  }
+}
+
+/** A token good for at least a minute, refreshing and persisting if needed. */
+export async function ensureAccessToken(account: Account): Promise<string | undefined> {
+  if (account.access && typeof account.expires === "number" && Date.now() + 60_000 < account.expires) {
+    return account.access;
+  }
+  if (!account.refresh) return account.access;
+
+  const refreshed = await refreshToken({ refreshToken: account.refresh, maxRetries: 0 });
+  // Persist immediately: Anthropic may rotate the refresh token, and losing the
+  // new one would invalidate the account.
+  saveAccount({
+    ...account,
+    access: refreshed.access,
+    refresh: refreshed.refresh,
+    expires: refreshed.expires,
+    lastRefreshedAt: Date.now(),
+  });
+  return refreshed.access;
+}
+
+/**
+ * Refreshes stale quota for every usable account, in parallel.
+ * Best-effort: a failure leaves the previous snapshot in place.
+ */
+export async function refreshAllQuota(force = false): Promise<number> {
+  const storage = loadAccounts();
+  if (!storage) return 0;
+  const now = Date.now();
+
+  const stale = storage.accounts.filter(
+    (a) => a.enabled !== false && a.type === "oauth"
+      && (force || !isFresh(a.quota, now))
+      && !isPollBlocked(a.id, now));
+
+  const results = await Promise.all(stale.map(async (account) => {
+    try {
+      const token = await ensureAccessToken(account);
+      if (!token) return false;
+      const quota = await pollQuota(token, account.id);
+      if (!quota) return false;
+      saveAccount({ ...account, quota });
+      return true;
+    } catch {
+      return false;
+    }
+  }));
+
+  return results.filter(Boolean).length;
+}

package/src/core/anthropic/routing.ts

@@ -0,0 +1,168 @@
+import { MAIN_ACCOUNT_ID, type Account, type QuotaSnapshot, type QuotaWindow, type RoutingMode } from "./store.ts";
+
+/**
+ * Account selection and sticky session assignment.
+ *
+ * Two jobs:
+ *   1. score each candidate by how much work it can absorb
+ *   2. keep a session on one account, because Anthropic's prompt cache is
+ *      per-account and migrating throws it away
+ */
+
+/** How long each window takes to refill completely. */
+export const WINDOW_HOURS = { five_hour: 5, seven_day: 168, scoped: 168 } as const;
+export type WindowKey = keyof typeof WINDOW_HOURS;
+
+export type Family = "fable" | "opus" | "general";
+
+export function familyForModel(model: string | undefined): Family {
+  const id = (model ?? "").toLowerCase();
+  if (id.includes("fable") || id.includes("mythos")) return "fable";
+  if (id.includes("opus")) return "opus";
+  return "general";
+}
+
+export interface Candidate {
+  id: string;
+  access?: string;
+  quota?: QuotaSnapshot;
+  /** Config order; `main` is 0, so it wins ties. */
+  order: number;
+  account?: Account;
+}
+
+/**
+ * Hours of wall-clock recovery per point of quota spent.
+ *
+ * Expressed against the window's own length rather than its distance to reset:
+ * a 5h window regenerates 34x faster than a 7d one, so a point spent there is
+ * far cheaper. Returns Infinity at or below zero, which collapses the account's
+ * weight to 0 and removes it from selection.
+ */
+export function recoveryCost(window: QuotaWindow | undefined, key: WindowKey, reserve = 0): number {
+  const remaining = window?.remainingPercent;
+  if (!Number.isFinite(remaining)) return Infinity;
+  const spendable = Math.max(0, (remaining as number) - reserve);
+  if (spendable <= 0) return Infinity;
+  return WINDOW_HOURS[key] / spendable;
+}
+
+/** Scoped windows are model-specific; match the one governing this model. */
+export function scopedWindowFor(quota: QuotaSnapshot | undefined, modelId?: string): QuotaWindow | undefined {
+  const scoped = quota?.scoped;
+  if (!Array.isArray(scoped) || scoped.length === 0) return undefined;
+  if (!modelId) return scoped[0];
+  const id = modelId.toLowerCase();
+  return scoped.find((w) => {
+    const name = String((w as any).id ?? (w as any).scope?.model?.display_name ?? "").toLowerCase();
+    return name && (id.includes(name) || name.includes(id));
+  }) ?? scoped[0];
+}
+
+/**
+ * Capacity score. Higher is better, 0 means unusable.
+ *
+ * Costs are summed and inverted rather than taking the minimum window, so a
+ * cheap fast-refilling window still contributes instead of being masked by a
+ * slow one. Any window at zero yields Infinity and zeroes the account, which
+ * preserves the hard exclusion rule.
+ */
+export function candidateWeight(candidate: Candidate, family: Family, modelId?: string, reserve = 0): number {
+  const quota = candidate.quota;
+  if (!quota) return 0;
+
+  const costs = [
+    recoveryCost(quota.five_hour, "five_hour", reserve),
+    recoveryCost(quota.seven_day, "seven_day", reserve),
+  ];
+
+  // Fable requests are additionally gated by their scoped window.
+  if (family === "fable") {
+    const scoped = scopedWindowFor(quota, modelId);
+    if (scoped) costs.push(recoveryCost(scoped, "scoped", reserve));
+  }
+
+  const total = costs.reduce((sum, c) => sum + c, 0);
+  return Number.isFinite(total) && total > 0 ? 1 / total : 0;
+}
+
+export interface Assignment {
+  accountId: string;
+  family: Family;
+  assignedAt: number;
+  lastSeenAt: number;
+}
+
+export interface SelectInput {
+  candidates: Candidate[];
+  family: Family;
+  modelId?: string;
+  mode: RoutingMode;
+  /** Existing sticky assignment for this session, if any. */
+  assignment?: Assignment;
+  now?: number;
+}
+
+export interface Selection {
+  candidate: Candidate;
+  reason: "sticky" | "weighted" | "main-first" | "fallback-first" | "only";
+}
+
+/**
+ * Picks an account.
+ *
+ * `main-first` and `fallback-first` are simple orderings. `sticky-balanced`
+ * keeps the session where it is while that account is still viable, and
+ * otherwise takes the highest-weight candidate.
+ */
+export function selectAccount(input: SelectInput): Selection | undefined {
+  const usable = input.candidates.filter((c) => c.access);
+  if (usable.length === 0) return undefined;
+  if (usable.length === 1) return { candidate: usable[0], reason: "only" };
+
+  if (input.mode === "main-first" || input.mode === "fallback-first") {
+    const ordered = [...usable].sort((a, b) =>
+      input.mode === "main-first" ? a.order - b.order : b.order - a.order);
+    const viable = ordered.find((c) => candidateWeight(c, input.family, input.modelId) > 0);
+    return viable ? { candidate: viable, reason: input.mode } : undefined;
+  }
+
+  const weighted = usable
+    .map((candidate) => ({ candidate, weight: candidateWeight(candidate, input.family, input.modelId) }))
+    .filter((entry) => entry.weight > 0);
+  if (weighted.length === 0) return undefined;
+
+  // Stay put while the assigned account can still serve: migrating discards
+  // the prompt cache, which costs more than a slightly better weight gains.
+  if (input.assignment) {
+    const held = weighted.find((e) => e.candidate.id === input.assignment!.accountId);
+    if (held) return { candidate: held.candidate, reason: "sticky" };
+  }
+
+  weighted.sort((a, b) =>
+    b.weight - a.weight
+    || a.candidate.order - b.candidate.order
+    || a.candidate.id.localeCompare(b.candidate.id));
+  return { candidate: weighted[0].candidate, reason: "weighted" };
+}
+
+/** Seconds until the soonest window that would unblock this model resets. */
+export function retryAfterSeconds(candidates: Candidate[], family: Family, modelId?: string, now = Date.now()): number {
+  const resets: number[] = [];
+  for (const candidate of candidates) {
+    const quota = candidate.quota;
+    if (!quota) continue;
+    const windows: (QuotaWindow | undefined)[] = [quota.five_hour, quota.seven_day];
+    if (family === "fable") windows.push(scopedWindowFor(quota, modelId));
+    for (const w of windows) {
+      if (!w?.resetsAt) continue;
+      if ((w.remainingPercent ?? 0) > 0) continue;
+      const at = Date.parse(w.resetsAt);
+      if (Number.isFinite(at) && at > now) resets.push(at);
+    }
+  }
+  if (resets.length === 0) return 60;
+  return Math.max(1, Math.ceil((Math.min(...resets) - now) / 1000));
+}
+
+export { MAIN_ACCOUNT_ID };

package/src/core/anthropic/store.ts

@@ -0,0 +1,225 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * Anthropic account store.
+ *
+ * Byte-compatible with @cortexkit/anthropic-auth-core so both implementations
+ * can read the same files and reverting stays possible. The split is theirs and
+ * is worth preserving: durable identity in `anthropic-auth.json`, live secrets
+ * and volatile quota in `anthropic-auth-state.json`.
+ *
+ *   anthropic-auth.json        id, label, type, enabled, addedAt, routing
+ *   anthropic-auth-state.json  access, refresh, expires, quota, lastUsed, ...
+ *
+ * Keeping secrets out of the config file means the config can be inspected,
+ * diffed or backed up without exposing tokens.
+ */
+
+export const CONFIG_FILE = "anthropic-auth.json";
+export const STATE_FILE = "anthropic-auth-state.json";
+
+export interface QuotaWindow {
+  remainingPercent?: number;
+  usedPercent?: number;
+  resetsAt?: string;
+  checkedAt?: number;
+  id?: string;
+}
+
+export interface QuotaSnapshot {
+  five_hour?: QuotaWindow;
+  seven_day?: QuotaWindow;
+  scoped?: QuotaWindow[];
+  checkedAt?: number;
+  source?: "poll" | "headers";
+  [key: string]: unknown;
+}
+
+export interface Account {
+  id: string;
+  label?: string;
+  type: "oauth" | "api";
+  enabled?: boolean;
+  addedAt?: number;
+  // state-file fields
+  access?: string;
+  refresh?: string;
+  expires?: number;
+  lastUsed?: number;
+  lastRefreshedAt?: number;
+  authLineageId?: string;
+  quota?: QuotaSnapshot;
+  apiKey?: string;
+}
+
+export type RoutingMode = "main-first" | "fallback-first" | "sticky-balanced";
+
+export interface Storage {
+  version?: number;
+  mainAccountId?: string;
+  main?: Record<string, unknown>;
+  accounts: Account[];
+  routing?: { mode?: RoutingMode };
+  [key: string]: unknown;
+}
+
+/** Fields that belong in the durable config file. */
+const CONFIG_FIELDS = ["id", "label", "type", "enabled", "addedAt", "baseURL", "authHeader"] as const;
+/** Fields that belong in the state file. */
+const STATE_FIELDS = [
+  "authLineageId", "access", "refresh", "expires", "lastUsed",
+  "lastRefreshedAt", "lastRefreshError", "lastQuotaRefreshError", "quota", "profile", "prime", "apiKey",
+] as const;
+
+function agentDir(): string {
+  return process.env.PI_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+export function configPath(): string {
+  return process.env.PI_ANTHROPIC_AUTH_FILE ?? join(agentDir(), CONFIG_FILE);
+}
+
+export function statePath(config = configPath()): string {
+  return config.endsWith(CONFIG_FILE) ? join(dirname(config), STATE_FILE) : `${config}.state.json`;
+}
+
+function readJson<T>(path: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Temp-file + rename, so a crash cannot leave a half-written credential file. */
+function writeJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(value, undefined, 2), { encoding: "utf8", mode: 0o600 });
+  renameSync(temp, path);
+}
+
+const pick = <T extends object>(source: any, keys: readonly string[]): T =>
+  Object.fromEntries(keys.filter((k) => source?.[k] !== undefined).map((k) => [k, source[k]])) as T;
+
+export function emptyStorage(): Storage {
+  return { version: 1, accounts: [], routing: { mode: "main-first" } };
+}
+
+/**
+ * Reads both files and rejoins them into whole accounts.
+ *
+ * A state file can exist without a config file: a main-account refresh writes
+ * state but never touches config. Returns undefined only when neither exists.
+ */
+export function loadAccounts(config = configPath()): Storage | undefined {
+  const cfg = readJson<Storage>(config);
+  const state = readJson<{ main?: any; accounts?: Record<string, any> }>(statePath(config));
+  if (!cfg && !state) return undefined;
+
+  const base: Storage = cfg ?? emptyStorage();
+  const byId = state?.accounts ?? {};
+
+  return {
+    ...base,
+    main: { ...(base.main ?? {}), ...(state?.main ?? {}) },
+    accounts: (base.accounts ?? []).map((account) => ({ ...account, ...(byId[account.id] ?? {}) })),
+  };
+}
+
+/** Writes both files, routing each field to the correct one. */
+export function saveAccounts(storage: Storage, config = configPath()): void {
+  const existingCfg = readJson<Record<string, unknown>>(config) ?? {};
+  const existingState = readJson<Record<string, any>>(statePath(config)) ?? {};
+
+  const cfg = {
+    ...existingCfg,
+    ...storage,
+    version: storage.version ?? 1,
+    accounts: storage.accounts.map((a) => pick(a, CONFIG_FIELDS)),
+  };
+  delete (cfg as any).main;
+
+  const state = {
+    ...existingState,
+    version: 1,
+    main: storage.main && Object.keys(storage.main).length ? storage.main : undefined,
+    accounts: Object.fromEntries(storage.accounts.map((a) => [a.id, pick(a, STATE_FIELDS)])),
+  };
+  if (state.main === undefined) delete state.main;
+
+  writeJson(config, cfg);
+  writeJson(statePath(config), state);
+}
+
+/** Inserts or replaces one account, leaving every other account untouched. */
+export function saveAccount(account: Account, config = configPath()): void {
+  const storage = loadAccounts(config) ?? emptyStorage();
+  const index = storage.accounts.findIndex((a) => a.id === account.id);
+  if (index >= 0) storage.accounts[index] = { ...storage.accounts[index], ...account };
+  else storage.accounts.push(account);
+  saveAccounts(storage, config);
+}
+
+export function removeAccount(id: string, config = configPath()): boolean {
+  const storage = loadAccounts(config);
+  if (!storage) return false;
+  const before = storage.accounts.length;
+  storage.accounts = storage.accounts.filter((a) => a.id !== id);
+  if (storage.accounts.length === before) return false;
+  saveAccounts(storage, config);
+  return true;
+}
+
+export const isOAuthAccount = (a: Account): boolean => a.type === "oauth" && !!a.refresh;
+export const isUsable = (a: Account): boolean => a.enabled !== false && isOAuthAccount(a);
+
+export function getRoutingMode(storage: Storage | undefined): RoutingMode {
+  const mode = storage?.routing?.mode;
+  return mode === "sticky-balanced" || mode === "fallback-first" || mode === "main-first" ? mode : "main-first";
+}
+
+export function setRoutingMode(mode: RoutingMode, config = configPath()): Storage {
+  const storage = loadAccounts(config) ?? emptyStorage();
+  storage.routing = { ...(storage.routing ?? {}), mode };
+  saveAccounts(storage, config);
+  return storage;
+}
+
+/**
+ * The pseudo-account id for pi's own Anthropic credential.
+ *
+ * `main` is NOT one of `storage.accounts`. Its tokens live in pi's `auth.json`
+ * and reach the provider as the primary access token at request time;
+ * `mainAccountId` is only a stable name for it, and an empty `main` block in
+ * the state file is normal.
+ *
+ * This is easy to mistake for stale data and delete. Doing so breaks
+ * `main-first` routing and orphans every routing assignment targeting `main`.
+ */
+export const MAIN_ACCOUNT_ID = "main";
+
+/**
+ * Drops only references that genuinely cannot resolve: config accounts with no
+ * credentials in the state file.
+ *
+ * Deliberately leaves `mainAccountId` and an empty `main` block alone, for the
+ * reason above.
+ */
+export function pruneStale(config = configPath()): string[] {
+  const storage = loadAccounts(config);
+  if (!storage) return [];
+  const fixes: string[] = [];
+
+  const hasCreds = (a: Account) => !!(a.access || a.refresh || a.apiKey);
+  const before = storage.accounts.length;
+  storage.accounts = storage.accounts.filter(hasCreds);
+  if (storage.accounts.length !== before) {
+    fixes.push(`removed ${before - storage.accounts.length} credential-less account(s)`);
+  }
+
+  if (fixes.length) saveAccounts(storage, config);
+  return fixes;
+}

package/src/core/anthropic/vendor/README.md

@@ -0,0 +1,36 @@
+# Vendored: xxhash-wasm
+
+`xxhash-wasm.js` is the ESM build of [xxhash-wasm](https://github.com/jungomi/xxhash-wasm),
+MIT licensed (see `xxhash-wasm.LICENSE.md`), copied in verbatim.
+
+## Why vendored rather than depended on
+
+The billing checksum in `../client-identity.ts` needs xxHash64. Two things were
+tried before this:
+
+1. **A hand-written BigInt implementation.** It produced correct values for
+   empty and very short inputs and wrong values for everything longer. Four
+   separate bugs were found and fixed, each time with the output still wrong.
+   Guessing further at a hash function was not converging.
+2. **`xxhash-wasm` as an npm dependency.** Rejected: the point of the extraction
+   is that no unaudited package sits in the auth path.
+
+Vendoring gets both: the algorithm is known-correct, and the code lives in this
+repository with no install-time dependency.
+
+## What this is
+
+A single self-contained ~11 KB `.js` file with the compiled WebAssembly inlined
+as a byte array. It is not fetched, built, or downloaded at runtime. The only
+import is the file itself.
+
+## Regenerating
+
+```sh
+npm pack xxhash-wasm@<version>
+tar -xzf xxhash-wasm-*.tgz
+cp package/esm/xxhash-wasm.js src/core/anthropic/vendor/
+```
+
+Record the version when you do. The current copy came from `xxhash-wasm` as
+installed by pi's own tree on 2026-09-19.