@byokit/usage 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 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)
+
+
+
+- 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.
 
@@ -47,6 +48,18 @@ original observation time. Poll 429 (`rate-limited`), host renewal failure
 (`refresh-failed`) and credential refusals are distinct; usage never changes
 account health or renews credentials.
 
+The managed-folder source is `{ provider: 'claude', folder, headers: { 'anthropic-beta', 'User-Agent' } }`. Paths must be absolute; removed or empty keys mean disconnected. Claude headers are app-passed. The Claude folder must resolve inside the reader's `stateDir` as `<stateDir>/claude/<hex>`, matching managed CLI account folders. Default `.claude` roots, paths outside the root, and symlinked folders or credential files are refused. Use the managed plans root as the usage reader's stateDir; its quota store coexists with the account roster. The default login's usage adapter remains with the host.
+
+Approved exception: the `./cli` entry reads and runs only app-managed per-account folders under `stateDir` and the absolute CLI binaries the app passes; it never touches the person's default login; tokens never leave the device and are never logged. Under the same managed-folder boundary, usage may read `.credentials.json` only for a single Claude subscription usage request. It does not refresh, write, rename or copy credentials; expired or malformed credentials return `expired` or `not-connected`, requiring sign-in again. The token is held in memory only for that request and never enters readings, stored quotas, errors or logs. Folder and credential metadata supply the cache fingerprint without loading a token, and credential changes invalidate the cached account reading.
+
+`read(source, { nowMs? })` returns `{ provider, windows, at, code? }`; `at` and all
+`resetsAt` fields are **epoch milliseconds** in 0.2.0. This changes 0.1.0's seconds
+reset convention. Windows include kind, used percent, optional duration in minutes,
+reset time, limit label and limited flag. Parsers are exported for host integrations:
+`claudeWindows`, `codexWindows` (app-server), `codexTokenWindows`, `goWindows`,
+`zaiWindows`, `copilotWindows`, `grokWindows`, `minimaxWindows`, `geminiWindows`,
+`kimiWindows(raw, nowMs)`.
+
 Windows include kind, optional reported `usedPercent`, duration, reset, limit,
 `limited` and `scope: { model?, surface? }`. Missing usage is unknown, never zero.
 Claude `limits[]` session/weekly-all rows override corresponding legacy aggregates,
@@ -197,6 +210,8 @@ and HOME explicitly when needed. No tokens in logs, errors, readings or public h
 no credential write-back, telemetry, automatic refresh or reset-credit spend.
 
 Built-in requests send `User-Agent: byokit/usage/0.3.0`, never another app's identity.
+
+Token and explicit-file sources send `User-Agent: byokit/usage/0.2.0`, never another app's identity.
 A refusal returns a code; with no last-good quota, room is unknown. Fixed endpoints
 are Anthropic `api/oauth/usage`, ChatGPT `backend-api/wham/usage`, GitHub
 `copilot_internal/user`, Grok `v1/billing` (weekly credits then monthly when needed),
@@ -228,8 +243,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.
@@ -264,8 +282,127 @@ 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.
 Alternatively, this package's `roomOf(reading, nowMs)` returns a structural `Room`
 that the accounts chooser accepts directly. Preserve the original measurement time.
