@toddzheng024/dscode-bundle 0.7.6 → 0.7.8

package/plugins/providers/openrouter-account.mjs

@@ -0,0 +1,171 @@
+// OpenRouter account facts for /openrouter and the footer balance. The inference key
+// reads the account credits and its own limit and usage; an optional management key,
+// which cannot call models, adds every key's usage and the last 30 days of spend.
+// This directory also ships beside the TUI, so the module imports nothing.
+export const OPENROUTER_API = 'https://openrouter.ai/api/v1';
+export const MANAGEMENT_REF = 'OPENROUTER_MANAGEMENT_KEY';
+
+const finite = value => {
+  const number = Number(value);
+  return value !== null && value !== undefined && value !== '' && Number.isFinite(number) ? number : undefined;
+};
+
+export class OpenRouterAccountError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'OpenRouterAccountError';
+    this.status = status;
+  }
+}
+
+async function get(path, key, { fetch: fetchImpl = globalThis.fetch, signal } = {}) {
+  let response;
+  try {
+    response = await fetchImpl(`${OPENROUTER_API}${path}`, { headers: { authorization: `Bearer ${key}`, accept: 'application/json' }, signal });
+  } catch (error) {
+    throw new OpenRouterAccountError(`OpenRouter is unreachable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let body;
+  try { body = await response.json(); } catch { body = undefined; }
+  if (!response.ok) throw new OpenRouterAccountError(typeof body?.error?.message === 'string' ? body.error.message : `HTTP ${response.status}`, response.status);
+  return body;
+}
+
+/** Account credits from a `/credits` body, or undefined when it carries none. */
+export function creditsOf(body) {
+  const total = finite(body?.data?.total_credits), used = finite(body?.data?.total_usage);
+  if (total === undefined || used === undefined || total < 0 || used < 0) return undefined;
+  return { total, used, remaining: Math.max(0, total - used) };
+}
+
+/** Remaining USD account credits from a `/credits` body: purchased minus used. */
+export function parseOpenRouterCredits(body) {
+  return creditsOf(body)?.remaining ?? null;
+}
+
+/** Remaining USD credit limit from a `/key` body; null when the key has no limit. */
+export function parseOpenRouterKeyRemaining(body) {
+  const remaining = body?.data?.limit_remaining;
+  if (remaining == null) return null;
+  const value = Number(remaining);
+  return Number.isFinite(value) ? Math.max(0, value) : null;
+}
+
+function keyOf(raw) {
+  return {
+    label: typeof raw?.label === 'string' ? raw.label : undefined,
+    name: typeof raw?.name === 'string' && raw.name.length > 0 ? raw.name : undefined,
+    disabled: raw?.disabled === true,
+    limit: finite(raw?.limit),
+    limitRemaining: finite(raw?.limit_remaining),
+    usage: finite(raw?.usage),
+    usageDaily: finite(raw?.usage_daily),
+    usageWeekly: finite(raw?.usage_weekly),
+    usageMonthly: finite(raw?.usage_monthly),
+  };
+}
+
+/**
+ * Verify a management key before it is stored. Account activity is the reading OpenRouter
+ * refuses an inference key; `/credits`, though documented as management-only, serves both.
+ * @throws OpenRouterAccountError with a message fit for the key prompt.
+ */
+export async function verifyManagementKey(key, options) {
+  try {
+    await get('/activity', key, options);
+  } catch (error) {
+    if (error instanceof OpenRouterAccountError && (error.status === 401 || error.status === 403)) {
+      throw new OpenRouterAccountError('This is not a management key: OpenRouter refused it for account data. Create one under Settings → Management keys.', error.status);
+    }
+    throw error;
+  }
+}
+
+/** The `/activity` rows (last 30 completed UTC days) as totals and the top models with the providers that served them. */
+export function summarizeActivity(rows, top = 5) {
+  const models = new Map(), days = new Set();
+  let usage = 0, requests = 0;
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (typeof row?.model !== 'string') continue;
+    const cost = finite(row.usage) ?? 0, count = finite(row.requests) ?? 0;
+    usage += cost;
+    requests += count;
+    if (typeof row.date === 'string') days.add(row.date);
+    const entry = models.get(row.model) ?? { model: row.model, usage: 0, requests: 0, providers: new Map() };
+    entry.usage += cost;
+    entry.requests += count;
+    const name = typeof row.provider_name === 'string' && row.provider_name.length > 0 ? row.provider_name : 'unknown';
+    const served = entry.providers.get(name) ?? { name, usage: 0, requests: 0 };
+    served.usage += cost;
+    served.requests += count;
+    entry.providers.set(name, served);
+    models.set(row.model, entry);
+  }
+  const ranked = [...models.values()].sort((left, right) => right.usage - left.usage || right.requests - left.requests).slice(0, top)
+    .map(entry => ({ ...entry, providers: [...entry.providers.values()].sort((left, right) => right.usage - left.usage) }));
+  return { usage, requests, days: days.size, modelCount: models.size, models: ranked };
+}
+
+/**
+ * Everything /openrouter shows. Each section settles on its own: `{ value }`, `{ error }`,
+ * or undefined when the key it needs is missing.
+ */
+export async function loadOpenRouterAccount({ apiKey, managementKey, fetch, signal } = {}) {
+  const options = { fetch, signal };
+  const section = (key, run) => key ? run().then(value => ({ value }), error => ({ error: error instanceof Error ? error.message : String(error) })) : Promise.resolve(undefined);
+  const [key, credits, keys, activity] = await Promise.all([
+    section(apiKey, async () => keyOf((await get('/key', apiKey, options))?.data)),
+    section(managementKey ?? apiKey, async () => {
+      const credits = creditsOf(await get('/credits', managementKey ?? apiKey, options));
+      if (!credits) throw new Error('OpenRouter returned no account credits');
+      return credits;
+    }),
+    section(managementKey, async () => {
+      const body = await get('/keys', managementKey, options);
+      return (Array.isArray(body?.data) ? body.data : []).map(keyOf);
+    }),
+    section(managementKey, async () => summarizeActivity((await get('/activity', managementKey, options))?.data)),
+  ]);
+  return { hasApiKey: Boolean(apiKey), hasManagementKey: Boolean(managementKey), key, credits, keys, activity };
+}
+
+const money = value => Number.isFinite(value) ? `$${value.toFixed(2)}` : '$--';
+const limitText = key => key.limit === undefined ? 'no limit' : `limit ${money(key.limit)}, ${money(key.limitRemaining)} left`;
+
+/**
+ * The panel's lines for a loaded account.
+ * @returns `{ text, tone }` rows; tone is `title`, `value`, `dim` or `error`.
+ */
+export function openRouterAccountLines(account, { maxKeys = 5 } = {}) {
+  const lines = [];
+  const push = (text, tone = 'value') => lines.push({ text, tone });
+  if (!account.hasApiKey) push('No OpenRouter API key: run /login openrouter.', 'error');
+  if (account.credits?.value) {
+    const { remaining, total, used } = account.credits.value;
+    push(`Account balance  ${money(remaining)} · credits ${money(total)} · used ${money(used)}`, 'title');
+  } else if (account.credits?.error) push(`Account balance unavailable: ${account.credits.error}`, 'error');
+  else push('Account balance  $--', 'dim');
+  if (account.key?.value) {
+    const key = account.key.value;
+    push(`This key  ${key.label ?? 'unnamed'} · ${limitText(key)}`, 'title');
+    push(`  today ${money(key.usageDaily)} · week ${money(key.usageWeekly)} · month ${money(key.usageMonthly)}`, 'dim');
+  } else if (account.key?.error) push(`This key unavailable: ${account.key.error}`, 'error');
+  if (!account.hasManagementKey) push('API keys and 30-day spend  press m to add a management key', 'dim');
+  if (account.keys?.value) {
+    const keys = [...account.keys.value].sort((left, right) => (right.usageMonthly ?? 0) - (left.usageMonthly ?? 0));
+    push(`API keys (${keys.length})`, 'title');
+    for (const key of keys.slice(0, maxKeys)) {
+      const current = account.key?.value?.label !== undefined && key.label === account.key.value.label;
+      push(`  ${key.name ?? key.label ?? 'unnamed'}${current ? ' (this key)' : ''}${key.disabled ? ' · disabled' : ''} · today ${money(key.usageDaily)} · month ${money(key.usageMonthly)} · ${limitText(key)}`, key.disabled ? 'dim' : 'value');
+    }
+    if (keys.length > maxKeys) push(`  +${keys.length - maxKeys} more`, 'dim');
+  } else if (account.keys?.error) push(`API keys unavailable: ${account.keys.error}`, 'error');
+  if (account.activity?.value) {
+    const activity = account.activity.value;
+    push(`Last 30 days  ${money(activity.usage)} · ${activity.requests} requests · ${activity.modelCount} models`, 'title');
+    for (const model of activity.models) {
+      push(`  ${model.model} · ${money(model.usage)} · ${model.requests} req · ${model.providers.map(provider => `${provider.name} ${money(provider.usage)}`).join(', ')}`);
+    }
+  } else if (account.activity?.error) push(`Activity unavailable: ${account.activity.error}`, 'error');
+  return lines;
+}

package/plugins/session-bridge/communication.mjs

@@ -27,6 +27,17 @@ export class CommunicationService {
       ctx.on('agent/disposed', ({ agent }) => this.remove(agent)),
     ];
     for (const agent of ctx.agents.list()) this.start(agent);
+    // The mailbox keeps every settled message for a week; a daily prune stops the sqlite file
+    // from growing for the process lifetime (prune itself is throttled and cheap).
+    const pruneTimer = setInterval(() => { try { this.store.prune(); } catch (error) { ctx.logger?.warn?.(`Mailbox prune failed: ${error.message}`); } }, 24 * 3600000);
+    pruneTimer.unref?.();
+    // Through the same disposer list as the event handlers: a context without `effect` still clears it.
+    this.disposers.push(() => clearInterval(pruneTimer));
+    // A TUI restarts far more often than daily, and the throttle is per process, so the first
+    // sweep is forced once per start and deferred off the startup path.
+    const firstPrune = setTimeout(() => { try { this.store.prune({ force: true }); } catch (error) { ctx.logger?.warn?.(`Mailbox prune failed: ${error.message}`); } }, 15000);
+    firstPrune.unref?.();
+    this.disposers.push(() => clearTimeout(firstPrune));
   }
   background(promise) {
     this.pending.add(promise);

package/plugins/session-bridge/mailbox.mjs

@@ -3,7 +3,11 @@ import { mkdirSync, chmodSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID, createHash, timingSafeEqual } from 'node:crypto';
 
-export const limits = Object.freeze({ depth: 3, sends: 8, ttlMs: 3600000, pending: 100, bytes: 1048576, contexts: 32 });
+export const limits = Object.freeze({ depth: 3, sends: 8, ttlMs: 3600000, pending: 100, bytes: 1048576, contexts: 32,
+  // The retention window is the real policy: settled rows are deleted only once they are past it.
+  // The row caps are a backstop against runaway growth from an idle or hostile sender; they are
+  // deliberately far above any realistic mailbox so they never cut a live late-reply window short.
+  retentionMs: 7 * 24 * 3600000, retainedMessages: 50000, retainedEvents: 5000, retainedChains: 20000, retainedRefusals: 5000 });
 export class CommunicationError extends Error {
   constructor(code, message) { super(message); this.code = code; }
 }
@@ -19,9 +23,14 @@ export function mergeContexts(...sets) {
 
 // Shared metadata only. Native Harness owns the session writer and model driver.
 export class Mailbox {
-  constructor(home, now = Date.now) {
+  constructor(home, now = Date.now, retention = {}) {
+    this.retention = Object.freeze(Object.fromEntries(['retentionMs', 'retainedMessages', 'retainedEvents', 'retainedChains', 'retainedRefusals'].map(key => {
+      const value = retention[key] ?? limits[key];
+      if (!Number.isSafeInteger(value) || value < 1) throw new Error(`Invalid mailbox retention: ${key}`);
+      return [key, value];
+    })));
     const root = join(home, 'session-communication'); mkdirSync(root, { recursive: true, mode: 0o700 });
-    this.db = new DatabaseSync(join(root, 'mailbox.sqlite')); this.now = now;
+    this.db = new DatabaseSync(join(root, 'mailbox.sqlite')); this.now = now; this.prunedAt = 0; this.eventsPrunedAt = new Map();
     chmodSync(join(root, 'mailbox.sqlite'), 0o600);
     this.db.exec(`PRAGMA busy_timeout=3000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
       CREATE TABLE IF NOT EXISTS owners(id TEXT PRIMARY KEY, generation TEXT NOT NULL, secret TEXT NOT NULL, socket TEXT NOT NULL);
@@ -34,6 +43,8 @@ export class Mailbox {
       CREATE TABLE IF NOT EXISTS refusals(key TEXT PRIMARY KEY);
       CREATE TABLE IF NOT EXISTS events(seq INTEGER PRIMARY KEY AUTOINCREMENT, recipient TEXT NOT NULL, message_id TEXT, type TEXT NOT NULL, time INTEGER NOT NULL, data TEXT NOT NULL);`);
   }
+  /** Cheap size check for the prune test surface. */
+  tableCounts() { return Object.fromEntries(['messages', 'events', 'refusals', 'chains', 'contexts'].map(name => [name, this.one(`SELECT COUNT(*) AS n FROM ${name}`).n])); }
   all(sql, ...args) { return this.db.prepare(sql).all(...args); }
   one(sql, ...args) { return this.db.prepare(sql).get(...args); }
   run(sql, ...args) { return this.db.prepare(sql).run(...args); }
@@ -91,6 +102,50 @@ export class Mailbox {
       this.run("UPDATE messages SET delivery='expired' WHERE id=?", row.id); this.event(id, 'expired', row.id);
     }
   }
+  /** Drop dead rows so the sqlite file stays bounded: settled messages past the retention
+   * window (or beyond the cap), their events, expired chains and old refusals. A request whose
+   * reply window may still be used is kept for the full retention window, because late replies
+   * are legal. Cheap, idempotent and throttled to once an hour. */
+  prune({ force = false } = {}) {
+    const now = this.now();
+    // The throttle is per process, but the table outlives it: the caller forces the first sweep.
+    if (!force && now - this.prunedAt < 3600000) return;
+    // Stamp only after the transaction commits, so a failed sweep retries instead of waiting an hour.
+    this.transaction(() => {
+      const cutoff = now - this.retention.retentionMs;
+      // Settle every request whose reply window has closed first: the in-process expiry sweep only
+      // runs on mailbox reads, so an idle session would otherwise never settle one.
+      for (const { recipient } of this.all('SELECT DISTINCT recipient FROM messages')) this.expire(recipient);
+      this.run("DELETE FROM messages WHERE delivery IN ('consumed','cancelled','expired','late') AND expires<=?", cutoff);
+      // Inside the retention window neither still-deliverable mail (accepted/admitted) nor a
+      // request whose reply window is still open is ever evicted: late replies are legal.
+      this.run("DELETE FROM messages WHERE delivery NOT IN ('accepted','admitted') AND expires<=? AND seq <= COALESCE((SELECT seq FROM messages WHERE delivery NOT IN ('accepted','admitted') AND expires<=? ORDER BY seq DESC LIMIT 1 OFFSET ?), -1)", now, now, this.retention.retainedMessages);
+      this.run('DELETE FROM events WHERE time<?', cutoff);
+      // Events are per-recipient cursors: cap each recipient's own stream so a busy session
+      // cannot age out another session's unread notifications.
+      for (const { recipient } of this.all('SELECT DISTINCT recipient FROM events')) {
+        this.run('DELETE FROM events WHERE recipient=? AND seq <= COALESCE((SELECT seq FROM events WHERE recipient=? ORDER BY seq DESC LIMIT 1 OFFSET ?), -1)', recipient, recipient, this.retention.retainedEvents);
+      }
+      this.run('DELETE FROM chains WHERE expires<?', cutoff);
+      this.run('DELETE FROM chains WHERE expires<? AND created < COALESCE((SELECT created FROM chains ORDER BY created DESC LIMIT 1 OFFSET ?), 0)', now, this.retention.retainedChains);
+      this.run('DELETE FROM refusals WHERE rowid NOT IN (SELECT rowid FROM refusals ORDER BY rowid DESC LIMIT ?)', this.retention.retainedRefusals);
+    });
+    this.prunedAt = now;
+  }
+
+  /** Event-only pruning for the watch loop: events are cheap rows and can be dropped more often. */
+  pruneEvents(recipient) {
+    const now = this.now();
+    // Per recipient: one session's poller must not starve another window.
+    if (now - (this.eventsPrunedAt.get(recipient) ?? 0) < 60000) return;
+    this.transaction(() => {
+      this.run('DELETE FROM events WHERE recipient=? AND time<?', recipient, now - this.retention.retentionMs);
+      // Scoped to one recipient: a busy session must not age out another session's notifications.
+      this.run('DELETE FROM events WHERE recipient=? AND seq <= COALESCE((SELECT seq FROM events WHERE recipient=? ORDER BY seq DESC LIMIT 1 OFFSET ?), -1)', recipient, recipient, this.retention.retainedEvents);
+    });
+    this.eventsPrunedAt.set(recipient, now);
+  }
+
   admit(recipient, request, auth) {
     const { text, mode = 'queue', kind = 'request', requestId, source = 'cli', inReplyTo, title } = request;
     if (typeof text !== 'string' || !text.trim() || Buffer.byteLength(text) > 64000) fail('invalid_text', 'Text must contain 1..64000 bytes');

package/plugins/session-bridge/server.mjs

@@ -135,7 +135,9 @@ export class SessionBridge {
           const poll = () => {
             if (!this.ctx.agents.get(agent.id)) { send({ type: 'closed', sessionId: agent.id, cursor }); socket.end(); return; }
             try { for (const event of this.communication.store.events(agent.id, cursor)) { if (!send({ type: 'event', event })) return; cursor = event.seq; } }
-            catch { socket.end(); }
+            catch { socket.end(); return; }
+            // Maintenance stays outside the read's failure domain: a busy or failing prune never closes a live watch.
+            try { this.communication.store.pruneEvents(agent.id); } catch (error) { this.ctx.logger?.warn?.(`Mailbox prune failed: ${error.message}`); }
           };
           poll(); const interval = setInterval(poll, 250); interval.unref(); cleanup = () => clearInterval(interval);
         } else if (req.method === 'watch') {

package/plugins/session-cards/manager.mjs

@@ -26,13 +26,21 @@ export class SessionCards {
   }
   path(session) { return join(this.root, fingerprint(session.id) + '.json'); }
   input(state) { return selectRequests(state.requests, this.config.maxMessages, this.config.maxInputChars); }
-  hash(state) { return fingerprint({ topicCount: this.config.topicCount, messages: this.input(state) }); }
+  /** A cheap key over everything `input()` reads: the memo can only be stale if this repeats. */
+  hashKey(state) { return `${state.requests.length}:${state.requests.at(-1)?.seq ?? ''}:${this.config.topicCount}:${this.config.maxMessages}:${this.config.maxInputChars}`; }
+  /** The digest hashes up to 16k characters, and arm()/updateStatus() ask for it
+   * several times per event across every tracked session; memoize until that key changes. */
+  hash(state) {
+    const key = this.hashKey(state);
+    if (state.digestKey !== key) { state.digest = fingerprint({ topicCount: this.config.topicCount, messages: this.input(state) }); state.digestKey = key; }
+    return state.digest;
+  }
   track(session) {
     if (this.closed || session.header.agentPreset !== 'dscode' || session.header.origin === 'subagent') return null;
     if (this.states.has(session.id)) return this.states.get(session.id);
     const requests = session.snapshotEvents().map(userRequest).filter(Boolean);
     const state = { session, requests: requests.slice(-this.config.maxMessages).map(m => ({ ...m, text: m.text.slice(0, 4000) })),
-      project: null, topics: [], hash: '', updatedAt: null, coveredUserSeq: null, status: 'empty', failures: 0,
+      project: null, topics: [], hash: '', digest: null, digestKey: null, updatedAt: null, coveredUserSeq: null, status: 'empty', failures: 0,
       nextAt: Date.now() + this.config.debounceMs, lastAttempt: 0, route: session.requestHeader()?.config, usage: { calls: 0, inputTokens: 0, outputTokens: 0, unknown: 0 } };
     try {
       const raw = readFileSync(this.path(session), 'utf8');
@@ -52,7 +60,8 @@ export class SessionCards {
     this.updateStatus(state); this.arm(); return state;
   }
   updateStatus(state) {
-    state.status = !this.config.enabled ? 'disabled' : !state.requests.length ? 'empty' : state.hash === this.hash(state) ? 'ready' : state.requests.length < this.config.minMessages ? 'insufficient' : 'pending';
+    const digest = !this.config.enabled || !state.requests.length ? null : this.hash(state);
+    state.status = !this.config.enabled ? 'disabled' : !state.requests.length ? 'empty' : state.hash === digest ? 'ready' : state.requests.length < this.config.minMessages ? 'insufficient' : 'pending';
   }
   observe(session, event) {
     const state = this.track(session); if (!state) return;
@@ -110,7 +119,7 @@ export class SessionCards {
       signal.throwIfAborted();
       if (this.states.get(state.session.id) !== state || hash !== this.hash(state)) return;
       const topics = validateTopics(result.value, messages, this.config.topicCount);
-      const updated = { topics, hash, updatedAt: Date.now(), coveredUserSeq: messages.at(-1)?.seq ?? null };
+      const updated = { topics, hash, digest: hash, digestKey: this.hashKey(state), updatedAt: Date.now(), coveredUserSeq: messages.at(-1)?.seq ?? null };
       this.save({ ...state, ...updated });
       Object.assign(state, updated); state.failures = 0; state.status = 'ready';
     } catch {

package/plugins/session-metrics/balance.mjs

@@ -1,10 +1,18 @@
+import { OPENROUTER_API, parseOpenRouterCredits, parseOpenRouterKeyRemaining } from '../providers/openrouter-account.mjs';
+
+export { parseOpenRouterCredits, parseOpenRouterKeyRemaining };
+
 // Remaining provider balance, refreshed on a long cache. DeepSeek's response
 // also carries the trusted clock: its `Date` header anchors peak/off-peak pricing
-// without a second network call. OpenRouter has no peak window, so only its
-// remaining credits are read.
+// without a second network call. OpenRouter has no peak window. Its account
+// credits (`/credits`) are documented as management-only but are served to
+// inference keys too; a key refused them falls back to its own remaining limit (`/key`).
 const SOURCES = {
-  'deepseek-official': { url: 'https://api.deepseek.com/user/balance', env: 'DEEPSEEK_API_KEY', parse: body => parseBalance(body), clock: true },
-  openrouter: { url: 'https://openrouter.ai/api/v1/credits', env: 'OPENROUTER_API_KEY', parse: body => parseOpenRouterCredits(body), clock: false },
+  'deepseek-official': { env: 'DEEPSEEK_API_KEY', clock: true, requests: ({ key }) => [{ url: 'https://api.deepseek.com/user/balance', key, parse: body => parseBalance(body) }] },
+  openrouter: { env: 'OPENROUTER_API_KEY', managementEnv: 'OPENROUTER_MANAGEMENT_KEY', clock: false, requests: ({ key, managementKey }) => [
+    { url: `${OPENROUTER_API}/credits`, key: managementKey ?? key, parse: parseOpenRouterCredits },
+    { url: `${OPENROUTER_API}/key`, key, parse: parseOpenRouterKeyRemaining },
+  ] },
 };
 export const BALANCE_PROVIDERS = Object.freeze(Object.keys(SOURCES));
 const CACHE_MS = 5 * 60 * 1000;
@@ -22,14 +30,6 @@ export function parseBalance(body) {
   return body?.is_available === false ? null : total;
 }
 
-/** Remaining USD credits from an OpenRouter `/credits` body: purchased minus used. */
-export function parseOpenRouterCredits(body) {
-  const credits = Number(body?.data?.total_credits), used = Number(body?.data?.total_usage);
-  if (body?.data?.total_credits == null || body?.data?.total_usage == null) return null;
-  if (!Number.isFinite(credits) || !Number.isFinite(used) || credits < 0 || used < 0) return null;
-  return Math.max(0, credits - used);
-}
-
 export function balanceNow(provider = 'deepseek-official') { return snapshotOf(provider).balance; }
 /** Clock anchored to the last DeepSeek balance response's `Date` header, else the local one. */
 export function trustedNow() {
@@ -43,29 +43,39 @@ export async function refreshBalance(options = {}) {
   const source = SOURCES[provider];
   if (!source) return null;
   const snapshot = snapshotOf(provider);
+  const key = options.key ?? process.env[source.env];
+  const managementKey = options.managementKey ?? (source.managementEnv ? process.env[source.managementEnv] : undefined);
+  const requests = source.requests({ key, managementKey }).filter(request => request.key);
+  const mode = managementKey ? 'management' : 'key';
   const now = Date.now();
-  if (snapshot.pending || now - snapshot.fetchedAt < CACHE_MS) return snapshot.balance;
+  // A newly added (or removed) management key changes the source; it is read at once.
+  if (snapshot.pending || snapshot.mode === mode && now - snapshot.fetchedAt < CACHE_MS) return snapshot.balance;
   const retrySoon = () => Date.now() - (CACHE_MS - RETRY_MS);
-  const key = options.key ?? process.env[source.env];
-  if (!key) { snapshots.set(provider, { ...snapshot, fetchedAt: retrySoon(), pending: false }); return snapshot.balance; }
+  if (requests.length === 0) { snapshots.set(provider, { ...snapshot, mode, fetchedAt: retrySoon(), pending: false }); return snapshot.balance; }
   const fetchImpl = options.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== 'function') return snapshot.balance;
   snapshots.set(provider, { ...snapshot, pending: true });
   try {
-    const response = await fetchImpl(source.url, { headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' } });
+    let response, body, request;
+    for (request of requests) {
+      response = await fetchImpl(request.url, { headers: { Authorization: `Bearer ${request.key}`, Accept: 'application/json' } });
+      body = await response.json();
+      // A key refused this reading falls through to the next source.
+      if (response.ok || (response.status !== 401 && response.status !== 403)) break;
+    }
     const header = source.clock ? response.headers?.get?.('date') : null;
     const anchor = header ? Date.parse(header) : NaN;
-    const body = await response.json();
-    const parsed = response.ok ? source.parse(body) : null;
+    const parsed = response.ok ? request.parse(body) : null;
     if (Number.isFinite(anchor)) clock = { anchor, skewMs: anchor - Date.now() };
     snapshots.set(provider, {
+      mode,
       balance: parsed === null && response.ok ? null : parsed ?? snapshot.balance,
       fetchedAt: parsed === null ? retrySoon() : Date.now(),
       pending: false,
     });
   } catch {
     // A transient failure keeps the last known balance and retries sooner.
-    snapshots.set(provider, { ...snapshot, fetchedAt: retrySoon(), pending: false });
+    snapshots.set(provider, { ...snapshot, mode, fetchedAt: retrySoon(), pending: false });
   }
   return snapshotOf(provider).balance;
 }

package/plugins/session-metrics/index.mjs

@@ -3,7 +3,8 @@ import { appendMetric } from './store.mjs';
 import { estimateCost, priceVersionFor } from './pricing.mjs';
 import { setMetricSource } from './view.mjs';
 import { BALANCE_PROVIDERS, refreshBalance } from './balance.mjs';
-import { refreshOpenRouterPrices } from './openrouter-prices.mjs';
+import { refreshOpenRouterModels } from '../openrouter/models.mjs';
+import { REPLAY_KIND } from '../openrouter/wire.mjs';
 import { providerSpec } from '../providers/catalog.mjs';
 import { createWindowRate } from './rate.mjs';
 import { currentCharge } from './attribution.mjs';
@@ -34,12 +35,17 @@ export function apply(ctx) {
   const credentials = ctx.get?.('credentials');
   const refresh = () => Promise.all(BALANCE_PROVIDERS.map(async provider => {
     try {
-      const ref = providerSpec(provider).credentialRef;
-      const resolved = await credentials?.resolve?.(ref);
-      const key = typeof resolved === 'string' ? resolved : resolved?.value;
-      await refreshBalance({ provider, key: key ?? process.env[ref] });
-      // OpenRouter list prices need no key, but only a session with an OpenRouter key uses them.
-      if (provider === 'openrouter' && (key ?? process.env[ref])) await refreshOpenRouterPrices({ home });
+      const spec = providerSpec(provider);
+      const secret = async ref => {
+        if (!ref) return undefined;
+        const resolved = await credentials?.resolve?.(ref);
+        return (typeof resolved === 'string' ? resolved : resolved?.value) || process.env[ref] || undefined;
+      };
+      // An OpenRouter management key, when stored, turns the balance into the account's credits.
+      const [key, managementKey] = await Promise.all([secret(spec.credentialRef), secret(spec.managementRef)]);
+      await refreshBalance({ provider, key, managementKey });
+      // The listing needs no key, but only a user with an OpenRouter key uses it; the adapter waits for it before its first call.
+      if (provider === 'openrouter' && key) await refreshOpenRouterModels({ home });
     } catch {
       /* balance stays unknown */
     }
@@ -64,19 +70,23 @@ export function apply(ctx) {
     }
     const save = entry => { for (const recipient of recipients) record(recipient, { ...entry, sessionId }); };
     save({ kind: 'start', id, time, provider: options.provider, model: options.model, purpose });
-    let usage, firstTokenTime;
+    let usage, firstTokenTime, billed;
     const liveSession = purpose === 'agent' ? ctx.agents.get(sessionId)?.session : undefined;
     try {
       for await (const chunk of next()) {
         if (chunk.type === 'usage') usage = chunk.usage;
         else if (firstTokenTime === undefined && OUTPUT_CHUNKS.has(chunk.type)) firstTokenTime = Date.now();
+        // OpenRouter reports what it charged; the finish of its response carries it.
+        if (chunk.type === 'finish' && chunk.replayState?.response?.kind === REPLAY_KIND && Number.isFinite(chunk.replayState.response.cost)) billed = chunk.replayState.response.cost;
         if (liveSession) liveRate.add(liveSession, chunk);
         yield chunk;
       }
     } finally {
       if (liveSession) liveRate.calibrate(liveSession, usage?.outputTokens);
       // `time` stays the start (it prices the call); `endTime` and `firstTokenTime` time it.
-      save({ kind: 'end', id, time, endTime: Date.now(), ...(firstTokenTime === undefined ? {} : { firstTokenTime }), usage: usage ?? null, cost: estimateCost(options.provider, options.model, usage, time), priceVersion: priceVersionFor(options.provider, options.model) });
+      save({ kind: 'end', id, time, endTime: Date.now(), ...(firstTokenTime === undefined ? {} : { firstTokenTime }), usage: usage ?? null, ...(billed === undefined
+        ? { cost: estimateCost(options.provider, options.model, usage, time), priceVersion: priceVersionFor(options.provider, options.model) }
+        : { cost: billed, priceVersion: 'openrouter-billed' }) });
     }
   });
 }

package/plugins/session-metrics/pricing.mjs

@@ -1,10 +1,10 @@
-import { openRouterPriceVersion, openRouterRates } from './openrouter-prices.mjs';
+import { openRouterPriceVersion, openRouterRates } from '../openrouter/models.mjs';
 
 // USD per million tokens. Snapshot of the official page opened 2026-09-11.
 // https://api-docs.deepseek.com/quick_start/pricing/
 export const PRICE_SOURCE = 'https://api-docs.deepseek.com/quick_start/pricing/';
 export const PRICE_VERSION = 'deepseek-2026-09-11';
-// OpenRouter calls are priced from its live model listing (openrouter-prices.mjs).
+// OpenRouter calls carry their billed cost; an unbilled one is estimated from the live model listing (plugins/openrouter/models.mjs).
 // Until that table loads, the DeepSeek models keep these list prices from the pinned
 // pi-ai 0.85.1 catalog. OpenRouter bills no peak window. [cache read, input, output].
 export const OPENROUTER_PRICE_VERSION = 'openrouter-pi-ai-0.85.1';
@@ -31,13 +31,33 @@ export function estimateCost(provider, model, usage, time) {
     return OPENROUTER_PRICES[model] ? charge(usage, OPENROUTER_PRICES[model]) : null;
   }
   if (provider !== 'deepseek-official') return null;
+  const rates = deepSeekRates(model, time);
+  if (!rates) return null;
+  const cost = charge(usage, rates);
+  return cost === null ? null : cost * (isPeak(time) ? 2 : 1);
+}
+
+/** DeepSeek list prices [cache read, input, output] at `time`, before the peak multiplier. */
+function deepSeekRates(model, time) {
   // Earlier requests require an older price table; never back-price them at today's rate.
-  if (time < Date.UTC(2026, 8, 11)) return null;
+  if (time < Date.UTC(2026, 8, 11)) return undefined;
   const flash = ['deepseek-flash', 'deepseek-v4-flash', 'deepseek-v4-flash-vision-exp'].includes(model)
     || model === 'deepseek-v4-pro' && time >= Date.UTC(2026, 8, 14, 4);
-  if (!flash && model !== 'deepseek-v4-pro') return null;
-  const cost = charge(usage, flash ? [0.003, 0.15, 0.6] : [0.022, 0.66, 1.98]);
-  return cost === null ? null : cost * (isPeak(time) ? 2 : 1);
+  if (!flash && model !== 'deepseek-v4-pro') return undefined;
+  return flash ? [0.003, 0.15, 0.6] : [0.022, 0.66, 1.98];
+}
+
+/**
+ * Cache-read price over input price for a route, or undefined when the route is unpriced.
+ * A model that lists no cache-read price bills cached input at the input rate (1).
+ */
+export function cacheReadRatio(provider, model, time = Date.now()) {
+  let rates;
+  if (provider === 'openrouter') {
+    const live = openRouterRates(model);
+    rates = live ? [live.cacheRead ?? live.input, live.input] : OPENROUTER_PRICES[model];
+  } else if (provider === 'deepseek-official') rates = deepSeekRates(model, time);
+  return rates && rates[1] > 0 ? rates[0] / rates[1] : undefined;
 }
 
 /** Cost in USD; cache writes need a write price, or the call stays unpriced. */

package/plugins/session-metrics/rate.mjs

@@ -77,9 +77,10 @@ export function sessionAverageTps(events) {
   const starts = new Map();
   let callMs = 0, outputTokens = 0, known = 0, unknown = false;
   for (const event of events) {
-    const key = `${event.data?.turn}:${event.data?.step}`;
-    if (event.type === 'step/start') starts.set(key, event.time);
+    // Build the key only for the two event types that use it: the array carries every event.
+    if (event.type === 'step/start') starts.set(`${event.data?.turn}:${event.data?.step}`, event.time);
     else if (event.type === 'assistant/message') {
+      const key = `${event.data?.turn}:${event.data?.step}`;
       const start = starts.get(key);
       starts.delete(key);
       const output = event.data?.usage?.outputTokens;

package/plugins/session-metrics/store.mjs

@@ -1,7 +1,12 @@
-import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
+// The render path reads this once a second per session; keep the last few ledgers and
+// append to the parsed rows instead of re-reading and re-parsing the whole jsonl.
+const MAX_SESSIONS = 16;
 const cache = new Map();
+const parse = (line, onCorrupt) => { try { return [JSON.parse(line)]; } catch { onCorrupt(); return []; } };
+const readsAsJson = text => { try { JSON.parse(text); return true; } catch { return false; } };
 export const ledgerPath = (home, id) => join(home, 'session-metrics', createHash('sha256').update(id).digest('hex') + '.jsonl');
 export function appendMetric(home, id, entry) {
   const path = ledgerPath(home, id);
@@ -12,13 +17,59 @@ export function readMetrics(home, id) {
   const path = ledgerPath(home, id);
   try {
     const st = statSync(path), key = `${st.mtimeMs}:${st.size}`;
-    if (cache.get(path)?.key === key) return cache.get(path).value;
+    const entry = cache.get(path);
+    if (entry?.key === key) return entry.value;
+    // Touching a key refreshes its recency; the oldest ledger is dropped past the cap.
+    if (entry) cache.delete(path);
     let corrupt = false;
-    const rows = readFileSync(path, 'utf8').split('\n').filter(Boolean).flatMap(line => {
-      try { return [JSON.parse(line)]; } catch { corrupt = true; return []; }
-    });
-    const value = { rows, corrupt };
-    cache.set(path, { key, value });
+    const onCorrupt = () => { corrupt = true; };
+    let value, offset = 0, pending = false;
+    if (entry && st.ino === entry.ino && st.dev === entry.dev && st.size > entry.size) {
+      // Append-only ledger: read just the bytes written since the last read (offset is a newline boundary).
+      const fd = openSync(path, 'r');
+      try {
+        const buffer = Buffer.allocUnsafe(st.size - entry.offset);
+        let filled = 0;
+        while (filled < buffer.length) {
+          const read = readSync(fd, buffer, filled, buffer.length - filled, entry.offset + filled);
+          if (read <= 0) break;
+          filled += read;
+        }
+        // A short read must never read as "the writer stopped here": fall back to the full
+        // parse below rather than caching an offset that would drop the unread bytes forever.
+        if (filled < buffer.length) throw Object.assign(new Error('short ledger read'), { code: 'ESHORTREAD' });
+        const tail = buffer.toString('utf8');
+        const lastNewline = tail.lastIndexOf('\n') + 1;
+        let complete = tail.slice(0, lastNewline);
+        const pendingLine = tail.slice(lastNewline);
+        // A fragment without a newline is either a torn write or a complete row this reader is
+        // simply early for; keep it only when it parses, and re-read it next time either way.
+        pending = pendingLine !== '' && readsAsJson(pendingLine);
+        if (pending) complete += pendingLine + '\n';
+        offset = entry.offset + Buffer.byteLength(tail.slice(0, lastNewline));
+        value = { rows: [...(entry.pending ? entry.value.rows.slice(0, -1) : entry.value.rows), ...complete.split('\n').filter(Boolean).flatMap(line => parse(line, onCorrupt))], corrupt: entry.value.corrupt || corrupt };
+      } finally { closeSync(fd); }
+    } else {
+      const raw = readFileSync(path);
+      const lastNewline = raw.lastIndexOf(0x0a) + 1;
+      let complete = raw.subarray(0, lastNewline);
+      const pendingLine = raw.subarray(lastNewline).toString('utf8');
+      pending = pendingLine !== '' && readsAsJson(pendingLine);
+      if (pending) complete = Buffer.concat([complete, Buffer.from(pendingLine + '\n')]);
+      offset = lastNewline;
+      value = { rows: complete.toString('utf8').split('\n').filter(Boolean).flatMap(line => parse(line, onCorrupt)), corrupt };
+    }
+    cache.set(path, { key, offset, value, pending, size: st.size, ino: st.ino, dev: st.dev });
+    while (cache.size > MAX_SESSIONS) cache.delete(cache.keys().next().value);
     return value;
-  } catch (e) { return { rows: [], corrupt: e.code !== 'ENOENT' }; }
+  } catch (e) {
+    cache.delete(path);
+    if (e.code === 'ESHORTREAD') {
+      // Read it the simple way once; the next call starts from a fresh offset.
+      let corrupt = false;
+      const rows = readFileSync(path, 'utf8').split('\n').filter(Boolean).flatMap(line => parse(line, () => { corrupt = true; }));
+      return { rows, corrupt };
+    }
+    return { rows: [], corrupt: e.code !== 'ENOENT' };
+  }
 }