agent-shim 7.13.1 → 7.14.0

package/dist/types/usage/read.d.ts

@@ -1,70 +0,0 @@
-import type { FarmFs } from "../launcher/ports";
-import { type LimitKind, type UsageRecord, type UsageSnapshot } from "./schema";
-/**
- * The read side of the usage store: pure over an injected filesystem, so the CLI, the library surface and tests all read the same way, and nothing here writes.
- */
-/** The filesystem reads the usage store's readers need. */
-export type UsageReadFs = Pick<FarmFs, "readFileUtf8" | "readdir">;
-/** The UTC day an instant falls on, as a segment names it. */
-export declare function segmentDay(epochMs: number): string;
-/** A segment's file name for one writer on one day. */
-export declare function segmentName(day: string, pid: number): string;
-/** One log segment found on disk. */
-export interface LogSegment {
-    readonly name: string;
-    readonly day: string;
-    /** The epoch milliseconds the segment's day ends at: no record in it is later. */
-    readonly endsAt: number;
-}
-/** Lists the log's segments, oldest day first; files that are not segments (a stray temporary file) are not the log's and are ignored. */
-export declare function listLogSegments(fs: Pick<FarmFs, "readdir">, logDir: string): readonly LogSegment[];
-/** What a log read found. */
-export interface UsageLogRead {
-    /** Every valid record at or after the cut-off, oldest first. */
-    readonly records: readonly UsageRecord[];
-    /** Complete lines that did not parse as a record of this schema version: a corrupted line, or one a newer agent-shim wrote. Reported, never silently dropped. */
-    readonly invalidLines: number;
-}
-/**
- * Reads the usage log, optionally only from `sinceMs` on. Each segment has a single writer that appends whole lines, so the only incomplete line a reader can meet is the last one of a segment still being written, which has no trailing newline yet; it is left for the next read rather than counted as invalid.
- */
-export declare function readUsageLog(fs: UsageReadFs, logDir: string, options?: {
-    readonly sinceMs?: number;
-}): UsageLogRead;
-/** Raised for a snapshot file that exists but does not hold a snapshot of this schema version. */
-export declare class UsageSnapshotError extends Error {
-    readonly file: string;
-    constructor(file: string, detail: string);
-}
-/** The path of an identity's snapshot. Throws for an invalid identity name, which could otherwise name a path outside the snapshots directory. */
-export declare function snapshotPath(snapshotsDir: string, identity: string): string;
-/** Reads one identity's snapshot: undefined when it has none yet, `UsageSnapshotError` when the file is there but unreadable. */
-export declare function readUsageSnapshot(fs: Pick<FarmFs, "readFileUtf8">, snapshotsDir: string, identity: string): UsageSnapshot | undefined;
-/** Reads every identity's snapshot, by identity name. */
-export declare function listUsageSnapshots(fs: UsageReadFs, snapshotsDir: string): readonly UsageSnapshot[];
-/** Token totals across a set of records. */
-interface TokenTotals {
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    readonly cacheCreationInputTokens: number;
-    readonly cacheReadInputTokens: number;
-}
-/** The totals for one identity and provider over a set of records. */
-export interface UsageSummary {
-    /** The identity, or undefined for requests from a launch that resolved none. */
-    readonly identity: string | undefined;
-    readonly provider: string;
-    readonly requests: number;
-    /** Responses with a status of 400 or above (refusals included). */
-    readonly failed: number;
-    /** Classified refusals, by kind. */
-    readonly limits: Readonly<Record<LimitKind, number>>;
-    readonly tokens: TokenTotals;
-    readonly firstAt: string;
-    readonly lastAt: string;
-    /** The models the responses named, most-used first. */
-    readonly models: readonly string[];
-}
-/** Groups records by identity and provider and totals each group, ordered by identity then provider. */
-export declare function summariseUsage(records: readonly UsageRecord[]): readonly UsageSummary[];
-export {};

package/dist/types/usage/scan.d.ts