+
+`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.
+
+## 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/claude.d.ts

@@ -0,0 +1,12 @@
+import { providerHttp, type Answer } from './providers.ts';
+import type { Source } from './types.ts';
+type ClaudeSource = Extract<Source, {
+    folder: string;
+}>;
+/** No ambient HOME discovery. Both the lexical and real folder must be managed by this root. */
+export declare function managedClaudeFolder(folder: string, stateDir: string): boolean;
+/** Metadata only, so account/cache probes never load a token. */
+export declare function claudeCredential(folder: string): import("fs").Stats | undefined;
+/** The credential is held only for this request; no refresh, writes or recovery sidecars. */
+export declare function claudeUsage(source: ClaudeSource, fetcher: typeof fetch, nowMs: number, pacing?: Parameters<typeof providerHttp>[5]): Promise<Answer>;
+export {};

package/dist/claude.js

@@ -0,0 +1,47 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { readJson } from "./store.js";
+import { record } from "./windows.js";
+import { providerHttp } from "./providers.js";
+/** No ambient HOME discovery. Both the lexical and real folder must be managed by this root. */
+export function managedClaudeFolder(folder, stateDir) {
+    const root = resolve(stateDir);
+    const candidate = resolve(folder);
+    if (root.split(sep).some((part) => ['.claude', '.codex', '.pi'].includes(part)))
+        return false;
+    const parent = join(root, 'claude');
+    if (!candidate.startsWith(parent + sep) || !/^[a-f0-9]+$/.test(candidate.slice(parent.length + 1)))
+        return false;
+    try {
+        if (![root, parent, candidate].every((path) => { const s = lstatSync(path); return s.isDirectory() && !s.isSymbolicLink(); }))
+            return false;
+        const realRoot = realpathSync(root);
+        if (realRoot.split(sep).some((part) => ['.claude', '.codex', '.pi'].includes(part)))
+            return false;
+        const realFolder = realpathSync(candidate);
+        return realFolder.startsWith(join(realRoot, 'claude') + sep);
+    }
+    catch {
+        return false;
+    }
+}
+/** Metadata only, so account/cache probes never load a token. */
+export function claudeCredential(folder) {
+    try {
+        const stat = lstatSync(join(folder, '.credentials.json'));
+        return stat.isFile() && !stat.isSymbolicLink() && stat.size <= 64 * 1024 ? stat : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The credential is held only for this request; no refresh, writes or recovery sidecars. */
+export async function claudeUsage(source, fetcher, nowMs, pacing) {
+    const raw = readJson(join(source.folder, '.credentials.json'), 64 * 1024);
+    const oauth = record(raw) && record(raw.claudeAiOauth) ? raw.claudeAiOauth : undefined;
+    if (!oauth || typeof oauth.accessToken !== 'string' || !oauth.accessToken.trim() || oauth.accessToken.length > 16384 || /[\x00-\x20\x7f]/.test(oauth.accessToken))
+        return { code: 'not-connected' };
+    if (typeof oauth.expiresAt !== 'number' || !Number.isFinite(oauth.expiresAt) || oauth.expiresAt <= nowMs)
+        return { code: 'expired' };
+    return providerHttp('https://api.anthropic.com/api/oauth/usage', oauth.accessToken, fetcher, nowMs, { headers: { 'anthropic-beta': source.headers['anthropic-beta'], 'User-Agent': source.headers['User-Agent'] } }, pacing);
+}

package/dist/identity.d.ts

@@ -0,0 +1,11 @@
+import type { Source } from './types.ts';
+export type Identity = {
+    signedIn: boolean;
+    email?: string;
+    plan?: string;
+};
+/** Explicit identity fields only: never walk arbitrary token-bearing objects. */
+export declare function publicIdentity(raw: unknown, signedIn: boolean): Identity;
+export declare function codexIdentity(source: Extract<Source, {
+    bin: string;
+}>): Promise<Identity>;

package/dist/identity.js

@@ -0,0 +1,16 @@
+import { codexRequest } from "./providers.js";
+import { record } from "./windows.js";
+/** Explicit identity fields only: never walk arbitrary token-bearing objects. */
+export function publicIdentity(raw, signedIn) {
+    if (!signedIn || !record(raw))
+        return { signedIn: false };
+    const short = (value) => typeof value === 'string' && value.length > 0 && value.length <= 320 && !/[\x00-\x1f\x7f]/.test(value);
+    const email = short(raw.email) && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw.email) ? raw.email : undefined;
+    const plan = [raw.planType, raw.subscriptionType, raw.plan, raw.tier, raw.planName].find((value) => short(value) && /^[a-zA-Z][a-zA-Z0-9 _+-]{0,63}$/.test(value));
+    return { signedIn: true, ...(email === undefined ? {} : { email }), ...(typeof plan === 'string' ? { plan } : {}) };
+}
+export async function codexIdentity(source) {
+    const answer = await codexRequest(source, 'account/read');
+    const account = record(answer.raw) ? answer.raw.account : undefined;
+    return publicIdentity(account, record(account));
+}

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-import { type Usage, type UsageOptions } from './types.ts';
+import { type Source, type Usage, type UsageOptions } from './types.ts';
+import { type Identity } from './identity.ts';
 export * from './types.ts';
-export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
+export type { Identity } from './identity.ts';
+/** Identity runs only the named binary, never opens a credential file. */
+export declare function identity(source: Extract<Source, {
+    bin: string;
+}>): Promise<Identity>;
+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

@@ -6,7 +6,16 @@ import { fingerprint, readJson, store, memoryUsageStore, safeWindows, safePoll }
 import { claudeWindows, codexWindows, goWindows, record, zaiWindows } from "./windows.js";
 import { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
 import { UsageError } from "./types.js";
+import { codexIdentity } from "./identity.js";
+import { claudeUsage as managedClaudeUsage, claudeCredential, managedClaudeFolder } from "./claude.js";
 export * from "./types.js";
+/** Identity runs only the named binary, never opens a credential file. */
+export async function identity(source) {
+    if (!record(source) || !('bin' in source) || 'folder' in source || 'credentialsFile' in source || 'read' in source)
+        throw new UsageError();
+    validate(source);
+    return codexIdentity(source);
+}
 export { callLedger, normalizeTokens, priceCall } from "./calls.js";
 export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError } from "./ledger.js";
 export { roomOf } from "./room.js";
@@ -17,10 +26,16 @@ export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimax
 export { WORDS, words, usageWords } from "./words.js";
 const providers = ['claude', 'codex', 'opencode', 'zai', 'copilot', 'grok', 'minimax', 'gemini', 'kimi'];
 const validText = (v) => typeof v === 'string' && !v.includes('\0') && !/[\r\n]/.test(v) && v.length <= 16384;
-function validate(source) {
+function validate(source, stateDir) {
     if (!record(source) || !providers.includes(source.provider))
         throw new UsageError();
-    if ('credentialsFile' in source) {
+    if ('folder' in source) {
+        if (source.provider !== 'claude' || !validText(source.folder) || !isAbsolute(source.folder) || !stateDir || !managedClaudeFolder(source.folder, stateDir))
+            throw new UsageError();
+        if (!record(source.headers) || !['anthropic-beta', 'User-Agent'].every((key) => validText(source.headers[key]) && source.headers[key].length <= 1024))
+            throw new UsageError();
+    }
+    else if ('credentialsFile' in source) {
         if (source.provider !== 'claude' || ![source.credentialsFile, ...[source.configFile, source.statuslineFile].filter((v) => v !== undefined)].every((v) => validText(v) && isAbsolute(v)))
             throw new UsageError();
     }
@@ -84,7 +99,9 @@ export function usage(options) {
     const failures = new Map();
     const now = (opts) => opts?.nowMs ?? (options.now ?? Date.now)();
     function connected(source) {
-        validate(source);
+        validate(source, options.stateDir);
+        if ('folder' in source)
+            return claudeCredential(source.folder) !== undefined;
         if ('credentialsFile' in source)
             return claudeAuth(source) !== undefined;
         if ('read' in source) {
@@ -107,9 +124,13 @@ export function usage(options) {
         return ('access' in source ? source.access : source.key).trim() !== '';
     }
     function account(source) {
-        validate(source);
+        validate(source, options.stateDir);
         let id;
-        if ('credentialsFile' in source)
+        if ('folder' in source) {
+            const stat = claudeCredential(source.folder);
+            id = stat ? `${source.folder}\0${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : undefined;
+        }
+        else if ('credentialsFile' in source)
             id = claudeAuth(source)?.account;
         else if ('read' in source)
             id = source.accountUuid;
