@dzhechkov/harness-core 0.3.99 → 0.3.101

package/dist/usage.d.ts

@@ -1,70 +1,123 @@
 /**
  * `dz usage` data source — a READONLY, never-throw, best-effort estimate of Claude SESSION
- * (active 5h-block) and WEEKLY (rolling 7d) token usage, aggregated from the local Claude Code
- * transcript files under `~/.claude/projects/<munged>/<session>.jsonl`.
+ * and WEEKLY token usage, aggregated from the local Claude Code transcript files under
+ * `~/.claude/projects/<munged>/<session>.jsonl`.
  *
- * ## Honest-uncertainty contract (LOAD-BEARING — NFR-4)
+ * ## Honest-uncertainty contract (LOAD-BEARING)
  *
- * These percentages are **ESTIMATES** derived by aggregating local transcript token counts against
- * a USER-CONFIGURED limit. There is **no official usage API** being consulted — this is a fuel
- * gauge built from the flow meter, not a tank sensor. Therefore:
+ * These percentages are ESTIMATES derived by aggregating local transcript token counts against
+ * USER-CONFIGURED limits. There is no official Anthropic usage API being consulted; claude.ai is
+ * authoritative. Therefore:
  *
- * - Every payload carries `estimated: true` so a consumer can NEVER mistake it for ground truth.
- * - When a limit is **unconfigured** (`.dz/config.json` has no `memory.usage.sessionTokenLimit` /
- *   `weeklyTokenLimit`), the corresponding `pct` is `null` — **unknown, never 0, never a guess**.
- * - **Calibration protocol (observed-exhaustion):** when a real limit-hit occurs at an estimated
- *   `X%`, scale the configured limit by `X/100` so the next estimate lines up with reality. The
- *   4 token fields are summed with equal weight; the relative weighting (cache-read tokens
- *   dominate real transcripts) is absorbed into the calibrated limit value.
+ * - Every JSON payload emitted by the CLI carries `estimated: true`.
+ * - When a limit is unconfigured, the corresponding `pct` is `null` — unknown, never 0.
+ * - Weekly usage counts from a fixed configured reset anchor such as `Wed 08:59`, not from a
+ *   rolling seven-day window.
+ * - Session usage counts from the active fixed-length transcript block, not from a rolling
+ *   last-N-hours window.
  *
- * ## Statusline discipline (NFR-1)
+ * ## Statusline discipline
  *
  * Modeled on {@link ./statusline.ts} and {@link ./vector-tier.ts}'s `readVectorEngineMode`:
- * - **never-throw** — any error (missing `~/.claude/projects`, corrupt jsonl line, missing/corrupt
- *   config, garbled usage object) collapses to a value with `null` pcts, never an exception.
- * - **readonly** — zero writes/appends/mkdir/unlink anywhere (the optional aggregate cache in
- *   arch §2.2(6) is DEFERRED — v1 ships with zero writes so READONLY is trivially true).
- * - **<100ms steady-state** via an `mtime` prefilter: a file whose `mtime` is older than the weekly
- *   window cannot contribute and is skipped WITHOUT opening it; only files touched inside the
- *   session window are line-parsed for the active block.
- * - **injectable clock** — `computeUsage(root, now?)` takes an optional `now` (ms epoch) so all
- *   window math is deterministic under test.
+ * - never-throw — missing/corrupt config, transcript directories, and jsonl lines collapse to
+ *   best-effort zero/null values, never exceptions;
+ * - readonly — `computeUsage` performs zero writes;
+ * - bounded scanning via an mtime prefilter;
+ * - injectable clock — `computeUsage(root, now?)` takes an optional epoch-ms clock.
  *
  * @packageDocumentation
  */
