@n-dx/core 0.1.0

package/packages/llm-client/dist/public.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @n-dx/llm-client — Vendor-neutral LLM client foundation for n-dx.
+ *
+ * ## Dependency inversion foundation
+ *
+ * This package is the **shared foundation** of the n-dx monorepo. It sits
+ * at the root of the dependency DAG, imported by every domain package but
+ * importing none of them:
+ *
+ * ```
+ *   hench ──→ rex ──→ llm-client
+ *     │                    ↑
+ *     └────────────────────┘
+ *   sourcevision ──→ llm-client
+ *   web ──→ rex, sourcevision
+ * ```
+ *
+ * By centralizing LLM integration concerns here, the domain packages (rex,
+ * sourcevision, hench) avoid any direct dependency on each other's
+ * internals for AI communication. This **dependency inversion** ensures:
+ *
+ * - **No circular dependencies** — the DAG is strictly acyclic.
+ * - **Independent development** — each domain package can be built and
+ *   tested in isolation, with only llm-client as a shared contract.
+ * - **Single point of change** — provider upgrades, auth changes, and
+ *   retry policy updates happen here without touching domain packages.
+ *
+ * ## Architecture
+ *
+ * This package currently ships a production-ready Claude adapter and a
+ * Codex CLI adapter behind a vendor-neutral API surface.
+ * The Claude dual-provider architecture (CLI + API) ensures
+ * the client works in any environment:
+ *
+ * - **API provider** — direct `@anthropic-ai/sdk` calls for CI/production
+ * - **CLI provider** — spawns `claude` binary for local development
+ *
+ * Provider selection is automatic (based on credential availability)
+ * or explicit. Both providers share identical retry, error classification,
+ * and token usage tracking semantics.
+ *
+ * ## Package structure
+ *
+ * **Vendor-neutral core**
+ * - `provider-interface.ts` — generic `LLMProvider` interface (vendor-agnostic contract)
+ * - `provider-registry.ts` — provider registration, selection, and `defaultRegistry`
+ * - `provider-session.ts` — active provider management and vendor switching
+ * - `llm-types.ts` — vendor-neutral types (`LLMVendor`, `LLMConfig`, `CodexConfig`)
+ * - `llm-client.ts` — vendor-neutral factory (`createLLMClient`, `detectLLMAuthMode`)
+ * - `llm-config.ts` — vendor-neutral project config loader (`loadLLMConfig`)
+ *
+ * **Claude providers**
+ * - `create-client.ts` — Claude factory with auto-detection logic
+ * - `api-provider.ts` — Anthropic SDK provider
+ * - `cli-provider.ts` — Claude Code CLI provider
+ *
+ * **Codex provider**
+ * - `codex-cli-provider.ts` — Codex CLI provider (`codex exec`)
+ *
+ * **Shared utilities**
+ * - `types.ts` — Claude-specific shared interfaces and error classes
+ * - `config.ts` — credential resolution and model mapping
+ * - `token-usage.ts` — usage parsing for API, CLI, and stream formats
+ * - `auth.ts` — auth detection and diagnostics
+ * - `exec.ts` — process execution utilities (`exec`, `spawnTool`, `ProcessPool`)
+ * - `project-dirs.ts` — project directory constants (`PROJECT_DIRS`)
+ * - `project-config.ts` — `.n-dx.json` override loading and merging
+ * - `json.ts` — canonical JSON serialization
+ * - `output.ts` — CLI output control (quiet mode)
+ * - `suggest.ts` — CLI typo correction
+ * - `help-format.ts` — CLI help formatting and color output
+ *
+ * @example
+ * ```ts
+ * import { createLLMClient, loadLLMConfig } from "@n-dx/llm-client";
+ *
+ * const config = await loadLLMConfig(projectDir);
+ * const client = createLLMClient({ llmConfig: config, vendor: "claude" });
+ *
+ * const result = await client.complete({
+ *   prompt: "Hello",
+ *   model: "claude-sonnet-4-6",
+ * });
+ *
+ * console.log(result.text);
+ * console.log(client.mode); // "api" or "cli"
+ * ```
+ */
+export type { ProviderAuthMode, ProviderCapability, ProviderInfo, StreamChunk, LLMProvider, } from "./provider-interface.js";
+export type { ProviderFactory } from "./provider-registry.js";
+export { ProviderRegistry, createDefaultRegistry, defaultRegistry, } from "./provider-registry.js";
+export { ProviderSession, createProviderSession, } from "./provider-session.js";
+export type { LLMVendor, CodexConfig, LLMConfig, LLMClient, } from "./llm-types.js";
+export type { TokenUsage, ClaudeConfig, AuthMode, ClaudeClientOptions, CompletionRequest, CompletionResult, ErrorReason, ClaudeClient, } from "./types.js";
+export { ClaudeClientError, CLIError } from "./types.js";
+export { loadLLMConfig } from "./llm-config.js";
+export { createLLMClient, detectLLMAuthMode, } from "./llm-client.js";
+export type { CreateLLMClientOptions } from "./llm-client.js";
+export { loadClaudeConfig, resolveApiKey, resolveCliPath, resolveModel, } from "./config.js";
+export { parseApiTokenUsage, parseCliTokenUsage, parseStreamTokenUsage, } from "./token-usage.js";
+export { createApiClient } from "./api-provider.js";
+export type { ApiProviderOptions } from "./api-provider.js";
+export { createCliClient } from "./cli-provider.js";
+export type { CliProviderOptions } from "./cli-provider.js";
+export { createCodexCliClient } from "./codex-cli-provider.js";
+export type { CodexCliProviderOptions } from "./codex-cli-provider.js";
+export { createClient, detectAuthMode, } from "./create-client.js";
+export type { CreateClientOptions } from "./create-client.js";
+export { detectCliAvailability, validateApiKey, detectAvailableAuth, diagnoseAuth, } from "./auth.js";
+export type { AuthDetectionResult, AuthDiagnostics } from "./auth.js";
+export { exec, execStdout, execShellCmd, getCurrentHead, getCurrentBranch, isExecutableOnPath, spawnTool, spawnManaged, killWithFallback, ProcessPool, ProcessLimitError, } from "./exec.js";
+export type { ExecResult, ExecOptions, SpawnToolOptions, SpawnToolResult, ManagedChild, } from "./exec.js";
+export { PROJECT_DIRS } from "./project-dirs.js";
+export type { ProjectDir } from "./project-dirs.js";
+export { toCanonicalJSON } from "./json.js";
+export { deepMerge, loadProjectOverrides, mergeWithOverrides, } from "./project-config.js";
+export { setQuiet, isQuiet, info, result, } from "./output.js";
+export { editDistance, suggestCommands, formatTypoSuggestion, } from "./suggest.js";
+export { isColorEnabled, resetColorCache, bold, dim, cyan, yellow, cmd, flag, sectionHeader, requiredParam, optionalParam, formatHelp, formatUsage, } from "./help-format.js";
+export type { HelpOption, HelpExample, HelpDefinition, UsageSection, UsageDefinition, } from "./help-format.js";