@@ -1,24 +0,0 @@
-import type { ErrorInfo } from "./rateLimit";
-import type { TokenUsage } from "./schema";
-/**
- * Incremental scanners that pull usage metadata out of a response body as it streams past, without ever holding the body: the model, the `usage` token counts, and an error's type, code and message. Content (text deltas, tool input, message content) is skipped character by character and never accumulated, so memory stays bounded by the metadata itself whatever the response's size.
- */
-/** What a scan found. */
-export interface ScanResult {
-    readonly model: string | undefined;
-    readonly usage: TokenUsage | undefined;
-    readonly error: ErrorInfo | undefined;
-}
-/** A body scanner: fed decoded text in arrival order, read once the body has ended. */
-export interface BodyScanner {
-    readonly push: (text: string) => void;
-    readonly result: () => ScanResult;
-}
-/**
- * Scans an Anthropic-format server-sent-events stream. Lines are split as they arrive, across chunk boundaries anywhere; an `event:` line names the event its `data:` lines belong to, and only metadata events' data is accumulated. A data line whose event is not named is held only until its leading `"type"` shows whether it is a metadata event, so content is never accumulated beyond those opening bytes.
- */
-export declare function createSseScanner(): BodyScanner;
-/**
- * Scans a JSON response body (a non-streaming Messages response, or an error body) for its top-level `model`, `usage` and `error`, capturing only those values' text. A small state machine tracks nesting and strings, so a `usage` key nested inside content is never mistaken for the top-level one, and content is walked past without being kept.
- */
-export declare function createJsonScanner(): BodyScanner;

package/dist/types/usage/schema.d.ts

