@byokit/usage 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.6.0 (2026-10-01)
+
+- FIX: Claude subscription quota snapshots can now be read through an identity-free ephemeral host callback without credentials or a fabricated account UUID; readings never enter a cache or shared store, and retry state stays local to the source.
+
+## 0.5.0 (2026-10-01)
+
+- Add a React Native entry for local call/token ledgers and pure quota helpers; subscription and API key (billed per use) attribution is preserved, with estimates only from app prices.
+
 ## 0.4.0 (2026-10-01)
 
 
@@ -9,6 +17,8 @@
 - SECURITY: Claude subscription usage may read credentials only from app-managed folders under the passed stateDir, without refresh or credential writes; default logins and folder escapes are refused, tokens stay in one request and never enter output, errors, logs or stored readings.
 - Share the bounded Codex app-server client between identity and subscription usage reads.
 - Apply shared poll health, scoped quota and hard-limit semantics to managed Claude usage, including cancellable host pacing.
+- Add host lane/route attribution and member-scoped per-run token queries to `callLedger`, sharing existing limits and app-owned cap policy.
+- Accept OpenClaw run usage with separate cache buckets alongside accounts and decide results, without provider calls or logging. Subscription attribution defaults on; API key (billed per use) attribution stays explicit and labelled.
 
 ## 0.3.0 (2026-10-01)
 

package/README.md

@@ -1,6 +1,7 @@
 # @byokit/usage
 
 Read subscription quota windows per provider and per account on Node 22.18 or later.
+React Native also supports local call/token accounting and pure quota parsing.
 The app owns sign-in, token renewal, account labels and selection. The kit reads room
 left, estimates no cost and never rotates an account.
 
@@ -38,6 +39,26 @@ Sources:
   host reader's optional HTTP origin for pacing. It has a ten-second deadline, with the signal
   aborted at expiry. The optional synchronous `connected()` hook controls whether
   last-good readings remain visible; exceptions count as disconnected.
+- `{ provider: 'claude', ephemeral: true, read, connected? }` supports a host-owned
+  opaque snapshot stream without an account UUID, email, folder or token. The same
+  `ClaudeReader` answer and ten-second cancellable deadline apply. For a statusline
+  body, return `{ raw: snapshot, at: snapshot.fetched_at }` when the host knows that
+  `fetched_at` is epoch milliseconds; otherwise omit `at` for unknown age. The kit
+  normalizes `rate_limits` and quota rows; it never opens a snapshot or credential
+  file, discovers credentials, copies tokens or makes a fallback request.
+  `connected()` should reflect the host's sign-in status; false or a thrown error
+  returns `not-connected`. An absent/invalid snapshot returns `incomplete`, while
+  timeout/cancellation returns `unavailable`; the host can report other safe codes.
+  `account()` and `lastKnown()` always return undefined. Successful readings are
+  never retained, so each subsequent read invokes the callback again. Only retry
+  metadata and concurrent operations are weakly held per source object in this
+  reader: reuse an immutable source for one stream, and replace it when the host
+  changes sign-in or stream. Failures never return earlier quota figures.
+  Rate limits honor Retry-After with a five-minute default; transient failures use
+  exponential backoff from one minute, capped at one hour. `backoff.delayMs` may
+  customize these delays with a one-minute minimum. Store and backoff get/set
+  hooks and account-based pacing are never called; the host owns any pacing in
+  its callback. No state is shared between source objects or reader instances.
 
 `read(source, { nowMs?, signal? })` returns `{ provider, windows, at?, limited?, poll?, code? }`.
 `at` is source observation time; it is absent when unavailable. `poll` contains