package/packages/llm-client/dist/public.js

@@ -0,0 +1,122 @@
+/**
+ * @n-dx/llm-client — Vendor-neutral LLM client foundation for n-dx.
+ *
+ * ## Dependency inversion foundation
+ *
+ * This package is the **shared foundation** of the n-dx monorepo. It sits
+ * at the root of the dependency DAG, imported by every domain package but
+ * importing none of them:
+ *
+ * ```
+ *   hench ──→ rex ──→ llm-client
+ *     │                    ↑
+ *     └────────────────────┘
+ *   sourcevision ──→ llm-client
+ *   web ──→ rex, sourcevision
+ * ```
+ *
+ * By centralizing LLM integration concerns here, the domain packages (rex,
+ * sourcevision, hench) avoid any direct dependency on each other's
+ * internals for AI communication. This **dependency inversion** ensures:
+ *
+ * - **No circular dependencies** — the DAG is strictly acyclic.
+ * - **Independent development** — each domain package can be built and
+ *   tested in isolation, with only llm-client as a shared contract.
+ * - **Single point of change** — provider upgrades, auth changes, and
+ *   retry policy updates happen here without touching domain packages.
+ *
+ * ## Architecture
+ *
+ * This package currently ships a production-ready Claude adapter and a
+ * Codex CLI adapter behind a vendor-neutral API surface.
+ * The Claude dual-provider architecture (CLI + API) ensures
+ * the client works in any environment:
+ *
+ * - **API provider** — direct `@anthropic-ai/sdk` calls for CI/production
+ * - **CLI provider** — spawns `claude` binary for local development
+ *
+ * Provider selection is automatic (based on credential availability)
+ * or explicit. Both providers share identical retry, error classification,
+ * and token usage tracking semantics.
+ *
+ * ## Package structure
+ *
+ * **Vendor-neutral core**
+ * - `provider-interface.ts` — generic `LLMProvider` interface (vendor-agnostic contract)
+ * - `provider-registry.ts` — provider registration, selection, and `defaultRegistry`
+ * - `provider-session.ts` — active provider management and vendor switching
+ * - `llm-types.ts` — vendor-neutral types (`LLMVendor`, `LLMConfig`, `CodexConfig`)
+ * - `llm-client.ts` — vendor-neutral factory (`createLLMClient`, `detectLLMAuthMode`)
+ * - `llm-config.ts` — vendor-neutral project config loader (`loadLLMConfig`)
+ *
+ * **Claude providers**
+ * - `create-client.ts` — Claude factory with auto-detection logic
+ * - `api-provider.ts` — Anthropic SDK provider
+ * - `cli-provider.ts` — Claude Code CLI provider
+ *
+ * **Codex provider**
+ * - `codex-cli-provider.ts` — Codex CLI provider (`codex exec`)
+ *
+ * **Shared utilities**
+ * - `types.ts` — Claude-specific shared interfaces and error classes
+ * - `config.ts` — credential resolution and model mapping
+ * - `token-usage.ts` — usage parsing for API, CLI, and stream formats
+ * - `auth.ts` — auth detection and diagnostics
+ * - `exec.ts` — process execution utilities (`exec`, `spawnTool`, `ProcessPool`)
+ * - `project-dirs.ts` — project directory constants (`PROJECT_DIRS`)
+ * - `project-config.ts` — `.n-dx.json` override loading and merging
+ * - `json.ts` — canonical JSON serialization
+ * - `output.ts` — CLI output control (quiet mode)
+ * - `suggest.ts` — CLI typo correction
+ * - `help-format.ts` — CLI help formatting and color output
+ *
+ * @example
+ * ```ts
+ * import { createLLMClient, loadLLMConfig } from "@n-dx/llm-client";
+ *
+ * const config = await loadLLMConfig(projectDir);
+ * const client = createLLMClient({ llmConfig: config, vendor: "claude" });
+ *
+ * const result = await client.complete({
+ *   prompt: "Hello",
+ *   model: "claude-sonnet-4-6",
+ * });
+ *
+ * console.log(result.text);
+ * console.log(client.mode); // "api" or "cli"
+ * ```
+ */
+export { ProviderRegistry, createDefaultRegistry, defaultRegistry, } from "./provider-registry.js";
+// Provider session (active provider management + vendor switching)
+export { ProviderSession, createProviderSession, } from "./provider-session.js";
+export { ClaudeClientError, CLIError } from "./types.js";
+// Vendor-neutral config + client factories
+export { loadLLMConfig } from "./llm-config.js";
+export { createLLMClient, detectLLMAuthMode, } from "./llm-client.js";
+// Config
+export { loadClaudeConfig, resolveApiKey, resolveCliPath, resolveModel, } from "./config.js";
+// Token usage parsing
+export { parseApiTokenUsage, parseCliTokenUsage, parseStreamTokenUsage, } from "./token-usage.js";
+// Providers
+export { createApiClient } from "./api-provider.js";
+export { createCliClient } from "./cli-provider.js";
+export { createCodexCliClient } from "./codex-cli-provider.js";
+// Factory
+export { createClient, detectAuthMode, } from "./create-client.js";
+// Auth detection and validation
+export { detectCliAvailability, validateApiKey, detectAvailableAuth, diagnoseAuth, } from "./auth.js";
+// Process execution
+export { exec, execStdout, execShellCmd, getCurrentHead, getCurrentBranch, isExecutableOnPath, spawnTool, spawnManaged, killWithFallback, ProcessPool, ProcessLimitError, } from "./exec.js";
+// Project directory constants
+export { PROJECT_DIRS } from "./project-dirs.js";
+// Canonical JSON serialization
+export { toCanonicalJSON } from "./json.js";
+// Project-level config utilities (.n-dx.json overrides)
+export { deepMerge, loadProjectOverrides, mergeWithOverrides, } from "./project-config.js";
+// CLI output control (quiet mode)
+export { setQuiet, isQuiet, info, result, } from "./output.js";
+// CLI typo correction
+export { editDistance, suggestCommands, formatTypoSuggestion, } from "./suggest.js";
+// CLI help formatting
+export { isColorEnabled, resetColorCache, bold, dim, cyan, yellow, cmd, flag, sectionHeader, requiredParam, optionalParam, formatHelp, formatUsage, } from "./help-format.js";
+//# sourceMappingURL=public.js.map

