@kill-switch/agent-guard 0.1.2 → 0.1.3

package/README.md

@@ -152,6 +152,10 @@ Tune the thresholds (0–1 utilization) if the defaults are too eager:
 | `--5h-soft` / `--5h-danger` | 5-hour warn / danger utilization | 0.7 / 0.9 |
 | `--burn-ratio` | pace multiplier that triggers a warning | 1.5 |
 
+The first time the proxy sees the `unified-*` headers it writes the raw values once to
+`~/.kill-switch/agent-guard/events.jsonl` (`kind: "unified-headers-observed"`) — so you can
+confirm Anthropic's exact value formats with a single `cat`.
+
 > Because subscription mode is alert-only, the "don't run both hook *and* proxy" caveat below
 > doesn't bite here — running Claude Code through the proxy is exactly what feeds the limit
 > headers, and dollars no longer gate anything.

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { dispatchAlert, type AlertEvent, type AlertLevel } from "./alert.js";
 export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
 export { runHook } from "./hook.js";
 export { buildStatusReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
-export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, WINDOW_MS, type LimitSnapshot, type WindowState, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, type LimitSnapshot, type WindowState, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, type PacingAssessment, type PacingLevel, type PacingThresholds, } from "./pacing.js";
 export { estimateSnapshot, isEstimated, TIER_BUDGETS, type PlanTier, type TierBudget, } from "./estimate.js";
 export { installHook, setBudget, setLimits, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, type LimitsPatch, } from "./ops.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { dispatchAlert } from "./alert.js";
 export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
 export { buildStatusReport, formatLimitsLines } from "./report.js";
-export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, WINDOW_MS, } from "./limits.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, } from "./pacing.js";
 export { estimateSnapshot, isEstimated, TIER_BUDGETS, } from "./estimate.js";
 export { installHook, setBudget, setLimits, resetLedger, } from "./ops.js";

package/dist/limits.d.ts

@@ -49,6 +49,8 @@ export interface LimitsState {
     snapshot: LimitSnapshot | null;
     /** Dedup flags so a given window/level/reset only alerts once. */
     notified: Record<string, boolean>;
+    /** Epoch ms we first logged the raw unified-* headers (write-once diagnostic). */
+    headersLoggedAt?: number;
 }
 /** Nominal window durations, used for pacing math when a reset time is unknown. */
 export declare const WINDOW_MS: Record<LimitWindow, number>;
@@ -81,3 +83,12 @@ export declare function parseReset(raw: string | null | undefined, now: number):
 export declare function parseUnifiedHeaders(h: HeaderGetter, now: number): LimitSnapshot | null;
 /** Stable dedup key for a pacing alert: re-alerts when the window resets. */
 export declare function limitNotifyKey(window: LimitWindow, level: string, resetAt: number | null): string;
+/**
+ * Pull every `anthropic-ratelimit-unified-*` header out of a raw record, verbatim.
+ * Used for the write-once diagnostic — Anthropic's value *formats* (fraction vs.
+ * percent, ISO vs. epoch reset) aren't fully documented, so capturing the raw
+ * strings the first time we see them makes verification a single `cat` away.
+ */
+export declare function unifiedHeaderDump(rec: Record<string, string | string[] | undefined>): Record<string, string>;
+/** Append a one-time raw-header diagnostic to events.jsonl. Best-effort, never throws. */
+export declare function logUnifiedHeaders(dump: Record<string, string>, now: number): void;

package/dist/limits.js

@@ -22,8 +22,8 @@
  * either a 0–1 fraction or a 0–100 percent; reset is accepted as an ISO 8601
  * timestamp, an epoch (s or ms), or a relative seconds-until-reset.
  */
-import { readFileSync, writeFileSync, renameSync } from "node:fs";
-import { limitsPath, ensureGuardDir } from "./config.js";
+import { readFileSync, writeFileSync, renameSync, appendFileSync } from "node:fs";
+import { limitsPath, eventsPath, ensureGuardDir } from "./config.js";
 /** Nominal window durations, used for pacing math when a reset time is unknown. */
 export const WINDOW_MS = {
     "5h": 5 * 60 * 60 * 1000,
@@ -41,6 +41,7 @@ export function loadLimitsState() {
                 subscriptionDetected: data.subscriptionDetected ?? false,
                 snapshot: data.snapshot ?? null,
                 notified: data.notified ?? {},
+                headersLoggedAt: data.headersLoggedAt,
             };
         }
     }
@@ -131,3 +132,30 @@ export function parseUnifiedHeaders(h, now) {
 export function limitNotifyKey(window, level, resetAt) {
     return `${window}:${level}:${resetAt ?? 0}`;
 }
+/**
+ * Pull every `anthropic-ratelimit-unified-*` header out of a raw record, verbatim.
+ * Used for the write-once diagnostic — Anthropic's value *formats* (fraction vs.
+ * percent, ISO vs. epoch reset) aren't fully documented, so capturing the raw
+ * strings the first time we see them makes verification a single `cat` away.
+ */
+export function unifiedHeaderDump(rec) {
+    const out = {};
+    for (const [k, v] of Object.entries(rec)) {
+        if (v == null)
+            continue;
+        const key = k.toLowerCase();
+        if (key.startsWith("anthropic-ratelimit-unified"))
+            out[key] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    return out;
+}
+/** Append a one-time raw-header diagnostic to events.jsonl. Best-effort, never throws. */
+export function logUnifiedHeaders(dump, now) {
+    try {
+        ensureGuardDir();
+        appendFileSync(eventsPath(), JSON.stringify({ ts: now, kind: "unified-headers-observed", headers: dump }) + "\n");
+    }
+    catch {
+        /* diagnostic only */
+    }
+}

package/dist/proxy.js

@@ -24,7 +24,7 @@ import { loadLedger, saveLedger, addSessionCost, rollingDailyCost, prune, } from
 import { evaluate } from "./budget.js";
 import { dispatchAlert } from "./alert.js";
 import { assertSafeEndpoint, warnIfUnexpectedHost } from "./net.js";
-import { parseUnifiedHeaders, loadLimitsState, saveLimitsState, limitNotifyKey, } from "./limits.js";
+import { parseUnifiedHeaders, recordHeaders, unifiedHeaderDump, logUnifiedHeaders, loadLimitsState, saveLimitsState, limitNotifyKey, } from "./limits.js";
 import { assessSnapshot, worstLevel } from "./pacing.js";
 const UPSTREAMS = {
     anthropic: "https://api.anthropic.com",
@@ -145,10 +145,20 @@ function meter(cfg, ledger, sessionId, parsed, now) {
  * the real wall).
  */
 function captureLimits(cfg, headers, sessionId, now) {
-    const snap = parseUnifiedHeaders(headers, now);
+    // Flatten to a lowercased record so we can both parse and dump the raw values.
+    const rec = {};
+    headers.forEach((v, k) => {
+        rec[k.toLowerCase()] = v;
+    });
+    const snap = parseUnifiedHeaders(recordHeaders(rec), now);
     if (!snap)
         return false;
     const state = loadLimitsState();
+    // Write-once raw-header diagnostic for format verification (`cat events.jsonl`).
+    if (!state.headersLoggedAt) {
+        logUnifiedHeaders(unifiedHeaderDump(rec), now);
+        state.headersLoggedAt = now;
+    }
     state.subscriptionDetected = true;
     state.snapshot = snap;
     const assessments = assessSnapshot(snap, cfg.limits, now);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Kill Switch for coding agents — stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM bill. Native hook + token-metering proxy with per-session and daily-rolling budgets.",
   "type": "module",
   "bin": {