@@ -164,7 +185,7 @@ export function usage(options) {
         }
     }
     async function read(source, opts) {
-        validate(source);
+        validate(source, options.stateDir);
         const clock = now(opts);
         const empty = (code) => ({ provider: source.provider, windows: [], code, poll: { at: clock, outcome: code ?? 'unavailable' } });
         if (!connected(source))
@@ -202,7 +223,7 @@ export function usage(options) {
             let answer;
             const pacing = { hook: options.pace, provider: source.provider, account: id.key, signal: opts?.signal };
             try {
-                answer = 'read' in source ? await customClaude(source, clock, pacing) : 'credentialsFile' in source ? await claudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing)
+                answer = 'folder' in source ? await managedClaudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing) : 'read' in source ? await customClaude(source, clock, pacing) : 'credentialsFile' in source ? await claudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing)
                     : 'bin' in source ? await codexUsage(source) : await providerGet(source, options.fetch ?? globalThis.fetch, clock, pacing);
             }
             catch {

package/dist/providers.d.ts

@@ -5,6 +5,16 @@ type TokenSource = Extract<Source, {
 } | {
     key: string;
 }>;
+/** One bounded request; credentials and response bodies never become errors. */
+export declare function providerHttp(url: string, key: string, fetcher: typeof fetch, nowMs: number, extra?: {
+    headers?: Record<string, string>;
+    body?: unknown;
+}, pacing?: {
+    hook?: PacingHook;
+    provider: Source['provider'];
+    account: string;
+    signal?: AbortSignal;
+}): Promise<Answer>;
 export declare function providerGet(source: TokenSource, fetcher: typeof fetch, nowMs: number, pacing?: {
     hook?: PacingHook;
     provider: Source['provider'];
@@ -22,6 +32,10 @@ export declare function customClaude(source: Extract<Source, {
 export declare function codexUsage(source: Extract<Source, {
     bin: string;
 }>): Promise<Answer>;
+/** The single bounded app-server transport used for identity and usage. */
+export declare function codexRequest(source: Extract<Source, {
+    bin: string;
+}>, method: 'account/read' | 'account/rateLimits/read', timeoutMs?: number): Promise<Answer>;
 /** Re-read the tool's credentials so its own renewal is picked up; never renew or write them. */
 export declare function claudeAuth(source: Extract<Source, {
     credentialsFile: string;

package/dist/providers.js

@@ -5,7 +5,7 @@ import { claudeWindows, record } from "./windows.js";
 import { grokWindows } from "./quota.js";
 const USER_AGENT = 'byokit/usage/0.2.0';
 /** One bounded request; credentials and response bodies never become errors. */
-async function request(url, key, fetcher, nowMs, extra = {}, pacing) {
+export async function providerHttp(url, key, fetcher, nowMs, extra = {}, pacing) {
     const controller = new AbortController();
     const abort = () => controller.abort();
     pacing?.signal?.addEventListener('abort', abort, { once: true });
@@ -69,7 +69,7 @@ async function request(url, key, fetcher, nowMs, extra = {}, pacing) {
 }
 export async function providerGet(source, fetcher, nowMs, pacing) {
     const key = 'access' in source ? source.access : source.key;
-    const get = (url, extra) => request(url, key, fetcher, nowMs, extra, pacing);
+    const get = (url, extra) => providerHttp(url, key, fetcher, nowMs, extra, pacing);
     switch (source.provider) {
         case 'claude': return get('https://api.anthropic.com/api/oauth/usage', { headers: { 'anthropic-beta': 'oauth-2025-04-20' } });
         case 'codex': return get('https://chatgpt.com/backend-api/wham/usage', { headers: { 'ChatGPT-Account-Id': source.accountId } });
@@ -138,6 +138,10 @@ export async function customClaude(source, nowMs, pacing) {
     }
 }
 export function codexUsage(source) {
+    return codexRequest(source, 'account/rateLimits/read', 20_000);
+}
+/** The single bounded app-server transport used for identity and usage. */
+export function codexRequest(source, method, timeoutMs = 15_000) {
     return new Promise((resolve) => {
         const child = spawn(source.bin, ['app-server'], { env: { ...source.env, CODEX_HOME: source.home }, stdio: ['pipe', 'pipe', 'ignore'] });
         let buffer = '';
@@ -156,7 +160,7 @@ export function codexUsage(source) {
             }
             resolve(answer);
         };
-        const timer = setTimeout(() => finish({ code: 'unavailable' }), 20_000);
+        const timer = setTimeout(() => finish({ code: 'unavailable' }), timeoutMs);
         child.once('error', () => finish({ code: 'unavailable' }));
         child.once('close', () => { clearTimeout(escalation); finish({ code: 'unavailable' }); });
         child.stdin.on('error', () => finish({ code: 'unavailable' }));
@@ -181,7 +185,7 @@ export function codexUsage(source) {
                     if (!record(message))
                         continue;
                     if (message.id === 1)
-                        child.stdin.write(`${JSON.stringify({ id: 2, method: 'account/rateLimits/read', params: {} })}\n`);
+                        child.stdin.write(`${JSON.stringify({ id: 2, method, params: {} })}\n`);
                     if (message.id === 2)
                         finish(record(message.result) ? { raw: message.result } : { code: 'incomplete' });
                 }

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

@@ -4,6 +4,13 @@ type Identity = {
     accountId?: string;
 };
 export type Source = {
+    provider: 'claude';
+    folder: string;
+    headers: {
+        'anthropic-beta': string;
+        'User-Agent': string;
+    };
+} | {
     provider: 'codex';
     bin: string;
     home: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/usage",
-  "version": "0.3.0",
+  "version": "0.5.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": [