claude-use 5.1.1 → 5.3.0

package/dist/index.cjs

@@ -37,6 +37,8 @@ __export(index_exports, {
   FrontDoorStartError: () => FrontDoorStartError,
   HeadroomStartError: () => HeadroomStartError,
   ROUTED_PATH_PREFIX: () => ROUTED_PATH_PREFIX,
+  UsageSnapshotError: () => UsageSnapshotError,
+  UsageSnapshotSchema: () => UsageSnapshotSchema,
   buildEntryFacts: () => buildEntryFacts,
   carryOver: () => carryOver,
   createLeafCache: () => createLeafCache,
@@ -49,9 +51,11 @@ __export(index_exports, {
   forwardableHeaders: () => forwardableHeaders,
   generateCa: () => generateCa,
   isInterceptedHost: () => isInterceptedHost,
+  listUsageSnapshots: () => listUsageSnapshots,
   mintLeaf: () => mintLeaf,
   parseConnectTarget: () => parseConnectTarget,
   readFarmManifest: () => readFarmManifest,
+  readUsageSnapshot: () => readUsageSnapshot,
   realConnectCertStore: () => realConnectCertStore,
   realConnectEffects: () => realConnectEffects,
   recoverFarm: () => recoverFarm,
@@ -62,6 +66,7 @@ __export(index_exports, {
   runFrontDoorSupervisor: () => runFrontDoorSupervisor,
   runSupervisor: () => runSupervisor,
   servedByPipeline: () => servedByPipeline,
+  snapshotPath: () => snapshotPath,
   startConnectServer: () => startConnectServer,
   topLevelNames: () => topLevelNames
 });
@@ -2346,8 +2351,8 @@ function parseConnectTarget(authority) {
 function isInterceptedHost(host, interceptHost) {
   return host === interceptHost;
 }
-function servedByPipeline(path7) {
-  return path7?.startsWith(ROUTED_PATH_PREFIX) === true;
+function servedByPipeline(path8) {
+  return path8?.startsWith(ROUTED_PATH_PREFIX) === true;
 }
 var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
   "connection",
@@ -2952,6 +2957,183 @@ function ensureFrontDoor(params) {
   }
 }
 
+// src/usage/read.ts
+var import_node_path7 = __toESM(require("node:path"), 1);
+
+// src/usage/schema.ts
+var import_zod5 = require("zod");
+var USAGE_SCHEMA_VERSION = 1;
+var VersionSchema = import_zod5.z.literal(USAGE_SCHEMA_VERSION);
+var InstantSchema = import_zod5.z.iso.datetime();
+var TokenCountSchema = import_zod5.z.number().int().nonnegative();
+var TokenUsageSchema = import_zod5.z.strictObject({
+  inputTokens: TokenCountSchema.optional(),
+  outputTokens: TokenCountSchema.optional(),
+  cacheCreationInputTokens: TokenCountSchema.optional(),
+  cacheReadInputTokens: TokenCountSchema.optional()
+});
+var LIMIT_KINDS = ["rate-limited", "quota-exhausted"];
+var LimitClassificationSchema = import_zod5.z.strictObject({
+  kind: import_zod5.z.enum(LIMIT_KINDS),
+  /** Seconds to wait before retrying, from the response's `retry-after`. */
+  retryAfterSeconds: import_zod5.z.number().nonnegative().optional(),
+  /** When the limiting window resets, from the upstream's own reset header. */
+  resetAt: InstantSchema.optional(),
+  /** The window the upstream named as the binding one (`anthropic-ratelimit-unified-representative-claim`), such as `five_hour` or `seven_day`. */
+  window: import_zod5.z.string().optional(),
+  /** The signals the classification rests on, each `<name>=<value>` from a response header or the error body's `type` or `code`. Never the error message. */
+  evidence: import_zod5.z.array(import_zod5.z.string())
+});
+var UsageRecordSchema = import_zod5.z.strictObject({
+  schemaVersion: VersionSchema,
+  /** When the front door received the request. */
+  at: InstantSchema,
+  /** The launching identity, when the launch resolved one. */
+  identity: import_zod5.z.string().optional(),
+  /** `anthropic` for an OAuth session's request to Claude Code's own API, otherwise the provider's name. */
+  provider: import_zod5.z.string(),
+  /** The launch's session id, generated per launch. */
+  sessionId: import_zod5.z.string().optional(),
+  /** The project the launch ran in (its git repository root), when the launch sent one: headroom launches do. */
+  project: import_zod5.z.string().optional(),
+  /** The front-door route that served the request. */
+  route: import_zod5.z.string(),
+  method: import_zod5.z.string(),
+  /** The API path as the upstream sees it (`/v1/messages`), without the provider prefix or a query string. */
+  endpoint: import_zod5.z.string(),
+  /** The model the response named. */
+  model: import_zod5.z.string().optional(),
+  status: import_zod5.z.number().int(),
+  /** Milliseconds from the request's arrival to its response head. */
+  latencyMs: import_zod5.z.number().int().nonnegative(),
+  /** Milliseconds from the request's arrival to the end of its response body. */
+  durationMs: import_zod5.z.number().int().nonnegative(),
+  /** Whether the client received the whole body. */
+  outcome: import_zod5.z.enum(["completed", "aborted"]),
+  usage: TokenUsageSchema.optional(),
+  /** The response's quota and rate-limit headers, by name (see `isRateLimitHeader`). */
+  rateLimitHeaders: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.string()).optional(),
+  limit: LimitClassificationSchema.optional(),
+  /** The upstream's request id (`request-id`), for matching a record to the provider's own logs. */
+  requestId: import_zod5.z.string().optional()
+});
+var QuotaWindowSchema = import_zod5.z.strictObject({
+  /** The fraction of the window used, as the upstream reports it (0 to 1). */
+  utilization: import_zod5.z.number().nonnegative().optional(),
+  resetsAt: InstantSchema.optional(),
+  /** The window's own status (`allowed`, `allowed_warning`, `rejected`). */
+  status: import_zod5.z.string().optional()
+});
+var UnifiedRateLimitSchema = import_zod5.z.strictObject({
+  /** The overall status: `allowed`, `allowed_warning` or `rejected`. */
+  status: import_zod5.z.string().optional(),
+  fiveHour: QuotaWindowSchema.optional(),
+  sevenDay: QuotaWindowSchema.optional(),
+  /** The window that currently binds. */
+  representativeClaim: import_zod5.z.string().optional(),
+  /** When the binding window resets. */
+  resetAt: InstantSchema.optional(),
+  /** Whether usage beyond the plan (extra usage) is available: `allowed` or `rejected`. */
+  overageStatus: import_zod5.z.string().optional()
+});
+var RateLimitStateSchema = import_zod5.z.strictObject({
+  observedAt: InstantSchema,
+  /** Every quota and rate-limit header on that response, by name. */
+  headers: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.string()),
+  unified: UnifiedRateLimitSchema.optional()
+});
+var LimitEventSchema = LimitClassificationSchema.extend({
+  observedAt: InstantSchema,
+  status: import_zod5.z.number().int()
+});
+var ProviderUsageStateSchema = import_zod5.z.strictObject({
+  lastRequestAt: InstantSchema,
+  lastStatus: import_zod5.z.number().int(),
+  lastModel: import_zod5.z.string().optional(),
+  /** The latest rate-limit state, from the last response that carried any rate-limit header. */
+  rateLimit: RateLimitStateSchema.optional(),
+  /** The latest classified refusal. It stays after later successes, so a reader compares its `resetAt` (or `observedAt` plus `retryAfterSeconds`) with the current time. */
+  lastLimit: LimitEventSchema.optional()
+});
+var AccountMetadataSchema = import_zod5.z.strictObject({
+  accountUuid: import_zod5.z.string().optional(),
+  emailAddress: import_zod5.z.string().optional(),
+  displayName: import_zod5.z.string().optional(),
+  organizationUuid: import_zod5.z.string().optional(),
+  organizationName: import_zod5.z.string().optional(),
+  organizationType: import_zod5.z.string().optional(),
+  organizationRole: import_zod5.z.string().optional(),
+  workspaceRole: import_zod5.z.string().optional(),
+  billingType: import_zod5.z.string().optional(),
+  seatTier: import_zod5.z.string().optional(),
+  organizationRateLimitTier: import_zod5.z.string().optional(),
+  userRateLimitTier: import_zod5.z.string().optional(),
+  hasExtraUsageEnabled: import_zod5.z.boolean().optional(),
+  subscriptionCreatedAt: import_zod5.z.string().optional(),
+  accountCreatedAt: import_zod5.z.string().optional()
+});
+var UsageSnapshotSchema = import_zod5.z.strictObject({
+  schemaVersion: VersionSchema,
+  identity: import_zod5.z.string(),
+  updatedAt: InstantSchema,
+  /** The identity's account metadata as of `updatedAt`. */
+  account: AccountMetadataSchema.optional(),
+  /** Latest state per provider, keyed by provider name (`anthropic` for OAuth sessions). */
+  providers: import_zod5.z.record(import_zod5.z.string(), ProviderUsageStateSchema)
+});
+
+// src/usage/account.ts
+function isIdentityName(name) {
+  return IdentitySchema.shape.name.safeParse(name).success;
+}
+
+// src/usage/read.ts
+var UsageSnapshotError = class extends Error {
+  constructor(file, detail) {
+    super(`${file} is not a usage snapshot this claude-use can read (schema version ${String(USAGE_SCHEMA_VERSION)}): ${detail}`);
+    this.file = file;
+    this.name = "UsageSnapshotError";
+  }
+  file;
+};
+function snapshotPath(snapshotsDir, identity) {
+  if (!isIdentityName(identity)) {
+    throw new Error(`"${identity}" is not a valid identity name.`);
+  }
+  return import_node_path7.default.join(snapshotsDir, `${identity}.json`);
+}
+function readUsageSnapshot(fs2, snapshotsDir, identity) {
+  const file = snapshotPath(snapshotsDir, identity);
+  const raw = fs2.readFileUtf8(file);
+  if (raw === void 0) {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new UsageSnapshotError(file, "not valid JSON");
+  }
+  const snapshot = UsageSnapshotSchema.safeParse(parsed);
+  if (!snapshot.success) {
+    throw new UsageSnapshotError(file, snapshot.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+  }
+  return snapshot.data;
+}
+function listUsageSnapshots(fs2, snapshotsDir) {
+  return fs2.readdir(snapshotsDir).flatMap((name) => {
+    if (!name.endsWith(".json")) {
+      return [];
+    }
+    const identity = name.slice(0, -".json".length);
+    if (!isIdentityName(identity)) {
+      return [];
+    }
+    const snapshot = readUsageSnapshot(fs2, snapshotsDir, identity);
+    return snapshot === void 0 ? [] : [snapshot];
+  }).sort((left, right) => left.identity.localeCompare(right.identity));
+}
+
 // src/headroom/ensure.ts
 var HEADROOM_START_TIMEOUT_MS = 12e4;
 var HEADROOM_LAUNCHER_POLL_MS = 250;
@@ -3326,6 +3508,8 @@ function evaluateAmbientCredentialGuard(params) {
   FrontDoorStartError,
   HeadroomStartError,
   ROUTED_PATH_PREFIX,
+  UsageSnapshotError,
+  UsageSnapshotSchema,
   buildEntryFacts,
   carryOver,
   createLeafCache,
@@ -3338,9 +3522,11 @@ function evaluateAmbientCredentialGuard(params) {
   forwardableHeaders,
   generateCa,
   isInterceptedHost,
+  listUsageSnapshots,
   mintLeaf,
   parseConnectTarget,
   readFarmManifest,
+  readUsageSnapshot,
   realConnectCertStore,
   realConnectEffects,
   recoverFarm,
@@ -3351,6 +3537,7 @@ function evaluateAmbientCredentialGuard(params) {
   runFrontDoorSupervisor,
   runSupervisor,
   servedByPipeline,
+  snapshotPath,
   startConnectServer,
   topLevelNames
 });

package/dist/index.mjs

@@ -2277,8 +2277,8 @@ function parseConnectTarget(authority) {
 function isInterceptedHost(host, interceptHost) {
   return host === interceptHost;
 }
-function servedByPipeline(path7) {
-  return path7?.startsWith(ROUTED_PATH_PREFIX) === true;
+function servedByPipeline(path8) {
+  return path8?.startsWith(ROUTED_PATH_PREFIX) === true;
 }
 var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
   "connection",
@@ -2883,6 +2883,183 @@ function ensureFrontDoor(params) {
   }
 }
 
+// src/usage/read.ts
+import path7 from "node:path";
+
+// src/usage/schema.ts
+import { z as z5 } from "zod";
+var USAGE_SCHEMA_VERSION = 1;
+var VersionSchema = z5.literal(USAGE_SCHEMA_VERSION);
+var InstantSchema = z5.iso.datetime();
+var TokenCountSchema = z5.number().int().nonnegative();
+var TokenUsageSchema = z5.strictObject({
+  inputTokens: TokenCountSchema.optional(),
+  outputTokens: TokenCountSchema.optional(),
+  cacheCreationInputTokens: TokenCountSchema.optional(),
+  cacheReadInputTokens: TokenCountSchema.optional()
+});
+var LIMIT_KINDS = ["rate-limited", "quota-exhausted"];
+var LimitClassificationSchema = z5.strictObject({
+  kind: z5.enum(LIMIT_KINDS),
+  /** Seconds to wait before retrying, from the response's `retry-after`. */
+  retryAfterSeconds: z5.number().nonnegative().optional(),
+  /** When the limiting window resets, from the upstream's own reset header. */
+  resetAt: InstantSchema.optional(),
+  /** The window the upstream named as the binding one (`anthropic-ratelimit-unified-representative-claim`), such as `five_hour` or `seven_day`. */
+  window: z5.string().optional(),
+  /** The signals the classification rests on, each `<name>=<value>` from a response header or the error body's `type` or `code`. Never the error message. */
+  evidence: z5.array(z5.string())
+});
+var UsageRecordSchema = z5.strictObject({
+  schemaVersion: VersionSchema,
+  /** When the front door received the request. */
+  at: InstantSchema,
+  /** The launching identity, when the launch resolved one. */
+  identity: z5.string().optional(),
+  /** `anthropic` for an OAuth session's request to Claude Code's own API, otherwise the provider's name. */
+  provider: z5.string(),
+  /** The launch's session id, generated per launch. */
+  sessionId: z5.string().optional(),
+  /** The project the launch ran in (its git repository root), when the launch sent one: headroom launches do. */
+  project: z5.string().optional(),
+  /** The front-door route that served the request. */
+  route: z5.string(),
+  method: z5.string(),
+  /** The API path as the upstream sees it (`/v1/messages`), without the provider prefix or a query string. */
+  endpoint: z5.string(),
+  /** The model the response named. */
+  model: z5.string().optional(),
+  status: z5.number().int(),
+  /** Milliseconds from the request's arrival to its response head. */
+  latencyMs: z5.number().int().nonnegative(),
+  /** Milliseconds from the request's arrival to the end of its response body. */
+  durationMs: z5.number().int().nonnegative(),
+  /** Whether the client received the whole body. */
+  outcome: z5.enum(["completed", "aborted"]),
+  usage: TokenUsageSchema.optional(),
+  /** The response's quota and rate-limit headers, by name (see `isRateLimitHeader`). */
+  rateLimitHeaders: z5.record(z5.string(), z5.string()).optional(),
+  limit: LimitClassificationSchema.optional(),
+  /** The upstream's request id (`request-id`), for matching a record to the provider's own logs. */
+  requestId: z5.string().optional()
+});
+var QuotaWindowSchema = z5.strictObject({
+  /** The fraction of the window used, as the upstream reports it (0 to 1). */
+  utilization: z5.number().nonnegative().optional(),
+  resetsAt: InstantSchema.optional(),
+  /** The window's own status (`allowed`, `allowed_warning`, `rejected`). */
+  status: z5.string().optional()
+});
+var UnifiedRateLimitSchema = z5.strictObject({
+  /** The overall status: `allowed`, `allowed_warning` or `rejected`. */
+  status: z5.string().optional(),
+  fiveHour: QuotaWindowSchema.optional(),
+  sevenDay: QuotaWindowSchema.optional(),
+  /** The window that currently binds. */
+  representativeClaim: z5.string().optional(),
+  /** When the binding window resets. */
+  resetAt: InstantSchema.optional(),
+  /** Whether usage beyond the plan (extra usage) is available: `allowed` or `rejected`. */
+  overageStatus: z5.string().optional()
+});
+var RateLimitStateSchema = z5.strictObject({
+  observedAt: InstantSchema,
+  /** Every quota and rate-limit header on that response, by name. */
+  headers: z5.record(z5.string(), z5.string()),
+  unified: UnifiedRateLimitSchema.optional()
+});
+var LimitEventSchema = LimitClassificationSchema.extend({
+  observedAt: InstantSchema,
+  status: z5.number().int()
+});
+var ProviderUsageStateSchema = z5.strictObject({
+  lastRequestAt: InstantSchema,
+  lastStatus: z5.number().int(),
+  lastModel: z5.string().optional(),
+  /** The latest rate-limit state, from the last response that carried any rate-limit header. */
+  rateLimit: RateLimitStateSchema.optional(),
+  /** The latest classified refusal. It stays after later successes, so a reader compares its `resetAt` (or `observedAt` plus `retryAfterSeconds`) with the current time. */
+  lastLimit: LimitEventSchema.optional()
+});
+var AccountMetadataSchema = z5.strictObject({
+  accountUuid: z5.string().optional(),
+  emailAddress: z5.string().optional(),
+  displayName: z5.string().optional(),
+  organizationUuid: z5.string().optional(),
+  organizationName: z5.string().optional(),
+  organizationType: z5.string().optional(),
+  organizationRole: z5.string().optional(),
+  workspaceRole: z5.string().optional(),
+  billingType: z5.string().optional(),
+  seatTier: z5.string().optional(),
+  organizationRateLimitTier: z5.string().optional(),
+  userRateLimitTier: z5.string().optional(),
+  hasExtraUsageEnabled: z5.boolean().optional(),
+  subscriptionCreatedAt: z5.string().optional(),
+  accountCreatedAt: z5.string().optional()
+});
+var UsageSnapshotSchema = z5.strictObject({
+  schemaVersion: VersionSchema,
+  identity: z5.string(),
+  updatedAt: InstantSchema,
+  /** The identity's account metadata as of `updatedAt`. */
+  account: AccountMetadataSchema.optional(),
+  /** Latest state per provider, keyed by provider name (`anthropic` for OAuth sessions). */
+  providers: z5.record(z5.string(), ProviderUsageStateSchema)
+});
+
+// src/usage/account.ts
+function isIdentityName(name) {
+  return IdentitySchema.shape.name.safeParse(name).success;
+}
+
+// src/usage/read.ts
+var UsageSnapshotError = class extends Error {
+  constructor(file, detail) {
+    super(`${file} is not a usage snapshot this claude-use can read (schema version ${String(USAGE_SCHEMA_VERSION)}): ${detail}`);
+    this.file = file;
+    this.name = "UsageSnapshotError";
+  }
+  file;
+};
+function snapshotPath(snapshotsDir, identity) {
+  if (!isIdentityName(identity)) {
+    throw new Error(`"${identity}" is not a valid identity name.`);
+  }
+  return path7.join(snapshotsDir, `${identity}.json`);
+}
+function readUsageSnapshot(fs2, snapshotsDir, identity) {
+  const file = snapshotPath(snapshotsDir, identity);
+  const raw = fs2.readFileUtf8(file);
+  if (raw === void 0) {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new UsageSnapshotError(file, "not valid JSON");
+  }
+  const snapshot = UsageSnapshotSchema.safeParse(parsed);
+  if (!snapshot.success) {
+    throw new UsageSnapshotError(file, snapshot.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+  }
+  return snapshot.data;
+}
+function listUsageSnapshots(fs2, snapshotsDir) {
+  return fs2.readdir(snapshotsDir).flatMap((name) => {
+    if (!name.endsWith(".json")) {
+      return [];
+    }
+    const identity = name.slice(0, -".json".length);
+    if (!isIdentityName(identity)) {
+      return [];
+    }
+    const snapshot = readUsageSnapshot(fs2, snapshotsDir, identity);
+    return snapshot === void 0 ? [] : [snapshot];
+  }).sort((left, right) => left.identity.localeCompare(right.identity));
+}
+
 // src/headroom/ensure.ts
 var HEADROOM_START_TIMEOUT_MS = 12e4;
 var HEADROOM_LAUNCHER_POLL_MS = 250;
@@ -3256,6 +3433,8 @@ export {
   FrontDoorStartError,
   HeadroomStartError,
   ROUTED_PATH_PREFIX,
+  UsageSnapshotError,
+  UsageSnapshotSchema,
   buildEntryFacts,
   carryOver,
   createLeafCache,
@@ -3268,9 +3447,11 @@ export {
   forwardableHeaders,
   generateCa,
   isInterceptedHost,
+  listUsageSnapshots,
   mintLeaf,
   parseConnectTarget,
   readFarmManifest,
+  readUsageSnapshot,
   realConnectCertStore,
   realConnectEffects,
   recoverFarm,
@@ -3281,6 +3462,7 @@ export {
   runFrontDoorSupervisor,
   runSupervisor,
   servedByPipeline,
+  snapshotPath,
   startConnectServer,
   topLevelNames
 };

package/dist/types/index.d.ts

@@ -1,9 +1,10 @@
 /**
- * The library surface of claude-use: the pure, port-injected parts other tools can call in-process instead of shelling out to the CLI. Three groups, none of which imports interactive prompting or argument parsing:
+ * The library surface of claude-use: the pure, port-injected parts other tools can call in-process instead of shelling out to the CLI. Four groups, none of which imports interactive prompting or argument parsing:
  *
  * - identity and configuration-profile resolution and farm sync (`resolveDecisions`, `resyncFarm`, `buildEntryFacts`, ...), pure over facts and ports passed in;
  * - routing: the front door's Remote-Control-preserving, capability-authenticated CONNECT surface and its certificate authority, the front-door supervisor and ensure lifecycle, and the headroom supervisor and ensure lifecycle, each pure over its injected ports;
- * - the ambient-credential guard.
+ * - the ambient-credential guard;
+ * - the per-identity usage snapshot a statusline or launcher reads: its schema and the reader over an injected filesystem.
  *
  * Everything the CLI alone needs (commander wiring, prompts, `doctor`, `check`) is deliberately not exported here.
  */
@@ -13,6 +14,8 @@ export { buildEntryFacts, carryOver, FARM_MANIFEST_FILENAME, readFarmManifest, r
 export { CONNECT_INTERCEPT_HOST, CONNECT_LIMITS, createLeafCache, ensureCa, forwardableHeaders, generateCa, isInterceptedHost, mintLeaf, parseConnectTarget, realConnectCertStore, realConnectEffects, ROUTED_PATH_PREFIX, servedByPipeline, startConnectServer, type CaMaterial, type ConnectCertStore, type ConnectEffects, type ConnectLimits, type ConnectServerConfig, type ConnectServerHandle, type ConnectTarget, type LeafCert, } from "./frontdoor/connect";
 export { ensureFrontDoor, FrontDoorStartError, type EnsureFrontDoorPorts } from "./frontdoor/ensure";
 export { runFrontDoorSupervisor, type FrontDoorSupervisorPorts, type RunFrontDoorSupervisorOptions } from "./frontdoor/supervisor";
+export { listUsageSnapshots, readUsageSnapshot, snapshotPath, UsageSnapshotError, type UsageReadFs } from "./usage/read";
+export { UsageSnapshotSchema, type UsageSnapshot } from "./usage/schema";
 export { ensureHeadroom, HeadroomStartError, type EnsureHeadroomPorts } from "./headroom/ensure";
 export { resolveSupervisorConfig, runSupervisor, type HeadroomSupervisorConfig, type RunSupervisorOptions, type SupervisorPorts } from "./headroom/supervisor";
 export { AMBIENT_CREDENTIAL_VARS, detectAmbientCredential, evaluateAmbientCredentialGuard, formatAmbientCredentialGuardMessage, type AmbientCredentialDetection, type AmbientCredentialGuardResult, type AmbientCredentialVar, type EvaluateAmbientCredentialGuardParams, type InjectedCredential, } from "./launcher/guard";

package/dist/types/launcher/ports.d.ts

@@ -46,6 +46,8 @@ export interface FarmFs {
     readonly mkdirPrivate: (path: string) => void;
     /** Writes a file's full contents as UTF-8 text readable only by its owner (mode 0600), atomically: a temporary sibling is written at that mode and renamed into place, so no reader ever sees a partial file or a wider mode. */
     readonly writeFilePrivate: (path: string, contents: string) => void;
+    /** Appends UTF-8 text to a file readable only by its owner (mode 0600), creating it at that mode when it is missing and narrowing an existing wider mode. The file is opened in append mode, so the text always lands at the end however the file grew; a reader running at the same moment can still see a trailing partial write. It is the primitive an append-only log with one writer per file is built on. */
+    readonly appendFilePrivate: (path: string, contents: string) => void;
     /** Creates a file only if it does not already exist, returning false when it does. This is the exclusive-create the identity lock depends on for its mutual exclusion — a read-then-write pair would race. */
     readonly writeFileExclusive: (path: string, contents: string) => boolean;
     /** A stable content hash of one file, or undefined when it is missing or is not a regular file. Used only to recognise farm data that has already been adopted into the canonical tree. */

package/dist/types/paths.d.ts

@@ -52,6 +52,12 @@ export interface LayoutPaths {
     readonly frontdoorSessionsDir: string;
     /** Path to the front door's log: one line per lifecycle event and routed failure, never a token. */
     readonly frontdoorLogPath: string;
+    /** Directory holding the usage store, mode 0700: the request log and the per-identity snapshots. Metadata only, never content or credentials. */
+    readonly usageDir: string;
+    /** Directory of the append-only usage log: one `<YYYY-MM-DD>.<writer-pid>.jsonl` segment per writing process per UTC day. */
+    readonly usageLogDir: string;
+    /** Directory of the latest-state snapshots, one `<identity>.json` per identity: the stable file other tools read. */
+    readonly usageSnapshotsDir: string;
 }
 /**
  * Resolves the current CLAUDE_USE_HOME root: the environment variable when set to a non-empty string, otherwise `~/.claude-use`. An empty string counts as unset, consistent with how this project treats empty-string environment variables elsewhere (see the ambient-credential guard).

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 claude-use 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 {};