+export declare const CLAUDE_USAGE_MODELS: readonly ["fable", "opus", "sonnet", "haiku"];
+export type ClaudeUsageModel = (typeof CLAUDE_USAGE_MODELS)[number];
+export interface UsageWindow {
+    readonly startedAtMs: number;
+    readonly resetsAtMs: number;
+}
+export interface WeeklyResetAnchor {
+    readonly weekday: number;
+    readonly hour: number;
+    readonly minute: number;
+}
 /** Optional, plan-dependent calibration limits from `.dz/config.json`. Absent ⇒ pct is `null`. */
 export interface UsageLimits {
     readonly sessionTokenLimit?: number;
     readonly weeklyTokenLimit?: number;
+    readonly weeklyTokenLimitByModel?: Partial<Record<ClaudeUsageModel, number>>;
+    readonly weeklyResetAnchor?: string;
+    readonly sessionBlockHours?: number;
+    readonly calibratedAt?: string;
+    readonly source?: string;
+}
+export interface UsageModelEstimate {
+    readonly tokens: number;
+    readonly pct: number | null;
 }
 /** A never-throw usage estimate. `estimated` is ALWAYS `true` (honest-uncertainty marker). */
 export interface UsageEstimate {
-    /** Active 5h-block token total (all projects). `0` when there is no active block. */
+    /** Active fixed-length session block token total (all projects). */
     readonly sessionTokens: number;
-    /** Rolling 7d token total (all projects). */
+    /** Fixed weekly-reset-window token total (all projects). */
     readonly weeklyTokens: number;
-    /** `null` ⇔ `sessionTokenLimit` unconfigured (unknown — never 0). */
+    /** `null` ⇔ `sessionTokenLimit` unconfigured (unknown — never a guess). */
     readonly sessionPct: number | null;
-    /** `null` ⇔ `weeklyTokenLimit` unconfigured (unknown — never 0). */
+    /** Binding weekly pct: per-model max when configured, otherwise all-model aggregate. */
     readonly weeklyPct: number | null;
-    /** ISO — active block start + 5h; `null` when there is no active block. */
+    /** ISO — active block start + configured session hours; `null` when there is no active block. */
     readonly sessionResetsAt: string | null;
-    /** ISO — oldest in-window sample ts + 7d (estimate); `null` when the weekly window is empty. */
+    /** ISO — next configured fixed weekly reset. */
     readonly weeklyResetsAt: string | null;
     /** ALWAYS `true` — these are estimates from local aggregation, not an official API. */
     readonly estimated: true;
+    /** Present only when per-model weekly limits are configured. */
+    readonly weeklyByModel?: Partial<Record<ClaudeUsageModel, UsageModelEstimate>>;
+    /** Raw weekly model totals for calibration; CLI omits this from the compatibility JSON. */
+    readonly weeklyTokensByModel: Partial<Record<ClaudeUsageModel, number>>;
+    /** Model family that supplied the binding top-level weeklyPct, if any. */
+    readonly weeklyBindingModel?: ClaudeUsageModel;
+    /** Traceability for tests and calibration diagnostics. */
+    readonly sessionStartedAt: string | null;
+    readonly weeklyStartedAt: string | null;
+}
+export interface UsageCalibrationInput {
+    readonly sessionPct?: unknown;
+    readonly weeklyPct?: unknown;
+    readonly modelPct?: Readonly<Record<string, unknown>>;
+    readonly calibratedAt: string;
+    readonly source: 'claude.ai/settings/usage';
 }
+export interface UsageCalibrationChange {
+    readonly key: string;
+    readonly before: number | null;
+    readonly after: number;
+    readonly tokens: number;
+    readonly pct: number;
+}
+export interface UsageCalibrationPlan {
+    readonly before: UsageLimits;
+    readonly after: UsageLimits;
+    readonly changes: readonly UsageCalibrationChange[];
+    readonly skipped: readonly string[];
+}
+export declare function parseWeeklyResetAnchor(anchor: string): WeeklyResetAnchor | null;
+export declare function weeklyWindowFor(nowMs: number, anchor: string): UsageWindow | null;
+/**
+ * A simple fixed-duration grid helper kept exported for pure date-math tests. `computeUsage` uses
+ * transcript-established session blocks per the feature requirements because no account-specific
+ * session anchor is stored today.
+ */
+export declare function fixedBlockWindowFor(nowMs: number, blockHours: number): UsageWindow | null;
+export declare function normalizeClaudeUsageModel(raw: unknown): ClaudeUsageModel | null;
+export declare function normalizeClaudeUsageModelKey(raw: unknown): ClaudeUsageModel | null;
 /**
- * Read `memory.usage.{sessionTokenLimit,weeklyTokenLimit}` from `<projectRoot>/.dz/config.json`.
- * NEVER throws — absent/corrupt/partial config ⇒ `{}` (⇒ pct `null`). Mirrors the
- * `readVectorEngineMode` never-throw shape exactly. `projectRoot` is the ONLY thing that scopes to
- * a project; the MEASUREMENT below is account-wide (FR-1.6).
+ * Read `memory.usage.*` from `<projectRoot>/.dz/config.json`. NEVER throws —
+ * absent/corrupt/partial config ⇒ `{}` or only valid fields.
  */
 export declare function readUsageLimits(projectRoot: string): UsageLimits;
 /**
  * Estimate SESSION + WEEKLY token usage from the local Claude transcript store. NEVER throws;
- * READONLY; `<100ms` steady-state via the `mtime` prefilter. `projectRoot` scopes ONLY the config
- * (limits) read — measurement is account-wide (all projects). `now` is injectable for tests.
+ * READONLY; `projectRoot` scopes ONLY the config (limits) read — measurement is account-wide
+ * (all projects). `now` is injectable for tests.
  */
 export declare function computeUsage(projectRoot: string, now?: number): UsageEstimate;
+export declare function deriveUsageCalibration(current: UsageEstimate, before: UsageLimits, input: UsageCalibrationInput): UsageCalibrationPlan;
 //# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAaH,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAaD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAgBhE;AAsID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CA8C7E"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}