package/packages/llm-client/dist/public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../src/public.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AAaH,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,mEAAmE;AACnE,OAAO,EACL,eAAe,EACf,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAsB/B,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzD,2CAA2C;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,eAAe,EACf,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAGzB,SAAS;AACT,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,sBAAsB;AACtB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,YAAY;AACZ,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAG/D,UAAU;AACV,OAAO,EACL,YAAY,EACZ,cAAc,GACf,MAAM,oBAAoB,CAAC;AAG5B,gCAAgC;AAChC,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,WAAW,CAAC;AAGnB,oBAAoB;AACpB,OAAO,EACL,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAUnB,8BAA8B;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,+BAA+B;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,wDAAwD;AACxD,OAAO,EACL,SAAS,EACT,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,kCAAkC;AAClC,OAAO,EACL,QAAQ,EACR,OAAO,EACP,IAAI,EACJ,MAAM,GACP,MAAM,aAAa,CAAC;AAErB,sBAAsB;AACtB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,sBAAsB;AACtB,OAAO,EACL,cAAc,EACd,eAAe,EACf,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,MAAM,EACN,GAAG,EACH,IAAI,EACJ,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,WAAW,GACZ,MAAM,kBAAkB,CAAC"}

package/packages/llm-client/dist/suggest.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Typo correction utilities for CLI commands.
+ *
+ * Uses Levenshtein edit distance to suggest similar commands when
+ * the user types an unrecognized command. Shared across all n-dx
+ * packages via the foundation layer.
+ *
+ * @module @n-dx/llm-client/suggest
+ */
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Uses single-row DP for O(n) memory.
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * Find the closest command names to the given input using edit distance.
+ * Returns suggestions sorted by distance, filtered to distance ≤ maxDistance.
+ */
+export declare function suggestCommands(input: string, candidates: string[], maxDistance?: number): Array<{
+    name: string;
+    distance: number;
+}>;
+/**
+ * Format a "Did you mean?" suggestion string for CLI output.
+ * Returns null if no close matches are found.
+ */
+export declare function formatTypoSuggestion(input: string, candidates: string[], prefix?: string): string | null;