@@ -1,318 +0,0 @@
-import { z } from "zod";
-/**
- * The usage store's one schema definition: every record the front door appends to the usage log, the per-identity snapshot other tools read, and the account metadata both carry. Each is a strict object, so a field not named here can never be written (the store validates every record and snapshot before it touches disk) and the published JSON Schemas (`schema/UsageRecord.schema.json`, `schema/UsageSnapshot.schema.json`) describe exactly what a reader can find.
- *
- * Metadata only, by construction: nothing here can hold a prompt, a response, tool content, or a credential. Rate-limit headers are kept by name from an allow-list of quota headers (`isRateLimitHeader`), never wholesale.
- */
-/** The version of the record and snapshot shapes below. A reader checks it before trusting a document; a change that is not purely additive bumps it. */
-export declare const USAGE_SCHEMA_VERSION = 1;
-/** Token counts from a response body's `usage` object, renamed to this project's casing. Each field is present only when the response reported it. */
-export declare const TokenUsageSchema: z.ZodObject<{
-    inputTokens: z.ZodOptional<z.ZodNumber>;
-    outputTokens: z.ZodOptional<z.ZodNumber>;
-    cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
-    cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
-export type TokenUsage = z.infer<typeof TokenUsageSchema>;
-/** The two kinds of refusal a consumer acts on differently: a short rate limit is worth retrying on the same credential once its wait has passed, an exhausted quota means moving to the next credential until the reset. */
-declare const LIMIT_KINDS: readonly ["rate-limited", "quota-exhausted"];
-export type LimitKind = (typeof LIMIT_KINDS)[number];
-/** A 429 (or 402) classified, with the wait or reset the upstream announced and the signals the classification rests on. */
-export declare const LimitClassificationSchema: z.ZodObject<{
-    kind: z.ZodEnum<{
-        "rate-limited": "rate-limited";
-        "quota-exhausted": "quota-exhausted";
-    }>;
-    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
-    resetAt: z.ZodOptional<z.ZodISODateTime>;
-    window: z.ZodOptional<z.ZodString>;
-    evidence: z.ZodArray<z.ZodString>;
-}, z.core.$strict>;
-export type LimitClassification = z.infer<typeof LimitClassificationSchema>;
-/** One routed request, appended to the usage log when its response has finished. */
-export declare const UsageRecordSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    at: z.ZodISODateTime;
-    identity: z.ZodOptional<z.ZodString>;
-    provider: z.ZodString;
-    sessionId: z.ZodOptional<z.ZodString>;
-    project: z.ZodOptional<z.ZodString>;
-    route: z.ZodString;
-    method: z.ZodString;
-    endpoint: z.ZodString;
-    model: z.ZodOptional<z.ZodString>;
-    status: z.ZodNumber;
-    latencyMs: z.ZodNumber;
-    durationMs: z.ZodNumber;
-    outcome: z.ZodEnum<{
-        aborted: "aborted";
-        completed: "completed";
-    }>;
-    usage: z.ZodOptional<z.ZodObject<{
-        inputTokens: z.ZodOptional<z.ZodNumber>;
-        outputTokens: z.ZodOptional<z.ZodNumber>;
-        cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
-        cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>>;
-    rateLimitHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    limit: z.ZodOptional<z.ZodObject<{
-        kind: z.ZodEnum<{
-            "rate-limited": "rate-limited";
-            "quota-exhausted": "quota-exhausted";
-        }>;
-        retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
-        resetAt: z.ZodOptional<z.ZodISODateTime>;
-        window: z.ZodOptional<z.ZodString>;
-        evidence: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>;
-    requestId: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type UsageRecord = z.infer<typeof UsageRecordSchema>;
-/** One quota window from Anthropic's unified rate-limit headers. */
-declare const QuotaWindowSchema: z.ZodObject<{
-    utilization: z.ZodOptional<z.ZodNumber>;
-    resetsAt: z.ZodOptional<z.ZodISODateTime>;
-    status: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type QuotaWindow = z.infer<typeof QuotaWindowSchema>;
-/** Anthropic's unified subscription rate-limit state, parsed from the `anthropic-ratelimit-unified-*` headers (which the in-process Codex route also derives from the Codex backend's own quota headers). */
-export declare const UnifiedRateLimitSchema: z.ZodObject<{
-    status: z.ZodOptional<z.ZodString>;
-    fiveHour: z.ZodOptional<z.ZodObject<{
-        utilization: z.ZodOptional<z.ZodNumber>;
-        resetsAt: z.ZodOptional<z.ZodISODateTime>;
-        status: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    sevenDay: z.ZodOptional<z.ZodObject<{
-        utilization: z.ZodOptional<z.ZodNumber>;
-        resetsAt: z.ZodOptional<z.ZodISODateTime>;
-        status: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    representativeClaim: z.ZodOptional<z.ZodString>;
-    resetAt: z.ZodOptional<z.ZodISODateTime>;
-    overageStatus: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type UnifiedRateLimit = z.infer<typeof UnifiedRateLimitSchema>;
-/** The latest rate-limit state an upstream reported on any response. */
-declare const RateLimitStateSchema: z.ZodObject<{
-    observedAt: z.ZodISODateTime;
-    headers: z.ZodRecord<z.ZodString, z.ZodString>;
-    unified: z.ZodOptional<z.ZodObject<{
-        status: z.ZodOptional<z.ZodString>;
-        fiveHour: z.ZodOptional<z.ZodObject<{
-            utilization: z.ZodOptional<z.ZodNumber>;
-            resetsAt: z.ZodOptional<z.ZodISODateTime>;
-            status: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
-        sevenDay: z.ZodOptional<z.ZodObject<{
-            utilization: z.ZodOptional<z.ZodNumber>;
-            resetsAt: z.ZodOptional<z.ZodISODateTime>;
-            status: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
-        representativeClaim: z.ZodOptional<z.ZodString>;
-        resetAt: z.ZodOptional<z.ZodISODateTime>;
-        overageStatus: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type RateLimitState = z.infer<typeof RateLimitStateSchema>;
-/** A classified refusal, with when it was seen and its status. */
-declare const LimitEventSchema: z.ZodObject<{
-    kind: z.ZodEnum<{
-        "rate-limited": "rate-limited";
-        "quota-exhausted": "quota-exhausted";
-    }>;
-    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
-    resetAt: z.ZodOptional<z.ZodISODateTime>;
-    window: z.ZodOptional<z.ZodString>;
-    evidence: z.ZodArray<z.ZodString>;
-    observedAt: z.ZodISODateTime;
-    status: z.ZodNumber;
-}, z.core.$strict>;
-export type LimitEvent = z.infer<typeof LimitEventSchema>;
-/** One quota window a provider reports through its own usage endpoint (as opposed to headers on a response): how much of it is used and when it resets. */
-declare const ProviderQuotaWindowSchema: z.ZodObject<{
-    measures: z.ZodString;
-    periodMs: z.ZodOptional<z.ZodNumber>;
-    period: z.ZodOptional<z.ZodString>;
-    utilization: z.ZodNumber;
-    resetsAt: z.ZodOptional<z.ZodISODateTime>;
-    limit: z.ZodOptional<z.ZodNumber>;
-    used: z.ZodOptional<z.ZodNumber>;
-    remaining: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
-export type ProviderQuotaWindow = z.infer<typeof ProviderQuotaWindowSchema>;
-/** A provider's quota as its usage endpoint last reported it. Pulled, not observed on a request, so it carries its own observation time. */
-export declare const ProviderQuotaSchema: z.ZodObject<{
-    observedAt: z.ZodISODateTime;
-    source: z.ZodString;
-    level: z.ZodOptional<z.ZodString>;
-    windows: z.ZodArray<z.ZodObject<{
-        measures: z.ZodString;
-        periodMs: z.ZodOptional<z.ZodNumber>;
-        period: z.ZodOptional<z.ZodString>;
-        utilization: z.ZodNumber;
-        resetsAt: z.ZodOptional<z.ZodISODateTime>;
-        limit: z.ZodOptional<z.ZodNumber>;
-        used: z.ZodOptional<z.ZodNumber>;
-        remaining: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type ProviderQuota = z.infer<typeof ProviderQuotaSchema>;
-/** One provider's latest state under one identity. */
-declare const ProviderUsageStateSchema: z.ZodObject<{
-    lastRequestAt: z.ZodISODateTime;
-    lastStatus: z.ZodNumber;
-    lastModel: z.ZodOptional<z.ZodString>;
-    rateLimit: z.ZodOptional<z.ZodObject<{
-        observedAt: z.ZodISODateTime;
-        headers: z.ZodRecord<z.ZodString, z.ZodString>;
-        unified: z.ZodOptional<z.ZodObject<{
-            status: z.ZodOptional<z.ZodString>;
-            fiveHour: z.ZodOptional<z.ZodObject<{
-                utilization: z.ZodOptional<z.ZodNumber>;
-                resetsAt: z.ZodOptional<z.ZodISODateTime>;
-                status: z.ZodOptional<z.ZodString>;
-            }, z.core.$strict>>;
-            sevenDay: z.ZodOptional<z.ZodObject<{
-                utilization: z.ZodOptional<z.ZodNumber>;
-                resetsAt: z.ZodOptional<z.ZodISODateTime>;
-                status: z.ZodOptional<z.ZodString>;
-            }, z.core.$strict>>;
-            representativeClaim: z.ZodOptional<z.ZodString>;
-            resetAt: z.ZodOptional<z.ZodISODateTime>;
-            overageStatus: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-    lastLimit: z.ZodOptional<z.ZodObject<{
-        kind: z.ZodEnum<{
-            "rate-limited": "rate-limited";
-            "quota-exhausted": "quota-exhausted";
-        }>;
-        retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
-        resetAt: z.ZodOptional<z.ZodISODateTime>;
-        window: z.ZodOptional<z.ZodString>;
-        evidence: z.ZodArray<z.ZodString>;
-        observedAt: z.ZodISODateTime;
-        status: z.ZodNumber;
-    }, z.core.$strict>>;
-    quota: z.ZodOptional<z.ZodObject<{
-        observedAt: z.ZodISODateTime;
-        source: z.ZodString;
-        level: z.ZodOptional<z.ZodString>;
-        windows: z.ZodArray<z.ZodObject<{
-            measures: z.ZodString;
-            periodMs: z.ZodOptional<z.ZodNumber>;
-            period: z.ZodOptional<z.ZodString>;
-            utilization: z.ZodNumber;
-            resetsAt: z.ZodOptional<z.ZodISODateTime>;
-            limit: z.ZodOptional<z.ZodNumber>;
-            used: z.ZodOptional<z.ZodNumber>;
-            remaining: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type ProviderUsageState = z.infer<typeof ProviderUsageStateSchema>;
-/**
- * The account fields copied from an identity's stored Claude login (`oauthAccount` in the identity's `.claude.json`): who the account is and which plan and tier it is on. Never the token, which Claude Code keeps elsewhere. Each field is present only when the stored login has it; a setup-token identity has no profile scope and so none of them (see issue #44).
- */
-export declare const AccountMetadataSchema: z.ZodObject<{
-    accountUuid: z.ZodOptional<z.ZodString>;
-    emailAddress: z.ZodOptional<z.ZodString>;
-    displayName: z.ZodOptional<z.ZodString>;
-    organizationUuid: z.ZodOptional<z.ZodString>;
-    organizationName: z.ZodOptional<z.ZodString>;
-    organizationType: z.ZodOptional<z.ZodString>;
-    organizationRole: z.ZodOptional<z.ZodString>;
-    workspaceRole: z.ZodOptional<z.ZodString>;
-    billingType: z.ZodOptional<z.ZodString>;
-    seatTier: z.ZodOptional<z.ZodString>;
-    organizationRateLimitTier: z.ZodOptional<z.ZodString>;
-    userRateLimitTier: z.ZodOptional<z.ZodString>;
-    hasExtraUsageEnabled: z.ZodOptional<z.ZodBoolean>;
-    subscriptionCreatedAt: z.ZodOptional<z.ZodString>;
-    accountCreatedAt: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type AccountMetadata = z.infer<typeof AccountMetadataSchema>;
-/**
- * The latest state for one identity, rewritten atomically after each recorded response: the snapshot file other tools read (`~/.agent-shim/usage/snapshots/<identity>.json`) without shelling out to `agent-shim`.
- */
-export declare const UsageSnapshotSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    identity: z.ZodString;
-    updatedAt: z.ZodISODateTime;
-    account: z.ZodOptional<z.ZodObject<{
-        accountUuid: z.ZodOptional<z.ZodString>;
-        emailAddress: z.ZodOptional<z.ZodString>;
-        displayName: z.ZodOptional<z.ZodString>;
-        organizationUuid: z.ZodOptional<z.ZodString>;
-        organizationName: z.ZodOptional<z.ZodString>;
-        organizationType: z.ZodOptional<z.ZodString>;
-        organizationRole: z.ZodOptional<z.ZodString>;
-        workspaceRole: z.ZodOptional<z.ZodString>;
-        billingType: z.ZodOptional<z.ZodString>;
-        seatTier: z.ZodOptional<z.ZodString>;
-        organizationRateLimitTier: z.ZodOptional<z.ZodString>;
-        userRateLimitTier: z.ZodOptional<z.ZodString>;
-        hasExtraUsageEnabled: z.ZodOptional<z.ZodBoolean>;
-        subscriptionCreatedAt: z.ZodOptional<z.ZodString>;
-        accountCreatedAt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
-        lastRequestAt: z.ZodISODateTime;
-        lastStatus: z.ZodNumber;
-        lastModel: z.ZodOptional<z.ZodString>;
-        rateLimit: z.ZodOptional<z.ZodObject<{
-            observedAt: z.ZodISODateTime;
-            headers: z.ZodRecord<z.ZodString, z.ZodString>;
-            unified: z.ZodOptional<z.ZodObject<{
-                status: z.ZodOptional<z.ZodString>;
-                fiveHour: z.ZodOptional<z.ZodObject<{
-                    utilization: z.ZodOptional<z.ZodNumber>;
-                    resetsAt: z.ZodOptional<z.ZodISODateTime>;
-                    status: z.ZodOptional<z.ZodString>;
-                }, z.core.$strict>>;
-                sevenDay: z.ZodOptional<z.ZodObject<{
-                    utilization: z.ZodOptional<z.ZodNumber>;
-                    resetsAt: z.ZodOptional<z.ZodISODateTime>;
-                    status: z.ZodOptional<z.ZodString>;
-                }, z.core.$strict>>;
-                representativeClaim: z.ZodOptional<z.ZodString>;
-                resetAt: z.ZodOptional<z.ZodISODateTime>;
-                overageStatus: z.ZodOptional<z.ZodString>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>>;
-        lastLimit: z.ZodOptional<z.ZodObject<{
-            kind: z.ZodEnum<{
-                "rate-limited": "rate-limited";
-                "quota-exhausted": "quota-exhausted";
-            }>;
-            retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
-            resetAt: z.ZodOptional<z.ZodISODateTime>;
-            window: z.ZodOptional<z.ZodString>;
-            evidence: z.ZodArray<z.ZodString>;
-            observedAt: z.ZodISODateTime;
-            status: z.ZodNumber;
-        }, z.core.$strict>>;
-        quota: z.ZodOptional<z.ZodObject<{
-            observedAt: z.ZodISODateTime;
-            source: z.ZodString;
-            level: z.ZodOptional<z.ZodString>;
-            windows: z.ZodArray<z.ZodObject<{
-                measures: z.ZodString;
-                periodMs: z.ZodOptional<z.ZodNumber>;
-                period: z.ZodOptional<z.ZodString>;
-                utilization: z.ZodNumber;
-                resetsAt: z.ZodOptional<z.ZodISODateTime>;
-                limit: z.ZodOptional<z.ZodNumber>;
-                used: z.ZodOptional<z.ZodNumber>;
-                remaining: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type UsageSnapshot = z.infer<typeof UsageSnapshotSchema>;
-/**
- * Whether a response header is one the store keeps: the quota and rate-limit families the upstreams agent-shim routes to send (Anthropic's `anthropic-ratelimit-*`, the IETF draft's `ratelimit*`, the common `x-ratelimit-*`, the Codex backend's `x-codex-*` quota headers, which the Codex route forwards) and `retry-after`. Every one of these carries a number, a time or a status word; none carries a credential or content.
- */
-export declare function isRateLimitHeader(name: string): boolean;
-export {};

package/dist/types/usage/store.d.ts

@@ -1,43 +0,0 @@
-import type { FarmFs } from "../launcher/ports";
-import type { LayoutPaths } from "../paths";
-import { type AccountMetadata, type ProviderQuota, type ProviderUsageState, type UsageRecord } from "./schema";
-/** The filesystem effects the usage store's writer performs, all owner-only. */
-export type UsageFs = Pick<FarmFs, "mkdirPrivate" | "writeFilePrivate" | "appendFilePrivate" | "readFileUtf8" | "readdir" | "removeRecursive">;
-/**
- * How long the usage log keeps records: seven days, the longest quota window any upstream agent-shim routes to enforces (Anthropic's subscription `seven_day` window, and the weekly windows z.ai's GLM Coding Plan and MiniMax's Token Plan document). Consumers ask the log how a credential's quota was spent within its current windows; a record older than the longest window can no longer count against any of them. Segments are pruned whole, by day, so the log always covers at least the full window.
- */
-export declare const USAGE_RETENTION_MS: number;
-/** Removes every log segment whose day ended before the retention window began. Safe to race: removing a segment another pruner already removed does nothing. */
-export declare function pruneUsageLog(fs: Pick<UsageFs, "readdir" | "removeRecursive">, logDir: string, nowMs: number): void;
-/** Everything the store's writer depends on. */
-export interface UsageStoreDeps {
-    readonly fs: UsageFs;
-    readonly paths: Pick<LayoutPaths, "usageDir" | "usageLogDir" | "usageSnapshotsDir">;
-    /** This process's pid, which names its own log segments: one writer per segment is what makes concurrent writers safe without locking. */
-    readonly pid: number;
-    readonly now: () => number;
-    /** The identity's current account metadata, copied into its snapshot on every write so the snapshot is never staler than the last request. */
-    readonly readAccount: (identity: string) => AccountMetadata | undefined;
-    readonly log: (line: string) => void;
-}
-/** The store's writer. */
-export interface UsageStore {
-    /** Validates and appends one record, then refreshes its identity's snapshot. Throws on a write failure; the caller (the usage middleware) catches. */
-    readonly record: (record: UsageRecord) => void;
-    /** Attaches a provider's pulled quota to the identity's existing state for that provider, keeping the newer observation when one is already there. Returns false when the identity has no state for the provider (a quota is only ever attached to usage that was seen). Throws on a write failure. */
-    readonly recordQuota: (identity: string, provider: string, quota: ProviderQuota) => boolean;
-}
-/**
- * Folds one record into its provider's latest state. Each part keeps whichever observation is newest, so records folded out of order (two door generations overlapping, each writing its own) still leave the latest state, never an older one.
- */
-export declare function foldProviderState(current: ProviderUsageState | undefined, record: UsageRecord): ProviderUsageState;
-/**
- * The usage store's writer, owned by the front-door process.
- *
- * The log is append-only JSON Lines under `usage/log/`, one segment per writing process per UTC day (`<YYYY-MM-DD>.<pid>.jsonl`). Every segment has exactly one writer, so concurrent writers (two door generations overlapping during a restart) can never interleave within a line, and readers (`agent-shim usage`, other tools) need no lock: the only partial line they can meet is a segment's unfinished last one, which they skip. Retention is enforced by pruning whole segments on the first write of each day.
- *
- * Each identity's snapshot (`usage/snapshots/<identity>.json`) is rewritten atomically (a temporary sibling renamed into place) after every record, so a reader always sees a whole snapshot. Two writers racing on one snapshot can each overwrite the other's newest observation for a provider, but never corrupt the file; the next record repairs it, and the log, not the snapshot, is the record of truth. A snapshot that cannot be read (a newer schema, a corrupted file) is replaced with a fresh one, and the replacement is logged.
- *
- * Everything is created owner-only: the directories 0700, the files 0600.
- */
-export declare function createUsageStore(deps: UsageStoreDeps): UsageStore;

package/dist/types/versionDiscovery.d.ts

@@ -1,47 +0,0 @@
-/** One entry observed inside a versions directory (e.g. ~/.local/share/claude/versions/2.1.220). */
-export interface VersionsDirEntry {
-    /** The entry's own name — expected to be a plain dotted-numeric version like "2.1.220". */
-    name: string;
-    /** Whether the entry is a regular file (not a directory, symlink-to-directory, etc). */
-    isFile: boolean;
-    /** Whether the entry has at least one execute bit set. */
-    isExecutable: boolean;
-    /** The entry's size in bytes. */
-    sizeBytes: number;
-}
-/** Injected dependencies for discoverClaudeBinary, so no test ever touches a real filesystem or PATH. */
-export interface DiscoverClaudeBinaryOptions {
-    /** Directory to scan for versioned claude binaries. Defaults to ~/.local/share/claude/versions. */
-    versionsDir?: string;
-    /** Lists the entries of a versions directory. Injected so tests never touch the real filesystem. */
-    listVersionsDir: (dir: string) => VersionsDirEntry[];
-    /** The PATH-like list of directories to search as a fallback, in order. */
-    pathDirs: string[];
-    /** Looks up an executable of the given name inside one PATH directory, returning its full path if found. */
-    findExecutableInDir: (dir: string, name: string) => string | undefined;
-    /** This tool's own install directory(ies), excluded from the PATH fallback search to avoid self-selection. */
-    ownInstallDirs: string[];
-}
-/** The result of a successful discovery. */
-export interface DiscoveredClaudeBinary {
-    /** Full path to the discovered `claude` executable. */
-    path: string;
-    /** Which strategy found it. */
-    source: "versions-dir" | "path-fallback";
-    /** The version string, when discovered via the versions directory. */
-    version?: string;
-}
-/** True when `name` is a plain dotted-numeric version string like "2.1.220" (never full semver — no pre-release/build metadata is expected here). */
-export declare function isNumericDottedVersion(name: string): boolean;
-/**
- * Compares two plain dotted-numeric version strings segment by segment, treating a missing trailing segment as 0 (so "2.1" sorts before "2.1.1"). Returns a negative number when `a` is the earlier version, a positive number when `a` is the later one, and 0 when equal. Throws if either string isn't a valid numeric-dotted version — callers must filter with isNumericDottedVersion first, since a naive string/lexicographic sort would incorrectly rank "2.9.0" ahead of "2.10.0".
- */
-export declare function compareVersions(a: string, b: string): number;
-/**
- * Filters `entries` to genuinely-executable, non-empty regular files whose name is a valid dotted-numeric version (skipping things like .DS_Store or a stray empty file), then picks the highest version by a real numeric-segment comparison. Returns undefined when nothing qualifies.
- */
-export declare function pickHighestVersion(entries: readonly VersionsDirEntry[]): string | undefined;
-/**
- * Discovers the real `claude` binary to launch: first by scanning the versions directory and picking the highest genuinely-executable version, then falling back to a PATH search for a `claude` executable (excluding this tool's own install directory, so the launcher never recursively selects itself). Throws a clear, actionable error when neither strategy finds anything — this is a deliberate improvement over the legacy bash tool, which crashed cryptically on a missing or empty versions directory instead of reporting the problem.
- */
-export declare function discoverClaudeBinary(options: DiscoverClaudeBinaryOptions): DiscoveredClaudeBinary;