harnery 0.6.0 → 0.7.1

package/dist/core/hooks/harness/events.js

@@ -37,19 +37,35 @@ export const CURSOR_EVENTS = [
     { settingsKey: "beforeSubmitPrompt", subcommand: "user-prompt-submit" },
     { settingsKey: "stop", subcommand: "stop" },
 ];
-/** Codex: `.codex/hooks.json`. PascalCase keys + the same entry shape as Claude Code. */
+/** Codex events that harnery uses from the current native lifecycle surface. */
 export const CODEX_EVENTS = [
     { settingsKey: "SessionStart", subcommand: "session-start" },
-    { settingsKey: "SessionEnd", subcommand: "session-end" },
     { settingsKey: "PreToolUse", subcommand: "pre-tool-use" },
     { settingsKey: "PostToolUse", subcommand: "post-tool-use" },
-    { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
     { settingsKey: "UserPromptSubmit", subcommand: "user-prompt-submit" },
     { settingsKey: "SubagentStart", subcommand: "sub-agent-start" },
     { settingsKey: "SubagentStop", subcommand: "sub-agent-stop" },
     { settingsKey: "Stop", subcommand: "stop" },
+];
+/** Entries written by harnery before Codex adopted a strict native hook schema. */
+export const LEGACY_CODEX_EVENTS = [
+    { settingsKey: "SessionEnd", subcommand: "session-end" },
+    { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
     { settingsKey: "StopFailure", subcommand: "stop-failure" },
 ];
+/** Every hook key accepted by Codex 0.144, including events harnery does not consume. */
+export const CODEX_ALLOWED_EVENT_KEYS = [
+    "SessionStart",
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "UserPromptSubmit",
+    "SubagentStart",
+    "SubagentStop",
+    "Stop",
+];
 /** Every supported harness, fully wireable by `harn init`. */
 export const HARNESS_SPECS = {
     "claude-code": {
@@ -67,5 +83,8 @@ export const HARNESS_SPECS = {
         settingsFile: ".codex/hooks.json",
         events: CODEX_EVENTS,
         entryShape: "claude",
+        legacyEvents: LEGACY_CODEX_EVENTS,
+        allowedTopLevelKeys: ["description", "hooks"],
+        allowedEventKeys: CODEX_ALLOWED_EVENT_KEYS,
     },
 };

package/dist/core/hooks/harness/wiring.d.ts

@@ -28,6 +28,7 @@ export interface CursorHookGroup {
 export type HookGroup = ClaudeHookGroup | CursorHookGroup;
 export interface SettingsFile {
     version?: number;
+    description?: string;
     hooks?: Record<string, HookGroup[]>;
     [k: string]: unknown;
 }
@@ -51,6 +52,10 @@ export interface WiringDiff {
      * these — they need explicit removal — so they're surfaced separately.
      */
     orphans: string[];
+    /** Settings fields rejected by a harness with a strict top-level schema. */
+    invalidTopLevelKeys: string[];
+    /** Hook event names rejected by a harness with a strict event schema. */
+    invalidEventKeys: string[];
 }
 /**
  * Pure diff of one settings object against one harness spec. Read-only inverse
@@ -63,6 +68,9 @@ export interface HarnessWiringStatus {
     settingsFile: string;
     missing: HookEvent[];
     orphans: string[];
+    invalidTopLevelKeys: string[];
+    invalidEventKeys: string[];
+    parseError?: string;
 }
 /**
  * Inspect every harness whose settings file exists under `projectRoot` and

package/dist/core/hooks/harness/wiring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AACD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,eAAe,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAMxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnF;AAQD,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA0BhF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwB5E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAkBvC"}
+{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AACD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,eAAe,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAMxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnF;AAQD,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA2ChF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwC5E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAkBvC"}

package/dist/core/hooks/harness/wiring.js

@@ -65,7 +65,23 @@ export function diffWiring(settings, spec) {
             }
         }
     }
-    return { missing, present, orphans: [...orphans].sort() };
+    const invalidTopLevelKeys = spec.allowedTopLevelKeys
+        ? Object.keys(settings)
+            .filter((key) => !spec.allowedTopLevelKeys.includes(key))
+            .sort()
+        : [];
+    const invalidEventKeys = spec.allowedEventKeys
+        ? Object.keys(hooks)
+            .filter((key) => !spec.allowedEventKeys.includes(key))
+            .sort()
+        : [];
+    return {
+        missing,
+        present,
+        orphans: [...orphans].sort(),
+        invalidTopLevelKeys,
+        invalidEventKeys,
+    };
 }
 /**
  * Inspect every harness whose settings file exists under `projectRoot` and
@@ -88,21 +104,34 @@ export function loadHarnessWiring(projectRoot) {
         try {
             settings = JSON.parse(readFileSync(settingsPath, "utf8"));
         }
-        catch {
-            // Unparseable settings file: can't tell opt-in from noise, and the
-            // harness itself will complain about its own malformed config. Skip.
+        catch (error) {
+            out.push({
+                harness: id,
+                settingsFile: spec.settingsFile,
+                missing: [],
+                orphans: [],
+                invalidTopLevelKeys: [],
+                invalidEventKeys: [],
+                parseError: error.message,
+            });
             continue;
         }
         const diff = diffWiring(settings, spec);
         if (diff.present.length === 0)
             continue; // not opted in → not drift
-        if (diff.missing.length === 0 && diff.orphans.length === 0)
+        if (diff.missing.length === 0 &&
+            diff.orphans.length === 0 &&
+            diff.invalidTopLevelKeys.length === 0 &&
+            diff.invalidEventKeys.length === 0) {
             continue; // current
+        }
         out.push({
             harness: id,
             settingsFile: spec.settingsFile,
             missing: diff.missing,
             orphans: diff.orphans,
+            invalidTopLevelKeys: diff.invalidTopLevelKeys,
+            invalidEventKeys: diff.invalidEventKeys,
         });
     }
     return out;

package/dist/core/scratch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/scratch/index.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,kBAAkB,iFAQrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAC5C,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,6DAA6D;AAC7D,eAAO,MAAM,eAAe,QACyF,CAAC;AAEtH,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAID,wBAAgB,UAAU,IAAI,MAAM,CAMnC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAInC;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAeD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,CAAC,GAAE,IAAiB,GAAG,MAAM,CAW1D;AAID,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CA+DtE;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAkBxD;AAmBD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,SAAoB,GAAG,SAAS,EAAE,CA2DrF;AAID,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,GACX,UAAU,CAgEZ;AAID,wGAAwG;AACxG,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhE;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,IAAI,SAAyB,GAAG,MAAM,CAkBnE;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAajD;AAED,qDAAqD;AACrD,wBAAgB,YAAY,IAAI;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,EAAE,CAWF;AAID,wBAAgB,mBAAmB,IAAI,MAAM,CAM5C;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIjE;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoB9D"}

package/dist/{lib → core}/scratch/index.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { monorepoRoot, readHeartbeat, resolveOwner } from "../../core/agents/index.js";
-import { resolveMachineLabel } from "../machine.js";
+import { resolveMachineLabel } from "../../lib/machine.js";
+import { monorepoRoot, readHeartbeat, resolveOwner } from "../agents/index.js";
 /**
  * Agent scratchpad: per-agent markdown journal at `.harnery/scratch/<instance_id>.md`.
  *

package/dist/lib/devtools.d.ts

@@ -0,0 +1,178 @@
+/**
+ * `devtools`: read locally-stored state of the AI coding agents harnery
+ * supports — Claude Code (`~/.claude`), Codex (`~/.codex`), and Cursor
+ * (`~/.cursor`) — into one uniform status shape: login state, plan/tier,
+ * auth expiry, session counts, and (where the tool stores them locally)
+ * rate-limit / quota windows.
+ *
+ * Everything here reads files on disk — no network, no vendor API, no
+ * credentials leave the machine (auth tokens are inspected for their
+ * non-secret claims only; the token strings themselves are never returned).
+ * The signals a tool keeps server-side (Cursor usage + billing, Claude's live
+ * rate-limit windows) surface as `null` with a note rather than a guess.
+ *
+ * Pure toolkit tier: depends only on `node:*`, never on `src/core/`.
+ */
+export type DevtoolName = "claude-code" | "codex" | "cursor";
+export interface QuotaWindow {
+    /** Human label for the reset window (e.g. "5h", "weekly", "45m"). */
+    window: string;
+    /** Percent of the window's allowance consumed, 0-100, or null if unknown. */
+    usedPercent: number | null;
+    /** ISO timestamp when the window resets, or null if unknown. */
+    resetsAt: string | null;
+}
+export interface ApiEnrichment {
+    /** The configured API key authenticated successfully. */
+    ok: boolean;
+    /** Human name the vendor reports for the key (e.g. Cursor's apiKeyName). */
+    keyName: string | null;
+    /** Cloud-agent activity (Cursor Cloud Agent API), when available. */
+    cloudAgents: {
+        total: number;
+        active: number;
+    } | null;
+    /** Error message when the key is configured but a call failed. */
+    error: string | null;
+}
+/**
+ * Cursor billing-cycle + usage snapshot, fetched from cursor.com's own dashboard
+ * API using the IDE's locally-stored session token — the same call Cursor's UI
+ * makes for the Spending page. No API key to mint; it reads what's already on
+ * disk. Percentages are 0-100; cent amounts are raw (divide by 100 for dollars).
+ */
+export interface CursorUsage {
+    /** ISO start of the current billing cycle. */
+    cycleStart: string | null;
+    /** ISO end of the current billing cycle (the "resets on …" date). */
+    cycleEnd: string | null;
+    /** Percent of included total usage consumed this cycle (Cursor's "Total"). */
+    totalPercentUsed: number | null;
+    /** Percent of included API usage consumed (named-model / "API"). */
+    apiPercentUsed: number | null;
+    /** Percent of included first-party ("Auto") model usage consumed. */
+    firstPartyPercentUsed: number | null;
+    /** Included usage allowance in cents (e.g. 7000 = $70). */
+    includedLimitCents: number | null;
+}
+/**
+ * Overage / on-demand dollar spend against a cap — Cursor's on-demand usage and
+ * Claude's extra-usage credits are the same idea. Cents are raw (÷100 for USD).
+ */
+export interface SpendStatus {
+    /** Human label for what this spend covers (e.g. "On-demand", "Extra usage"). */
+    label: string;
+    /** Amount spent this cycle in cents. */
+    usedCents: number | null;
+    /** Spend cap in cents, or null when unset/unlimited. */
+    limitCents: number | null;
+}
+export interface ToolStatus {
+    tool: DevtoolName;
+    /** The tool's config directory exists on this machine. */
+    installed: boolean;
+    /** A credential is present and not obviously expired. null when undeterminable. */
+    loggedIn: boolean | null;
+    /** Account identifier (email where the tool exposes one), else null. */
+    account: string | null;
+    /** Plan / seat tier as the tool records it locally (e.g. "team", "team_tier_1"). */
+    plan: string | null;
+    /** Rate-limit tier string where the tool records one, else null. */
+    rateLimitTier: string | null;
+    /** ISO expiry of the active access credential, else null. */
+    authExpiresAt: string | null;
+    /** Count of local session transcripts, else null. */
+    sessions: number | null;
+    /** ISO timestamp of the most recent local session activity, else null. */
+    lastActivity: string | null;
+    /** Locally-known quota/rate-limit windows, or null when the tool keeps them server-side. */
+    quota: QuotaWindow[] | null;
+    /**
+     * Total tokens observed in local transcripts within the scan window
+     * (`windowDays`). Codex always reports it — its per-session cumulative total
+     * is one tail-read per rollout, cheap enough for every render. Claude Code's
+     * is `--usage`-gated (a full transcript scan, potentially gigabytes) and null
+     * otherwise. Cursor keeps token counts server-side, so it stays null.
+     */
+    tokensUsed: number | null;
+    /**
+     * Result of the optional API enrichment (network), populated by
+     * `enrichFromApi` when a key is configured. `null` when no enrichment ran.
+     */
+    api: ApiEnrichment | null;
+    /**
+     * Cursor billing-cycle + usage, populated by `enrichFromApi` from the IDE's
+     * own session token (no API key needed). `null` when no enrichment ran, the
+     * token is stale, or the tool isn't Cursor.
+     */
+    usage: CursorUsage | null;
+    /**
+     * Overage / on-demand dollar spend, populated by `enrichFromApi` (Cursor's
+     * on-demand, Claude's extra-usage credits). `null` when no enrichment ran or
+     * the plan has no overage concept.
+     */
+    spend: SpendStatus | null;
+    /** Caveats about what is and isn't derivable locally for this tool. */
+    notes: string[];
+}
+export interface DevtoolsReport {
+    generatedAt: string;
+    windowDays: number | null;
+    tools: ToolStatus[];
+}
+/** One endpoint's health, from `probeEndpoints` (the `devtools doctor` check). */
+export interface ProbeResult {
+    tool: DevtoolName;
+    endpoint: string;
+    /** Client version we put in the request's User-Agent, else null. */
+    clientVersion: string | null;
+    /** HTTP status, or null when no call was made / the request threw. */
+    status: number | null;
+    outcome: "ok" | "rate_limited" | "auth_rejected" | "shape_changed" | "unreachable" | "no_credential";
+    detail: string;
+}
+export interface ReadDevtoolsOpts {
+    /** Home directory to resolve tool config against. Defaults to os.homedir(). */
+    home?: string;
+    /** Scan transcripts for token totals (opt-in; can be slow). Default false. */
+    usage?: boolean;
+    /** When scanning usage, only include transcripts modified within N days. Default 7. */
+    windowDays?: number;
+    /** Clock injection for tests. Default Date.now(). */
+    now?: number;
+    /** Restrict to a subset of tools. Default all three. */
+    only?: readonly DevtoolName[];
+}
+/** Path of the machine-local Cursor API key file (honors XDG_CONFIG_HOME). */
+export declare function cursorApiKeyPath(): string;
+/** Resolve a Cursor API key: env `CURSOR_API_KEY` first, then the key file. */
+export declare function resolveCursorApiKey(): string | null;
+/**
+ * Enrich a report's entries over the network with live usage each tool keeps
+ * server-side, authenticating with the credential already on disk. Best-effort
+ * and network-guarded: every failure degrades to a note, never throws. No-op
+ * for a tool that isn't installed / present in the report.
+ */
+export declare function enrichFromApi(report: DevtoolsReport, opts?: {
+    cursorKey?: string | null;
+    timeoutMs?: number;
+    home?: string;
+    /** Cache TTL for the usage endpoints (ms). 0 disables caching. Default 120s. */
+    cacheTtlMs?: number;
+}): Promise<DevtoolsReport>;
+/**
+ * One live call per usage endpoint (cache-bypassing) to check the integration
+ * still works — the occasional "did a client change its headers?" test. It
+ * exercises the EXACT request builders production uses, so an `auth_rejected`
+ * result means our headers/token stopped being accepted, and `shape_changed`
+ * means the response schema drifted. Rate-limited results are reported as such,
+ * not as failures. Makes at most one request per tool; run it by hand (it is not
+ * scheduled) so it can't itself cause a rate limit.
+ */
+export declare function probeEndpoints(opts?: {
+    home?: string;
+    timeoutMs?: number;
+    only?: readonly DevtoolName[];
+}): Promise<ProbeResult[]>;
+export declare function readDevtools(opts?: ReadDevtoolsOpts): DevtoolsReport;
+//# sourceMappingURL=devtools.d.ts.map

package/dist/lib/devtools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.d.ts","sourceRoot":"","sources":["../../src/lib/devtools.ts"],"names":[],"mappings":"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"}