package/packages/llm-client/dist/suggest.js

@@ -0,0 +1,63 @@
+/**
+ * Typo correction utilities for CLI commands.
+ *
+ * Uses Levenshtein edit distance to suggest similar commands when
+ * the user types an unrecognized command. Shared across all n-dx
+ * packages via the foundation layer.
+ *
+ * @module @n-dx/llm-client/suggest
+ */
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Uses single-row DP for O(n) memory.
+ */
+export function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const prev = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        let prevDiag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const temp = prev[j];
+            if (a[i - 1] === b[j - 1]) {
+                prev[j] = prevDiag;
+            }
+            else {
+                prev[j] = 1 + Math.min(prevDiag, prev[j - 1], prev[j]);
+            }
+            prevDiag = temp;
+        }
+    }
+    return prev[n];
+}
+/**
+ * Find the closest command names to the given input using edit distance.
+ * Returns suggestions sorted by distance, filtered to distance ≤ maxDistance.
+ */
+export function suggestCommands(input, candidates, maxDistance = 2) {
+    const lower = input.toLowerCase();
+    return candidates
+        .map((name) => ({ name, distance: editDistance(lower, name.toLowerCase()) }))
+        .filter((s) => s.distance > 0 && s.distance <= maxDistance)
+        .sort((a, b) => a.distance - b.distance);
+}
+/**
+ * Format a "Did you mean?" suggestion string for CLI output.
+ * Returns null if no close matches are found.
+ */
+export function formatTypoSuggestion(input, candidates, prefix = "") {
+    const suggestions = suggestCommands(input, candidates);
+    if (suggestions.length === 0)
+        return null;
+    if (suggestions.length === 1) {
+        return `Did you mean '${prefix}${suggestions[0].name}'?`;
+    }
+    const names = suggestions.slice(0, 3).map((s) => `${prefix}${s.name}`);
+    return `Did you mean one of: ${names.join(", ")}?`;
+}
+//# sourceMappingURL=suggest.js.map

