agent-shim 0.0.0 → 7.1.0

package/dist/types/resolve/types.d.ts

@@ -0,0 +1,159 @@
+import type { CategoryMap, CategoryName, Entries, LaunchFlags, OverridableCategory, WhenCondition } from "../config/schema";
+/** A layer's index in the assembled cascade. Strictly ascending in composition order: a higher id was composed later and therefore wins on the comparator's first rank. */
+export type LayerId = number;
+/** Where a cascade layer came from. Purely descriptive — precedence is carried by `LayerId`, never by kind. */
+type LayerKind = "global-config" | "config-profile" | "directory-rule" | "portable" | "portable-local" | "cli-override";
+/** One composable layer of the cascade: its own category toggles and entries overrides, plus the entries key order captured at load time. */
+export interface Layer {
+    readonly id: LayerId;
+    readonly kind: LayerKind;
+    /** Human-readable origin (a file path, or a profile name) used by `agent-shim check` to explain a decision. */
+    readonly source: string;
+    readonly categories?: CategoryMap;
+    readonly entries?: Entries;
+    /** The entries object's own key insertion order, from `src/config/load.ts`. Falls back to `Object.keys(entries)` when absent. */
+    readonly entryOrder?: readonly string[];
+    readonly launch?: LaunchFlags;
+}
+/** Facts about one entry under `~/.claude`, relative to `~/.claude` itself. */
+export interface EntryFact {
+    /** Path relative to `~/.claude`, forward-slash separated, never leading or trailing slash. */
+    readonly relPath: string;
+    readonly isDirectory: boolean;
+    /** True when the entry is itself a symlink (including the relative, tree-escaping symlinks that already exist inside a real `~/.claude`). */
+    readonly isSymlink: boolean;
+    /** The entry's own mtime. */
+    readonly mtimeMs: number;
+    /** The most recent mtime anywhere in this entry's subtree — its own mtime for a plain file. A directory-scoped `newerThan` must read this, never the directory's own inode mtime, which does not change when a file three levels down is rewritten. */
+    readonly latestMtimeMs: number;
+    /** The entry's own size. */
+    readonly sizeBytes: number;
+    /** The recursive total size of this entry's subtree — its own size for a plain file. A directory-scoped `maxSizeBytes` must read this, never the directory's own ~4KB inode size. */
+    readonly totalSizeBytes: number;
+}
+/**
+ * Every fact the resolver needs, injected rather than read. Nothing in `src/resolve/` ever touches a real filesystem, git repository, clock, or environment: something else builds this structure and hands it over, which is what makes the whole resolver unit-testable with fake mtimes, a fake branch, and a fake environment.
+ */
+export interface EntryFacts {
+    readonly nowMs: number;
+    /** The real home directory, used to expand `~` in `history/projects/` patterns. */
+    readonly home: string;
+    /** The canonical `~/.claude` directory every relative path in `entries` is relative to. */
+    readonly claudeHome: string;
+    /** The working directory the cascade was resolved for. */
+    readonly cwd: string;
+    /** The git branch checked out at `cwd`, or undefined when `cwd` is not in a repository. */
+    readonly branch?: string;
+    /** True when `cwd`'s repository is in detached-HEAD state, in which case no `branch` condition can match. */
+    readonly branchDetached?: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Every entry under `~/.claude`, keyed by its path relative to `~/.claude`. Directories appear alongside their descendants. */
+    readonly entries: ReadonlyMap<string, EntryFact>;
+}
+/** A single entries override, compiled into the form the resolver actually matches against. */
+export interface CompiledRule {
+    /** The key exactly as written in its source file, for diagnostics. */
+    readonly rawKey: string;
+    /** The category prefix the key declared. Cross-checked against the real classification of every path it matches. */
+    readonly declaredCategory: CategoryName;
+    /** The key with its category prefix stripped and (under `history/projects/`) its path fragment encoded — a pattern over paths relative to `~/.claude`. Two differently-spelled but equivalent keys share one canonical pattern and therefore collapse to one rule. */
+    readonly canonicalPattern: string;
+    readonly value: boolean;
+    readonly when?: WhenCondition;
+    readonly layer: LayerId;
+    /** The key's position within its own layer's entries object, used only by the comparator's final same-layer tie-break. */
+    readonly ordinal: number;
+    /** True when the canonical pattern contains no glob metacharacter. */
+    readonly isExact: boolean;
+    /** The pattern's leading run of literal (non-wildcard) characters. */
+    readonly literalPrefix: string;
+    /** How many `/`-separated segments the canonical pattern has. */
+    readonly segmentCount: number;
+    /** Matches the pattern itself and everything beneath it, so a rule on `skills` covers `skills/commit/SKILL.md`. */
+    readonly matches: (relPath: string) => boolean;
+}
+/** How a decision was reached, for `agent-shim check`'s "which layer decided this" output. */
+type DecisionVia = 
+/** The unconditional pre-cascade floor: the path's real classification is `secret`. */
+"secret-floor"
+/** Nothing in the classification map recognises the path's top-level entry. */
+ | "unclassified"
+/** An entries rule matched and its condition (if any) held. */
+ | "entry-rule"
+/** No entries rule survived; a layer's category toggle decided it. */
+ | "category-override"
+/** No entries rule and no category toggle; the shipped default for the category decided it. */
+ | "category-default";
+/** One entry's resolved sharing decision plus the reasoning behind it. */
+export interface Decision {
+    readonly relPath: string;
+    readonly shared: boolean;
+    readonly via: DecisionVia;
+    readonly category: CategoryName | null;
+    /** The winning entries rule, when `via` is "entry-rule". */
+    readonly rule?: CompiledRule;
+    /** Rules that matched but whose `when` condition failed, in descending specificity — each was eliminated and resolution continued to the next candidate. */
+    readonly eliminated?: readonly EliminatedRule[];
+}
+/** A candidate rule that matched the path but was eliminated because its `when` condition did not hold. */
+export interface EliminatedRule {
+    readonly rule: CompiledRule;
+    readonly failed: readonly string[];
+}
+/** Every diagnostic the resolver can raise. Codes are stable strings so `agent-shim check` and tests can assert on them. */
+type DiagnosticCode = 
+/** A profile's `extends` graph contains a cycle. */
+"EXTENDS_CYCLE"
+/** An `extends` entry names a profile that does not exist. */
+ | "MISSING_PROFILE"
+/** An entries key was written under the `secret/` prefix. Rejected at compile time — `secret` can never be overridden by any layer. */
+ | "SECRET_ENTRY_KEY"
+/** An entries key under some other prefix matched a path whose real classification is `secret`. Neutralised at resolve time by the floor check. */
+ | "SECRET_PATH_NEUTRALISED"
+/** An entries key's declared category prefix disagrees with the real classification of a path it matched. */
+ | "CATEGORY_PREFIX_MISMATCH"
+/** An entries key is not of the form `<category>/<path>`. The schema rejects these at parse time; this fires only for a layer built in code. */
+ | "MALFORMED_ENTRY_KEY"
+/** An earlier layer's exact key lost to a later layer's glob. Correct per the comparator, but worth surfacing rather than resolving silently. */
+ | "EXACT_ENTRY_OVERRIDDEN_BY_LATER_GLOB"
+/** A `history/projects/` pattern's encoded form could plausibly correspond to more than one real path. */
+ | "AMBIGUOUS_PROJECT_ENCODING"
+/** A `history/projects/` key's path fragment is neither home-rooted nor absolute, so it cannot be encoded. */
+ | "UNROOTED_PROJECT_PATH"
+/** A `~/.claude` entry nothing in the classification map recognises. */
+ | "UNCLASSIFIED_ENTRY"
+/** An empty `when: {}` object, which is vacuously true and therefore has no effect. */
+ | "EMPTY_WHEN"
+/** The previous farm's manifest is missing or unreadable, so reconciliation ran in conservative mode. */
+ | "FARM_MANIFEST_MISSING"
+/** A file Claude Code wrote into a materialised farm directory differs from the canonical copy of the same path. */
+ | "RECONCILE_CONFLICT"
+/** Reconciliation proposed adopting a path whose real classification is `secret`. Refused: the secret floor applies to data moving into `~/.claude` exactly as it applies to data moving out. */
+ | "RECONCILE_SECRET_BLOCKED"
+/** A previous launch was interrupted mid-swap and this launch completed or undid the half-finished work. */
+ | "FARM_SWAP_RECOVERED"
+/** A superseded farm could not be discarded because it still held data the new farm has its own entry for, so it was left on disk for the user to look at. */
+ | "FARM_PREVIOUS_RETAINED";
+/** Severity of a diagnostic. An `error` means a configuration layer asked for something the tool refused to do. */
+type DiagnosticSeverity = "error" | "warning" | "info";
+/** One structured diagnostic. */
+export interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    /** The config key, profile name, or entry path the diagnostic concerns. */
+    readonly subject?: string;
+    /** The layer that raised it, when the diagnostic is attributable to one. */
+    readonly layer?: LayerId;
+}
+/** The flattened result of cascade phase one. */
+export interface FlattenedCascade {
+    /** The last value each overridable category was set to across every layer. Categories no layer touched are absent. */
+    readonly categories: ReadonlyMap<OverridableCategory, boolean>;
+    /** One compiled rule per canonical pattern — later layers having already overwritten earlier ones for identical patterns. */
+    readonly rules: ReadonlyMap<string, CompiledRule>;
+    /** Launch flags, last layer wins per field. */
+    readonly launch: LaunchFlags;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export {};

package/dist/types/resolve/walk.d.ts

@@ -0,0 +1,85 @@
+import type { DirectoryRule, GlobalConfig, PortableConfig } from "../config/schema";
+import { type ProfileLoader } from "./extends";
+import type { Diagnostic, Layer } from "./types";
+/** Injected predicate answering whether a directory can be read, so the walk stays pure. */
+export type ReadablePredicate = (dir: string) => boolean;
+/** Options for the upward directory walk. */
+export interface WalkOptions {
+    /** The user's home directory, the walk's default stopping point. */
+    readonly home: string;
+    /** Where to stop walking upward, inclusive. Defaults to `home`, and is what `walkUpLimit` in the global config sets. */
+    readonly limit?: string;
+    /** Answers whether a directory is readable. A directory that is not stops the walk there rather than failing the launch. */
+    readonly isReadable?: ReadablePredicate;
+}
+/**
+ * Collects `cwd` and every ancestor of it, shallowest-first, the way Claude Code itself resolves nested `CLAUDE.md` files.
+ *
+ * The walk stops at (and includes) the limit directory — `$HOME` by default — or at the filesystem root when `cwd` is not beneath the limit at all. An ancestor that cannot be read stops the walk there rather than failing the launch: a directory you cannot read cannot carry a config file you were meant to obey.
+ *
+ * `cwd` is expected to already be a real path; resolving symlinks is the caller's job, so this stays free of filesystem access.
+ */
+export declare function walkDirectoryAncestors(cwd: string, options: WalkOptions): string[];
+/** The up-to-three configuration sources that can apply at one directory level. */
+export interface DirectoryLevelSources {
+    readonly dir: string;
+    /** The committed, team-shared `.agent-shim.json` at this level. */
+    readonly portable?: {
+        readonly config: PortableConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+    /** Every rule in this user's own `~/.agent-shim/directory-rules.json` whose path is exactly this level, in file order. */
+    readonly rules?: readonly {
+        readonly rule: DirectoryRule;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    }[];
+    /** The gitignored `.agent-shim.local.json` at this level. */
+    readonly portableLocal?: {
+        readonly config: PortableConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+}
+/** Everything needed to assemble the full ordered layer sequence, all of it already loaded by the caller. */
+export interface CascadeInput {
+    readonly home: string;
+    /** The user-global `~/.agent-shim/config.json`, the least-specific layer above the shipped defaults. */
+    readonly globalConfig?: {
+        readonly config: GlobalConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+    /** The configuration profile chosen by the caller's own precedence rules: explicit flag, then the active identity's default, then the global default. */
+    readonly baseConfigProfile?: string;
+    readonly loadProfile: ProfileLoader;
+    /** Directory levels, shallowest-first, as produced by `walkDirectoryAncestors`. */
+    readonly levels?: readonly DirectoryLevelSources[];
+    /** One-off overrides from the command line or environment, composed last so they beat everything. */
+    readonly cliOverride?: {
+        readonly categories?: Layer["categories"];
+        readonly entries?: Layer["entries"];
+        readonly entryOrder?: readonly string[];
+        readonly launch?: Layer["launch"];
+    };
+}
+/** The assembled cascade: an ordered layer sequence plus what the walk itself decided. */
+export interface AssembledCascade {
+    readonly layers: readonly Layer[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** The deepest directory-level `identity` pin encountered, which the launcher uses as a safety net beneath an explicit `@name`. */
+    readonly identityPin?: string;
+    /** The deepest directory-level `configProfile` selection encountered, which is what `agent-shim configure` treats as the active profile for a path. */
+    readonly directoryConfigProfile?: string;
+}
+/**
+ * Assembles the full ordered layer sequence.
+ *
+ * Order is: the user-global config, then the base configuration profile's own `extends` chain, then every directory level shallowest-to-deepest, then one-off command-line overrides.
+ *
+ * Within one directory level, up to three sources fold most-personal-last: the committed `.agent-shim.json` (team-shared), then this user's own `directory-rules.json` entries for that exact path, then `.agent-shim.local.json` (this clone, this user, never committed). That three-source fold happens once per level, and the whole shallowest-to-deepest walk is one continuous sequence through those folded levels — a deeper level's three-source result composes on top of a shallower level's, never gathered per-source across the whole tree first.
+ *
+ * A level source that names a `configProfile` composes that profile's whole chain in *before* its own inline overrides, so the source reads as "everything that profile says, plus what is additionally true this far down the tree" rather than swapping the base profile out wholesale.
+ */
+export declare function assembleCascade(input: CascadeInput): AssembledCascade;

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

@@ -0,0 +1,20 @@
+import { CliError } from "../cliError";
+import type { FarmFs } from "../launcher/ports";
+import { type AccountMetadata } from "./schema";
+/** Raised when an identity's `.claude.json` exists but cannot be read as account metadata (not a JSON object, or an `oauthAccount` field of an unexpected type): reported, never read as "no account". */
+export declare class AccountMetadataError extends CliError {
+    readonly file: string;
+    constructor(file: string, detail: string);
+}
+/** Whether `name` is a valid identity name, which is also what makes it safe as one path component under the identities and snapshots directories (no separator, no leading dot). */
+export declare function isIdentityName(name: string): boolean;
+/** The path of an identity's `.claude.json`. */
+export declare function claudeJsonPath(identitiesDir: string, identity: string): string;
+/**
+ * Reads an identity's account metadata from the `oauthAccount` block Claude Code writes into the identity's `.claude.json` when it logs in: the fields `AccountMetadataSchema` names and nothing else (the token is never in this file; Claude Code keeps it in the Keychain or `.credentials.json`). Undefined when the identity has no `.claude.json` or no `oauthAccount` (a setup-token identity, or one never logged in). Throws `AccountMetadataError` for a file that is not a JSON object, and on an invalid identity name, which could otherwise name a path outside the identities directory.
+ */
+export declare function readAccountMetadata(fs: Pick<FarmFs, "readFileUtf8">, identitiesDir: string, identity: string): AccountMetadata | undefined;
+/**
+ * An account reader for the long-running door: re-reads an identity's `.claude.json` only when its modification time or size has changed, since the door records every request and the file (which also holds Claude Code's per-project history) can be large while its account block rarely changes.
+ */
+export declare function createAccountReader(fs: Pick<FarmFs, "readFileUtf8" | "lstat">, identitiesDir: string): (identity: string) => AccountMetadata | undefined;

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

@@ -0,0 +1,70 @@
+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/schema.d.ts

@@ -0,0 +1,318 @@
+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<{
+        completed: "completed";
+        aborted: "aborted";
+    }>;
+    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 {};