@@ -242,8 +263,11 @@ or store exception text. Entries are counts only, never sign-in tokens.
 
 `callLedger({ store?, prices? })` records runtime model calls through the same
 `TokenLedgerStore` seam. `record(member, { provider, account, model, runId, time,
-billing, usage?, payer?, durationMs?, state?, limits? })` returns and stores one
-`CallRecord`. `billing` is `subscription` or `api`; `payer` defaults to the member.
+billing?, usage?, usageFormat?, lane?, route?, payer?, durationMs?, state?, limits? })`
+returns and stores one `CallRecord`. `billing` defaults to `subscription`; passing
+`api` explicitly attributes an API key (billed per use) call. Every record carries
+`billingLabel: "Person's own plan" | "Person's API bill"`, even without a price
+estimate. `payer` defaults to the member.
 `state` is `completed` (default), `cancelled` or `failed`. The host records each
 actual model call, including retries, and supplies the provider's final usage when
 available. No missing counts are inferred from words or decision sub-answers.
@@ -278,6 +302,73 @@ calls with unknown total counts, member/day/week results expose `unknownCalls`,
 policy remain the host's. All times, durations and quota reset timestamps are
 milliseconds. There is no transport, credential discovery or automatic rotation.
 
+Record host lanes and routes with optional app-supplied `lane` and `route` fields.
+`runs(member, from, to)` returns a `RunQuery` per run in first-call order;
+`queryRun(member, runId, from, to)` returns one run. Each result contains `runId`,
+time-sorted `calls` (including lane, route, model and limits), aggregate `tokens`,
+`costs` and `unpricedCalls`, using the same `[from, to)` bounds as `query`.
+An absent run returns no calls and zero tokens. A run's totals cover only calls
+inside the requested range; pass the run's full time range for its complete total.
+Retries and multiple routes/models are added under the app's run id. Members remain
+separate even when run ids match. Missing counts stay unknown in run totals, and
+the shared member ledger continues to withhold remaining allowance when needed.
+
+Pass a result with a `usage` field directly, or pass just its usage. For accounts'
+Messages result and decide's reported answer usage, the default provider format
+handles native `input_tokens`/`output_tokens` counts. For OpenClaw `RunEnd`, pass
+`usageFormat: 'openclaw'`: its `input` excludes `cacheRead`/`cacheWrite`, so the kit
+adds those buckets once and preserves reported output and total. Reasoning is
+already part of output and never added again. Missing/inconsistent usage stays
+partial/unknown; engine cost estimates, raw answers and secrets are discarded.
+`normalizeTokens(provider, result, 'openclaw')` exposes the same pure conversion.
+
+```ts
+import { callLedger, memoryTokenLedgerStore, tokenLedger } from '@byokit/usage';
+import type { RunEnd } from '@byokit/openclaw';
+import type { AnthropicResult } from '@byokit/accounts';
+import type { Answer } from '@byokit/decide';
+
+const store = memoryTokenLedgerStore();
+const calls = callLedger({ store });
+// The app supplies its member policy, run identity and selected lane/route/model.
+const limits = tokenLedger({ store, cap: (member) => member === 'member-one' ? 50_000 : undefined });
+const context = {
+  provider: 'anthropic', account: 'non-secret-account-id', model: 'selected-model',
+  lane: 'host', route: 'anthropic-cli', runId: 'run-one',
+};
+declare const end: RunEnd; // Returned by the kit's existing run; no extra request.
+if (end.ok) {
+  calls.record('member-one', { ...context, time: Date.now(), usage: end, usageFormat: 'openclaw' });
+}
+
+declare const answer: Answer;
+// Record once per actual backend invocation, not once per question or cache hit.
+// The host selected this API-billed backend only after the person's opt-in.
+if (answer.source === 'api') {
+  calls.record('member-one', { ...context, route: 'decision', billing: 'api',
+    time: Date.now(), usage: answer });
+}
+declare const messages: AnthropicResult;
+// API key (billed per use); consent and the original request belong to the app.
+calls.record('member-one', { ...context, route: 'anthropic', billing: 'api',
+  time: Date.now(), usage: messages });
+
+declare const runStartedAt: number;
+const run = calls.queryRun('member-one', 'run-one', runStartedAt, Date.now() + 1);
+const history = calls.runs('member-one', runStartedAt, Date.now() + 1);
+const allowance = limits.query('member-one', runStartedAt, Date.now() + 1);
+```
+
+The host records either an OpenClaw aggregate result or its individual calls, never
+both. Decide can attach one invocation's usage to several answers; record it once,
+and skip `source: 'cache'` answers. String-only accounts/answerer results carry no
+counts and remain unknown; the ledger makes no recovery requests. Model, provider,
+lane and route describe the actual execution and are supplied by the app; there is
+no fallback to an API-billed route. Per-run counts stay on device, in memory by
+default. A custom store must keep them on device and apply the app's retention
+policy. The kit never logs counts, sends telemetry or stores the raw result.
+Iteration budgets, stopping rules, consent and presentation belong to the app.
+
 When passing normalized windows to `@byokit/accounts`' structural helper, use
 `roomOf(reading.windows, reading.at, 'milliseconds')`. Its two-argument form is for
 legacy reset seconds; normalized usage windows in 0.2.0+ already use milliseconds.
@@ -287,3 +378,56 @@ that the accounts chooser accepts directly. Preserve the original measurement ti
 `identity(codexSource)` shares the app-server transport, calls `account/read` with a 15-second deadline, never opens a credential file, and returns only `{signedIn,email?,plan?}`. Managed-folder HTTP usage carries only the app-passed headers plus Bearer authorization and JSON accept; it uses the same bounded HTTP transport.
 
 Managed-folder Claude usage uses the shared poll-health and normalized quota pipeline, including scoped hard blocks, unknown usage, last-good observation times, account retry policies and cancellable host origin pacing.
+
+The token and call ledgers accept host-supplied entries/results; they are not
+harness-log or ccusage readers. A bounded incremental log source (including file
+offsets, rotation and bounded work per update) remains outstanding. This snapshot
+source does not implement it or scan real logs.
+
+## React Native
+
+The `react-native` condition of `@byokit/usage` selects a portable entry. The explicit
+`@byokit/usage/react-native` subpath selects the same API when a bundler does not
+use export conditions. It needs no native module, Node shim, credentials or network.
+The default Node entry and browser resolution are unchanged.
+
+```ts
+import { callLedger, tokenLedger, memoryTokenLedgerStore } from '@byokit/usage/react-native';
+const store = memoryTokenLedgerStore(); // Replace with an app-owned synchronous durable store.
+const calls = callLedger({ store });
+const tokens = tokenLedger({ store, cap: 10_000 });
+const time = Date.now();
+calls.record('member-1', {
+  provider: 'openai', account: 'app-account', model: 'app-model', runId: 'run-1',
+  time, billing: 'api', lane: 'host-lane', route: 'host-route',
+  usage: { input_tokens: 12, output_tokens: 8 },
+});
+const daily = tokens.query('member-1', time, time + 1);
+const history = calls.query('member-1', time, time + 1);
+const runs = calls.runs('member-1', time, time + 1);
+const run = calls.queryRun('member-1', 'run-1', time, time + 1);
+```
+
+This entry exports `callLedger`, `tokenLedger`, `memoryTokenLedgerStore`,
+`TokenLedgerError`, `normalizeTokens`, `priceCall`, all quota parsers listed above,
+`codexHardLimit`, `roomOf` and the words helpers, with their corresponding types
+(including `RunQuery`). `callLedger` supports the same `runs`/`queryRun` methods and
+host-supplied lane/route attribution as the Node entry.
+The app supplies provider usage and quota payloads; `usage()`, credential/file
+adapters, `identity()`, fingerprints and disk quota stores remain Node-only.
+
+Counts retain reported/partial/unknown provenance. Missing counts remain unknown;
+unknown calls suppress a positive remaining allowance. Subscription and API key
+(billed per use) calls retain their separate billing attribution. Cost is absent
+unless a matching app-owned price table supplies an estimate, labelled
+“Person's own plan” or “Person's API bill”; no provider prices are invented and a
+subscription quota is never converted into an API charge.
+
+The offline consumer fixture in `test/rn-fixture.ts` exercises the built package's
+React Native export. After building, run
+`BYOKIT_HERMES=/absolute/path/to/hermes sh scripts/test.sh 'packages/usage/test/react-native.test.ts'`
+from the repository root to execute it in a Hermes CLI VM. Without that optional
+binary, the same contract runs in a sandbox without Node globals; the Hermes check
+is skipped. The standalone fixture uses the locked Expo Babel preset's `hermes-v0`
+profile to lower classes for legacy Hermes CLI VMs. This is VM qualification, not
+an Expo SDK runtime, emulator or native UI test.

package/dist/calls.d.ts

@@ -31,8 +31,14 @@ export interface CallInput {
     account: string;
     model: string;
     runId: string;
+    /** App-selected host lane and runtime route; never inferred from a model id. */
+    lane?: string;
+    route?: string;
     time: number;
-    billing: 'subscription' | 'api';
+    /** Subscription by default; API key (billed per use) attribution is explicit. */
+    billing?: 'subscription' | 'api';
+    /** OpenClaw reports input separately from cache reads/writes. */
+    usageFormat?: 'provider' | 'openclaw';
     /** Native provider usage/envelope, or normalized input/output/cachedInput/cacheWrite/total counts. */
     usage?: unknown;
     payer?: string;
@@ -40,7 +46,9 @@ export interface CallInput {
     state?: 'completed' | 'cancelled' | 'failed';
     limits?: readonly Window[];
 }
-export interface CallRecord extends Omit<CallInput, 'usage' | 'limits'> {
+export interface CallRecord extends Omit<CallInput, 'usage' | 'limits' | 'billing' | 'usageFormat'> {
+    billing: 'subscription' | 'api';
+    billingLabel: "Person's own plan" | "Person's API bill";
     tokens: NormalizedTokens;
     state: 'completed' | 'cancelled' | 'failed';
     cost?: CallCost;
@@ -56,9 +64,16 @@ export interface CallQuery {
 export interface CallLedger {
     record(member: string, call: CallInput): CallRecord;
     query(member: string, from: number, to: number): CallQuery;
+    /** All runs with recorded calls in [from, to), in first-call order. */
+    runs(member: string, from: number, to: number): RunQuery[];
+    /** One member's run, restricted to [from, to). Empty runs have zero totals. */
+    queryRun(member: string, runId: string, from: number, to: number): RunQuery;
+}
+export interface RunQuery extends CallQuery {
+    runId: string;
 }
 /** Pure normalization of reported counts, never estimates from text or shared decision invocations. */
-export declare function normalizeTokens(provider: string, raw: unknown): NormalizedTokens;
+export declare function normalizeTokens(provider: string, raw: unknown, format?: 'provider' | 'openclaw'): NormalizedTokens;
 /** App-supplied price estimates only, including explicit billing attribution. */
 export declare function priceCall(tokens: NormalizedTokens, price: ModelPrice | undefined, billing: ModelPrice['billing']): CallCost | undefined;
 /** Every recorded attempt is a call; the host records retries separately under its run id. */

package/dist/calls.js

@@ -1,6 +1,6 @@
 import { record as isRecord } from "./windows.js";
 import { memoryTokenLedgerStore, TokenLedgerError } from "./ledger.js";
-import { safeWindows } from "./store.js";
+import { safeWindows } from "./safe-windows.js";
 const object = (value) => isRecord(value) ? value : {};
 const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
 const text = (value) => typeof value === 'string' && !!value && value.length <= 1024 && !/[\0\r\n]/.test(value);
@@ -20,11 +20,20 @@ function normalized(input, output, cachedInput, cacheWrite, total) {
         provenance: input !== undefined && output !== undefined && derived !== undefined ? 'reported' : [input, output, cachedInput, cacheWrite, measured].some((v) => v !== undefined) ? 'partial' : 'unknown' };
 }
 /** Pure normalization of reported counts, never estimates from text or shared decision invocations. */
-export function normalizeTokens(provider, raw) {
+export function normalizeTokens(provider, raw, format = 'provider') {
     const envelope = object(raw);
     const usage = object(envelope.usage ?? envelope.usageMetadata ?? raw);
     if (usage.provenance === 'unknown' || usage.provenance === 'estimated')
         return { provenance: 'unknown' };
+    if (format === 'openclaw') {
+        if (!['input', 'output', 'cacheRead', 'cacheWrite', 'total'].some((key) => count(usage[key]) !== undefined))
+            return { provenance: 'unknown' };
+        const uncached = count(usage.input);
+        const cached = count(usage.cacheRead) ?? (usage.cacheRead === undefined ? 0 : undefined);
+        const written = count(usage.cacheWrite) ?? (usage.cacheWrite === undefined ? 0 : undefined);
+        const input = uncached !== undefined && cached !== undefined && written !== undefined ? sum(uncached, cached, written) : undefined;
+        return normalized(input, count(usage.output), cached, written, count(usage.total));
+    }
     if (['input', 'output', 'total'].some((key) => key in usage))
         return normalized(count(usage.input), count(usage.output), count(usage.cachedInput), count(usage.cacheWrite), count(usage.total));
     if (provider === 'claude' || provider === 'anthropic') {
@@ -76,21 +85,37 @@ function aggregate(calls) {
     const field = (key) => calls.every((call) => call.tokens[key] !== undefined) ? count(calls.reduce((total, call) => total + call.tokens[key], 0)) : undefined;
     return normalized(field('input'), field('output'), field('cachedInput'), field('cacheWrite'), field('total'));
 }
+function summarize(calls) {
+    const costs = new Map();
+    for (const call of calls) {
+        if (!call.cost)
+            continue;
+        const key = `${call.cost.currency}\0${call.cost.billing}`;
+        const previous = costs.get(key);
+        costs.set(key, { ...call.cost, amount: (previous?.amount ?? 0) + call.cost.amount });
+    }
+    return { calls, tokens: aggregate(calls), costs: [...costs.values()], unpricedCalls: calls.filter((call) => !call.cost).length };
+}
 /** Every recorded attempt is a call; the host records retries separately under its run id. */
 export function callLedger(options = {}) {
     const store = options.store ?? memoryTokenLedgerStore();
-    return {
+    const ledger = {
         record(member, call) {
             if (!text(member) || !call || ![call.provider, call.account, call.model, call.runId].every(text) || !time(call.time)
-                || !['subscription', 'api'].includes(call.billing) || call.payer !== undefined && !text(call.payer)
+                || call.billing !== undefined && !['subscription', 'api'].includes(call.billing) || call.payer !== undefined && !text(call.payer)
+                || call.lane !== undefined && !text(call.lane) || call.route !== undefined && !text(call.route)
+                || call.usageFormat !== undefined && !['provider', 'openclaw'].includes(call.usageFormat)
                 || call.durationMs !== undefined && (typeof call.durationMs !== 'number' || !Number.isFinite(call.durationMs) || call.durationMs < 0)
                 || call.state !== undefined && !['completed', 'cancelled', 'failed'].includes(call.state) || call.limits !== undefined && !Array.isArray(call.limits))
                 throw new TokenLedgerError('invalid');
-            const tokens = normalizeTokens(call.provider, call.usage);
-            const cost = priceCall(tokens, options.prices?.[call.provider]?.[call.model], call.billing);
+            const billing = call.billing ?? 'subscription';
+            const tokens = normalizeTokens(call.provider, call.usage, call.usageFormat);
+            const cost = priceCall(tokens, options.prices?.[call.provider]?.[call.model], billing);
             const limits = call.limits?.flatMap((window) => safeWindows(window.provider, [window]));
             const result = { provider: call.provider, account: call.account, model: call.model, runId: call.runId, time: call.time,
-                billing: call.billing, payer: call.payer ?? member, state: call.state ?? 'completed', tokens,
+                billing, billingLabel: billing === 'subscription' ? "Person's own plan" : "Person's API bill",
+                payer: call.payer ?? member, state: call.state ?? 'completed', tokens,
+                ...(call.lane === undefined ? {} : { lane: call.lane }), ...(call.route === undefined ? {} : { route: call.route }),
                 ...(call.durationMs === undefined ? {} : { durationMs: call.durationMs }), ...(cost ? { cost } : {}), ...(limits ? { limits } : {}) };
             try {
                 store.record(member, { time: call.time, tokens: tokens.total ?? 0, call: copyCall(result) });
@@ -113,19 +138,27 @@ export function callLedger(options = {}) {
             if (!Array.isArray(entries))
                 throw new TokenLedgerError('invalid');
             const calls = entries.filter((entry) => entry.call && entry.time >= from && entry.time < to).map((entry) => copyCall(entry.call)).sort((a, b) => a.time - b.time);
-            const costs = new Map();
-            for (const call of calls) {
-                if (!call.cost)
-                    continue;
-                const key = `${call.cost.currency}\0${call.cost.billing}`;
-                const previous = costs.get(key);
-                costs.set(key, { ...call.cost, amount: (previous?.amount ?? 0) + call.cost.amount });
+            return summarize(calls);
+        },
+        runs(member, from, to) {
+            const groups = new Map();
+            for (const call of ledger.query(member, from, to).calls) {
+                const calls = groups.get(call.runId) ?? [];
+                calls.push(call);
+                groups.set(call.runId, calls);
             }
-            return { calls, tokens: aggregate(calls), costs: [...costs.values()], unpricedCalls: calls.filter((call) => !call.cost).length };
+            return [...groups].map(([runId, calls]) => ({ runId, ...summarize(calls) }));
+        },
+        queryRun(member, runId, from, to) {
+            if (!text(runId))
+                throw new TokenLedgerError('invalid');
+            return { runId, ...summarize(ledger.query(member, from, to).calls.filter((call) => call.runId === runId)) };
         },
     };
+    return ledger;
 }
 function copyCall(call) {
-    return { ...call, tokens: { ...call.tokens }, ...(call.cost ? { cost: { ...call.cost } } : {}),
+    return { ...call, billingLabel: call.billing === 'subscription' ? "Person's own plan" : "Person's API bill",
+        tokens: { ...call.tokens }, ...(call.cost ? { cost: { ...call.cost } } : {}),
         ...(call.limits ? { limits: call.limits.map((window) => ({ ...window })) } : {}) };
 }

package/dist/ephemeral.d.ts

@@ -0,0 +1,3 @@
+import type { EphemeralClaudeSource, Reading, ReadOptions, UsageOptions } from './types.ts';
+/** Only retry/concurrency metadata survives a call; source objects are weakly held. */
+export declare function ephemeralClaude(options: UsageOptions): (source: EphemeralClaudeSource, clock: number, opts?: ReadOptions) => Promise<Reading>;

package/dist/ephemeral.js

@@ -0,0 +1,64 @@
+import { customClaude } from "./providers.js";
+import { safeWindows } from "./safe-windows.js";
+import { claudeWindows } from "./windows.js";
+/** Only retry/concurrency metadata survives a call; source objects are weakly held. */
+export function ephemeralClaude(options) {
+    const states = new WeakMap();
+    return async (source, clock, opts) => {
+        const empty = (poll) => ({ provider: 'claude', windows: [], code: poll.outcome === 'ok' ? 'unavailable' : poll.outcome, poll });
+        let connected = true;
+        try {
+            connected = source.connected?.() ?? true;
+        }
+        catch {
+            connected = false;
+        }
+        if (!connected) {
+            states.delete(source);
+            return empty({ at: clock, outcome: 'not-connected' });
+        }
+        let state = states.get(source);
+        if (!state) {
+            state = { failures: 0 };
+            states.set(source, state);
+        }
+        if (state.pending)
+            return state.pending;
+        if (state.poll?.retryAt !== undefined && clock < state.poll.retryAt)
+            return empty(state.poll);
+        const current = state;
+        const task = (async () => {
+            const answer = await customClaude(source, clock, { signal: opts?.signal });
+            const rows = safeWindows('claude', claudeWindows(answer.raw));
+            const limited = !answer.code && answer.limited === true;
+            const code = answer.code ?? (!rows.length && !limited ? 'incomplete' : undefined);
+            const poll = { at: clock, outcome: code ?? 'ok' };
+            if (code && ['rate-limited', 'refresh-failed', 'unavailable', 'incomplete'].includes(code)) {
+                current.failures = current.poll?.outcome === code ? current.failures + 1 : 1;
+                const retry = typeof answer.retryAfterMs === 'number' && Number.isFinite(answer.retryAfterMs) && answer.retryAfterMs >= 0 ? answer.retryAfterMs : undefined;
+                let delay = code === 'rate-limited' ? 300_000 : Math.min(3_600_000, 60_000 * 2 ** Math.min(current.failures - 1, 6));
+                try {
+                    const selected = options.backoff?.delayMs?.(retry, { outcome: code, failures: current.failures });
+                    if (selected !== undefined && Number.isFinite(selected) && selected >= 0)
+                        delay = selected;
+                }
+                catch { /* internal retry policy stands */ }
+                poll.retryAt = clock + Math.max(60_000, delay, retry ?? 0);
+            }
+            else
+                current.failures = 0;
+            current.poll = poll;
+            if (code)
+                return empty(poll);
+            const at = typeof answer.at === 'number' && Number.isFinite(answer.at) ? answer.at : undefined;
+            return { provider: 'claude', windows: rows, ...(at !== undefined ? { at } : {}), ...(limited ? { limited: true } : {}), poll };
+        })();
+        current.pending = task;
+        try {
+            return await task;
+        }
+        finally {
+            current.pending = undefined;
+        }
+    };
+}

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { Identity } from './identity.ts';
 export declare function identity(source: Extract<Source, {
     bin: string;
 }>): Promise<Identity>;
-export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
+export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type RunQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
 export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError, type TokenLedger, type TokenLedgerStore, type TokenLedgerOptions, type TokenEntry, type TokenQuery } from './ledger.ts';
 export { roomOf } from './room.ts';
 export { fingerprint, store as fileUsageStore, memoryUsageStore } from './store.ts';

package/dist/index.js

@@ -8,6 +8,7 @@ import { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimax
 import { UsageError } from "./types.js";
 import { codexIdentity } from "./identity.js";
 import { claudeUsage as managedClaudeUsage, claudeCredential, managedClaudeFolder } from "./claude.js";
+import { ephemeralClaude } from "./ephemeral.js";
 export * from "./types.js";
 /** Identity runs only the named binary, never opens a credential file. */
 export async function identity(source) {
@@ -29,6 +30,8 @@ const validText = (v) => typeof v === 'string' && !v.includes('\0') && !/[\r\n]/
 function validate(source, stateDir) {
     if (!record(source) || !providers.includes(source.provider))
         throw new UsageError();
+    if ('ephemeral' in source && (source.ephemeral !== true || source.provider !== 'claude' || typeof source.read !== 'function' || ['accountUuid', 'accountId', 'origin', 'folder', 'credentialsFile', 'access', 'key', 'bin', 'home', 'configFile', 'statuslineFile'].some((field) => field in source)))
+        throw new UsageError();
     if ('folder' in source) {
         if (source.provider !== 'claude' || !validText(source.folder) || !isAbsolute(source.folder) || !stateDir || !managedClaudeFolder(source.folder, stateDir))
             throw new UsageError();
@@ -40,7 +43,7 @@ function validate(source, stateDir) {
             throw new UsageError();
     }
     else if ('read' in source) {
-        if (source.provider !== 'claude' || typeof source.read !== 'function' || !validText(source.accountUuid) || !source.accountUuid || source.connected !== undefined && typeof source.connected !== 'function')
+        if (source.provider !== 'claude' || typeof source.read !== 'function' || !('ephemeral' in source) && (!validText(source.accountUuid) || !source.accountUuid) || source.connected !== undefined && typeof source.connected !== 'function')
             throw new UsageError();
     }
     else if ('bin' in source) {
@@ -98,6 +101,7 @@ export function usage(options) {
     const attempts = new Map();
     const failures = new Map();
     const now = (opts) => opts?.nowMs ?? (options.now ?? Date.now)();
+    const readEphemeral = ephemeralClaude(options);
     function connected(source) {
         validate(source, options.stateDir);
         if ('folder' in source)
@@ -133,7 +137,7 @@ export function usage(options) {
         else if ('credentialsFile' in source)
             id = claudeAuth(source)?.account;
         else if ('read' in source)
-            id = source.accountUuid;
+            id = 'ephemeral' in source ? undefined : source.accountUuid;
         else if ('bin' in source) {
             const raw = readJson(join(source.home, 'auth.json'), 64 * 1024);
             const tokens = record(raw) && record(raw.tokens) ? raw.tokens : undefined;
@@ -165,6 +169,9 @@ export function usage(options) {
         }
     }
     function lastKnown(source, opts) {
+        validate(source, options.stateDir);
+        if ('ephemeral' in source)
+            return undefined;
         if (!connected(source))
             return undefined;
         const id = identity(source);
@@ -187,6 +194,8 @@ export function usage(options) {
     async function read(source, opts) {
         validate(source, options.stateDir);
         const clock = now(opts);
+        if ('ephemeral' in source)
+            return readEphemeral(source, clock, opts);
         const empty = (code) => ({ provider: source.provider, windows: [], code, poll: { at: clock, outcome: code ?? 'unavailable' } });
         if (!connected(source))
             return empty('not-connected');

package/dist/providers.d.ts

@@ -26,7 +26,7 @@ export declare function customClaude(source: Extract<Source, {
     read: unknown;
 }>, nowMs: number, pacing?: {
     hook?: PacingHook;
-    account: string;
+    account?: string;
     signal?: AbortSignal;
 }): Promise<Answer>;
 export declare function codexUsage(source: Extract<Source, {

package/dist/providers.js

@@ -114,7 +114,7 @@ export async function customClaude(source, nowMs, pacing) {
     const timer = setTimeout(abort, 10_000);
     try {
         const operation = async () => {
-            if (source.origin && pacing?.hook)
+            if ('origin' in source && source.origin && pacing?.hook && pacing.account !== undefined)
                 await pacing.hook({ provider: source.provider, account: pacing.account, origin: source.origin, signal: controller.signal });
             if (controller.signal.aborted)
                 return { code: 'unavailable' };

package/dist/rn.d.ts

@@ -0,0 +1,8 @@
+/** Local usage accounting and host-supplied quota parsing; no credential or network access. */
+export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type RunQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
+export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError, type TokenLedger, type TokenLedgerStore, type TokenLedgerOptions, type TokenEntry, type TokenQuery } from './ledger.ts';
+export { roomOf } from './room.ts';
+export { claudeWindows, codexWindows, goWindows, zaiWindows, type CodexRateLimitResult } from './windows.ts';
+export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from './quota.ts';
+export type { Provider, Kind, Window, Scope, Poll, Freshness, Code, Reading, Room } from './types.ts';
+export { WORDS, words, usageWords, type WordKey } from './words.ts';

package/dist/rn.js

@@ -0,0 +1,7 @@
+/** Local usage accounting and host-supplied quota parsing; no credential or network access. */
+export { callLedger, normalizeTokens, priceCall } from "./calls.js";
+export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError } from "./ledger.js";
+export { roomOf } from "./room.js";
+export { claudeWindows, codexWindows, goWindows, zaiWindows } from "./windows.js";
+export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
+export { WORDS, words, usageWords } from "./words.js";

package/dist/safe-windows.d.ts

@@ -0,0 +1,3 @@
+import type { Provider, Window } from './types.ts';
+/** Public stores receive only these quota fields, never raw provider payloads. */
+export declare function safeWindows(provider: Provider, raw: unknown): Window[];

package/dist/safe-windows.js

@@ -0,0 +1,14 @@
+import { record, quotaScope } from "./windows.js";
+/** Public stores receive only these quota fields, never raw provider payloads. */
+export function safeWindows(provider, raw) {
+    return (Array.isArray(raw) ? raw : []).slice(0, 64).flatMap((value) => {
+        if (!record(value) || !['session', 'weekly', 'monthly', 'rolling', 'custom'].includes(String(value.kind)) || value.usedPercent !== undefined && (typeof value.usedPercent !== 'number' || !Number.isFinite(value.usedPercent)))
+            return [];
+        return [{ provider, kind: value.kind, ...(typeof value.usedPercent === 'number' ? { usedPercent: Math.max(0, Math.min(100, value.usedPercent)) } : {}),
+                ...(quotaScope(value.scope) ? { scope: quotaScope(value.scope) } : {}),
+                ...(typeof value.minutes === 'number' && Number.isFinite(value.minutes) && value.minutes > 0 ? { minutes: value.minutes } : {}),
+                ...(typeof value.resetsAt === 'number' && Number.isFinite(value.resetsAt) ? { resetsAt: value.resetsAt } : {}),
+                ...(value.limited === true ? { limited: true } : {}),
+                ...(typeof value.limit === 'string' && value.limit.length <= 80 ? { limit: value.limit } : {}) }];
+    });
+}

package/dist/store.d.ts

@@ -1,4 +1,5 @@
-import type { Provider, StoredReading, UsageStore, Window, Poll } from './types.ts';
+import type { Provider, StoredReading, UsageStore, Poll } from './types.ts';
+export { safeWindows } from './safe-windows.ts';
 export type Stored = StoredReading;
 /** Bounded regular files only; do not follow credential or state symlinks. */
 export declare function readJsonSnapshot(file: string, cap: number): {
@@ -10,6 +11,4 @@ export declare function fingerprint(salt: string): (provider: Provider, value: s
 /** Poll metadata is distinct from the observation timestamp. */
 export declare function safePoll(raw: unknown): Poll | undefined;
 export declare function store(stateDir: string): UsageStore;
-/** Public stores receive only these quota fields, never raw provider payloads. */
-export declare function safeWindows(provider: Provider, raw: unknown): Window[];
 export declare function memoryUsageStore(): UsageStore;

package/dist/store.js

@@ -2,7 +2,9 @@ import { createHash, randomUUID, scryptSync } from 'node:crypto';
 import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, constants } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { UsageError } from "./types.js";
-import { record, quotaScope } from "./windows.js";
+import { record } from "./windows.js";
+import { safeWindows } from "./safe-windows.js";
+export { safeWindows } from "./safe-windows.js";
 /** Bounded regular files only; do not follow credential or state symlinks. */
 export function readJsonSnapshot(file, cap) {
     let fd;
@@ -103,19 +105,6 @@ export function store(stateDir) {
         },
     };
 }
-/** Public stores receive only these quota fields, never raw provider payloads. */
-export function safeWindows(provider, raw) {
-    return (Array.isArray(raw) ? raw : []).slice(0, 64).flatMap((value) => {
-        if (!record(value) || !['session', 'weekly', 'monthly', 'rolling', 'custom'].includes(String(value.kind)) || value.usedPercent !== undefined && (typeof value.usedPercent !== 'number' || !Number.isFinite(value.usedPercent)))
-            return [];
-        return [{ provider, kind: value.kind, ...(typeof value.usedPercent === 'number' ? { usedPercent: Math.max(0, Math.min(100, value.usedPercent)) } : {}),
-                ...(quotaScope(value.scope) ? { scope: quotaScope(value.scope) } : {}),
-                ...(typeof value.minutes === 'number' && Number.isFinite(value.minutes) && value.minutes > 0 ? { minutes: value.minutes } : {}),
-                ...(typeof value.resetsAt === 'number' && Number.isFinite(value.resetsAt) ? { resetsAt: value.resetsAt } : {}),
-                ...(value.limited === true ? { limited: true } : {}),
-                ...(typeof value.limit === 'string' && value.limit.length <= 80 ? { limit: value.limit } : {}) }];
-    });
-}
 export function memoryUsageStore() {
     const readings = new Map();
     return { get: (provider, account) => { const r = readings.get(`${provider}\0${account}`); return r ? { at: r.at, windows: safeWindows(provider, r.windows), ...(r.limited ? { limited: true } : {}), ...(safePoll(r.poll) ? { poll: safePoll(r.poll) } : {}) } : undefined; },

package/dist/types.d.ts

@@ -29,7 +29,7 @@ export type Source = {
     read: ClaudeReader;
     origin?: string;
     connected?: () => boolean;
-}) | {
+}) | EphemeralClaudeSource | {
     provider: 'claude';
     credentialsFile: string;
     configFile?: string;
@@ -106,6 +106,13 @@ export type ClaudeReader = (options: {
     nowMs: number;
     signal: AbortSignal;
 }) => Promise<SourceAnswer>;
+/** Reuse one source object per host-owned snapshot stream; no identity or last-good cache. */
+export type EphemeralClaudeSource = {
+    provider: 'claude';
+    ephemeral: true;
+    read: ClaudeReader;
+    connected?: () => boolean;
+};
 export type StoredReading = {
     at?: number;
     windows: Window[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/usage",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Read subscription usage windows per provider and account.",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,12 +14,20 @@
   },
   "exports": {
     ".": {
+      "react-native": {
+        "types": "./dist/rn.d.ts",
+        "default": "./dist/rn.js"
+      },
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
+    },
+    "./react-native": {
+      "types": "./dist/rn.d.ts",
+      "default": "./dist/rn.js"
     }
   },
   "files": [