package/packages/llm-client/dist/suggest.js.map

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

package/packages/llm-client/dist/token-usage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Token usage parsing utilities.
+ *
+ * Handles both Anthropic SDK response format and CLI stream-json format,
+ * providing a single consistent TokenUsage shape.
+ */
+import type { TokenUsage } from "./types.js";
+/**
+ * Parse token usage from an Anthropic API SDK response `usage` object.
+ *
+ * The SDK response always has `input_tokens` / `output_tokens` at the top level.
+ * Cache fields (`cache_creation_input_tokens`, `cache_read_input_tokens`) are
+ * present on some models/versions but not typed in the SDK, so we extract them
+ * from the raw object.
+ *
+ * Always returns a TokenUsage — missing numeric fields default to 0.
+ * Cache fields are omitted when zero or absent.
+ */
+export declare function parseApiTokenUsage(raw: Record<string, unknown>): TokenUsage;
+/**
+ * Parse token usage from a Claude CLI JSON envelope.
+ *
+ * Claude CLI --output-format json includes usage fields at the top level:
+ * `input_tokens` / `total_input_tokens`, `output_tokens` / `total_output_tokens`.
+ *
+ * Returns undefined when no token fields are found.
+ * Cache fields are omitted when zero or absent.
+ */
+export declare function parseCliTokenUsage(envelope: Record<string, unknown>): TokenUsage | undefined;
+/**
+ * Parse token usage from a CLI stream-json event.
+ *
+ * Stream-json events may include token usage:
+ * - At the top level: `input_tokens`, `output_tokens`
+ * - As fallback: `total_input_tokens`, `total_output_tokens`
+ * - Inside a nested `usage` object (some CLI versions)
+ *
+ * Prefers `input_tokens` over `total_input_tokens`.
+ * Prefers top-level fields over nested `usage` object.
+ * Returns undefined when no token fields are found.
+ * Cache fields are omitted when zero or absent.
+ */
+export declare function parseStreamTokenUsage(obj: Record<string, unknown>): TokenUsage | undefined;

package/packages/llm-client/dist/token-usage.js

@@ -0,0 +1,106 @@
+/**
+ * Token usage parsing utilities.
+ *
+ * Handles both Anthropic SDK response format and CLI stream-json format,
+ * providing a single consistent TokenUsage shape.
+ */
+/**
+ * Parse token usage from an Anthropic API SDK response `usage` object.
+ *
+ * The SDK response always has `input_tokens` / `output_tokens` at the top level.
+ * Cache fields (`cache_creation_input_tokens`, `cache_read_input_tokens`) are
+ * present on some models/versions but not typed in the SDK, so we extract them
+ * from the raw object.
+ *
+ * Always returns a TokenUsage — missing numeric fields default to 0.
+ * Cache fields are omitted when zero or absent.
+ */
+export function parseApiTokenUsage(raw) {
+    const input = typeof raw.input_tokens === "number" ? raw.input_tokens : 0;
+    const output = typeof raw.output_tokens === "number" ? raw.output_tokens : 0;
+    const result = { input, output };
+    const cacheCreation = raw.cache_creation_input_tokens;
+    if (typeof cacheCreation === "number" && cacheCreation > 0) {
+        result.cacheCreationInput = cacheCreation;
+    }
+    const cacheRead = raw.cache_read_input_tokens;
+    if (typeof cacheRead === "number" && cacheRead > 0) {
+        result.cacheReadInput = cacheRead;
+    }
+    return result;
+}
+/**
+ * Parse token usage from a Claude CLI JSON envelope.
+ *
+ * Claude CLI --output-format json includes usage fields at the top level:
+ * `input_tokens` / `total_input_tokens`, `output_tokens` / `total_output_tokens`.
+ *
+ * Returns undefined when no token fields are found.
+ * Cache fields are omitted when zero or absent.
+ */
+export function parseCliTokenUsage(envelope) {
+    const input = envelope.input_tokens ?? envelope.total_input_tokens;
+    const output = envelope.output_tokens ?? envelope.total_output_tokens;
+    if (typeof input !== "number" && typeof output !== "number") {
+        return undefined;
+    }
+    const usage = {
+        input: typeof input === "number" ? input : 0,
+        output: typeof output === "number" ? output : 0,
+    };
+    const cacheCreation = envelope.cache_creation_input_tokens;
+    const cacheRead = envelope.cache_read_input_tokens;
+    if (typeof cacheCreation === "number" && cacheCreation > 0) {
+        usage.cacheCreationInput = cacheCreation;
+    }
+    if (typeof cacheRead === "number" && cacheRead > 0) {
+        usage.cacheReadInput = cacheRead;
+    }
+    return usage;
+}
+/**
+ * Parse token usage from a CLI stream-json event.
+ *
+ * Stream-json events may include token usage:
+ * - At the top level: `input_tokens`, `output_tokens`
+ * - As fallback: `total_input_tokens`, `total_output_tokens`
+ * - Inside a nested `usage` object (some CLI versions)
+ *
+ * Prefers `input_tokens` over `total_input_tokens`.
+ * Prefers top-level fields over nested `usage` object.
+ * Returns undefined when no token fields are found.
+ * Cache fields are omitted when zero or absent.
+ */
+export function parseStreamTokenUsage(obj) {
+    // Try direct fields first (prefer input_tokens over total_input_tokens)
+    let input = obj.input_tokens ?? obj.total_input_tokens;
+    let output = obj.output_tokens ?? obj.total_output_tokens;
+    let cacheCreation = obj.cache_creation_input_tokens;
+    let cacheRead = obj.cache_read_input_tokens;
+    // Try nested usage object (stream-json format) — only if top-level has nothing
+    if (typeof input !== "number" &&
+        typeof output !== "number" &&
+        obj.usage &&
+        typeof obj.usage === "object") {
+        const usage = obj.usage;
+        input = usage.input_tokens ?? usage.total_input_tokens;
+        output = usage.output_tokens ?? usage.total_output_tokens;
+        cacheCreation = usage.cache_creation_input_tokens;
+        cacheRead = usage.cache_read_input_tokens;
+    }
+    if (typeof input !== "number" && typeof output !== "number") {
+        return undefined;
+    }
+    const result = {
+        input: typeof input === "number" ? input : 0,
+        output: typeof output === "number" ? output : 0,
+    };
+    if (typeof cacheCreation === "number" && cacheCreation > 0) {
+        result.cacheCreationInput = cacheCreation;
+    }
+    if (typeof cacheRead === "number" && cacheRead > 0) {
+        result.cacheReadInput = cacheRead;
+    }
+    return result;
+}
+//# sourceMappingURL=token-usage.js.map

package/packages/llm-client/dist/token-usage.js.map

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

package/packages/llm-client/dist/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared types for the Claude API client abstraction layer.
+ *
+ * These types define the unified interface that both CLI and API providers
+ * implement, plus common token usage and configuration types shared across
+ * all n-dx packages.
+ *
+ * ## Architectural role
+ *
+ * These types form the **cross-package contract** for the n-dx monorepo.
+ * Domain packages (rex, sourcevision, hench) import these types to
+ * interact with Claude without coupling to each other. Keeping the
+ * contract here — in the leaf of the dependency DAG — prevents circular
+ * dependencies and allows each package to be built and tested in
+ * isolation.
+ *
+ * When adding new shared types, add them here rather than in a domain
+ * package to preserve the acyclic dependency graph.
+ */
+/** Per-call token usage breakdown. */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheCreationInput?: number;
+    cacheReadInput?: number;
+}
+/**
+ * Claude configuration from the unified .n-dx.json config.
+ * These settings apply across all packages (hench, rex, sourcevision).
+ */
+export interface ClaudeConfig {
+    /** Path to Claude Code CLI binary. When set, used instead of looking for "claude" on PATH. */
+    cli_path?: string;
+    /** Anthropic API key. When set, used instead of reading from env var. */
+    api_key?: string;
+    /** Custom API endpoint URL. When set, used instead of the default Anthropic API URL. */
+    api_endpoint?: string;
+    /** Default Claude model name. When set, used instead of the default model. */
+    model?: string;
+}
+/** Authentication mode the client is operating in. */
+export type AuthMode = "api" | "cli";
+/** Options for creating a Claude client. */
+export interface ClaudeClientOptions {
+    /** Claude configuration (from .n-dx.json). */
+    claudeConfig: ClaudeConfig;
+    /** Environment variable name for API key fallback (default: "ANTHROPIC_API_KEY"). */
+    apiKeyEnv?: string;
+}
+/** Input to a Claude completion request. */
+export interface CompletionRequest {
+    /** The prompt text to send. */
+    prompt: string;
+    /** Model to use (e.g., "claude-sonnet-4-6"). */
+    model: string;
+    /** Output format: "json" for a single JSON envelope, "stream-json" for streaming events. */
+    outputFormat?: "json" | "stream-json";
+    /** Additional CLI flags to pass (only used in CLI mode). */
+    cliFlags?: string[];
+    /** Timeout in milliseconds (only used in CLI mode). */
+    timeoutMs?: number;
+}
+/** Result from a Claude completion request. */
+export interface CompletionResult {
+    /** The text response from Claude. */
+    text: string;
+    /** Token usage from the call, if available. */
+    tokenUsage?: TokenUsage;
+}
+/** Error classification for structured error handling. */
+export type ErrorReason = "auth" | "timeout" | "rate-limit" | "not-found" | "cli" | "unknown";
+/** A classified error from a Claude call or CLI operation. */
+export declare class ClaudeClientError extends Error {
+    readonly reason: ErrorReason;
+    /** Whether this error is transient and the call could be retried. */
+    readonly retryable: boolean;
+    constructor(message: string, reason: ErrorReason, retryable: boolean);
+}
+/**
+ * Base CLI error class for domain packages.
+ *
+ * Extends {@link ClaudeClientError} with an optional user-facing suggestion,
+ * providing a consistent error hierarchy across all n-dx packages. Domain
+ * packages (rex, hench, sourcevision) extend this class for their CLI errors
+ * instead of plain `Error`, enabling unified `instanceof` checks up the chain.
+ */
+export declare class CLIError extends ClaudeClientError {
+    /** Actionable hint shown to the user (e.g. "Run 'n-dx init' ..."). */
+    readonly suggestion?: string;
+    constructor(message: string, suggestion?: string);
+}
+/**
+ * The unified Claude client interface.
+ *
+ * Both CLI and API providers implement this interface. Consumers don't need
+ * to know which provider is active — they call `complete()` and get back
+ * a consistent result.
+ */
+export interface ClaudeClient {
+    /** Which authentication mode this client is using. */
+    readonly mode: AuthMode;
+    /**
+     * Send a prompt to Claude and get a text response.
+     *
+     * @throws {ClaudeClientError} on classified failures (auth, timeout, rate-limit, etc.)
+     */
+    complete(request: CompletionRequest): Promise<CompletionResult>;
+}

package/packages/llm-client/dist/types.js

@@ -0,0 +1,49 @@
+/**
+ * Shared types for the Claude API client abstraction layer.
+ *
+ * These types define the unified interface that both CLI and API providers
+ * implement, plus common token usage and configuration types shared across
+ * all n-dx packages.
+ *
+ * ## Architectural role
+ *
+ * These types form the **cross-package contract** for the n-dx monorepo.
+ * Domain packages (rex, sourcevision, hench) import these types to
+ * interact with Claude without coupling to each other. Keeping the
+ * contract here — in the leaf of the dependency DAG — prevents circular
+ * dependencies and allows each package to be built and tested in
+ * isolation.
+ *
+ * When adding new shared types, add them here rather than in a domain
+ * package to preserve the acyclic dependency graph.
+ */
+/** A classified error from a Claude call or CLI operation. */
+export class ClaudeClientError extends Error {
+    reason;
+    /** Whether this error is transient and the call could be retried. */
+    retryable;
+    constructor(message, reason, retryable) {
+        super(message);
+        this.name = "ClaudeClientError";
+        this.reason = reason;
+        this.retryable = retryable;
+    }
+}
+/**
+ * Base CLI error class for domain packages.
+ *
+ * Extends {@link ClaudeClientError} with an optional user-facing suggestion,
+ * providing a consistent error hierarchy across all n-dx packages. Domain
+ * packages (rex, hench, sourcevision) extend this class for their CLI errors
+ * instead of plain `Error`, enabling unified `instanceof` checks up the chain.
+ */
+export class CLIError extends ClaudeClientError {
+    /** Actionable hint shown to the user (e.g. "Run 'n-dx init' ..."). */
+    suggestion;
+    constructor(message, suggestion) {
+        super(message, "cli", false);
+        this.name = "CLIError";
+        this.suggestion = suggestion;
+    }
+}
+//# sourceMappingURL=types.js.map

package/packages/llm-client/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmEH,8DAA8D;AAC9D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,MAAM,CAAc;IAC7B,qEAAqE;IAC5D,SAAS,CAAU;IAE5B,YAAY,OAAe,EAAE,MAAmB,EAAE,SAAkB;QAClE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,QAAS,SAAQ,iBAAiB;IAC7C,sEAAsE;IAC7D,UAAU,CAAU;IAE7B,YAAY,OAAe,EAAE,UAAmB;QAC9C,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}