@n-dx/core 0.1.0

package/packages/hench/dist/tools/test-runner.js.map

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

package/packages/hench/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Output utility re-exports for the hench package.
+ */
+export { setQuiet, isQuiet, info, result, section, subsection, stream, detail, } from "./output.js";

package/packages/hench/dist/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * Output utility re-exports for the hench package.
+ */
+// Re-export output utilities for convenient access
+export { setQuiet, isQuiet, info, result, section, subsection, stream, detail, } from "./output.js";
+//# sourceMappingURL=index.js.map

package/packages/hench/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,mDAAmD;AACnD,OAAO,EACL,QAAQ,EACR,OAAO,EACP,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,MAAM,EACN,MAAM,GACP,MAAM,aAAa,CAAC"}

package/packages/hench/dist/types/output.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CLI output control — supports --quiet mode for scripting
+ * and structured section headers for streaming agent output.
+ *
+ * Core primitives (setQuiet, isQuiet, info, result) are shared from
+ * @n-dx/llm-client. Hench-specific extensions (section, subsection,
+ * stream, detail) are defined here and use the shared isQuiet() state.
+ *
+ * This module is placed in types/ to avoid circular dependencies
+ * between CLI and agent modules (both need output formatting).
+ *
+ * In quiet mode, only essential output is emitted:
+ * - JSON output (--format=json)
+ * - Error messages (always via console.error)
+ * - Final result identifiers (e.g. run IDs, status)
+ *
+ * Informational messages (progress, hints, summaries) are suppressed.
+ */
+export { setQuiet, isQuiet, info, result } from "../prd/llm-gateway.js";
+/**
+ * Print a major section header. Suppressed in quiet mode.
+ *
+ *   ══════════════════════════════════════════════════════════════
+ *   ❯ Section Title
+ *   ══════════════════════════════════════════════════════════════
+ */
+export declare function section(title: string): void;
+/**
+ * Print a minor subsection header. Suppressed in quiet mode.
+ *
+ *   ── Subsection Title ──────────────────────────────────────────
+ */
+export declare function subsection(title: string): void;
+/**
+ * Print a labelled streaming line. Suppressed in quiet mode.
+ * The label is right-padded for alignment.
+ *
+ *   [Agent]   Some agent text…
+ *   [Tool]    read_file({"path":"…"})
+ *   [Result]  contents of file…
+ */
+export declare function stream(label: string, text: string): void;
+/**
+ * Print a dim/secondary detail line. Suppressed in quiet mode.
+ * Useful for metadata like timing, token counts, retry info.
+ */
+export declare function detail(text: string): void;

package/packages/hench/dist/types/output.js

@@ -0,0 +1,74 @@
+/**
+ * CLI output control — supports --quiet mode for scripting
+ * and structured section headers for streaming agent output.
+ *
+ * Core primitives (setQuiet, isQuiet, info, result) are shared from
+ * @n-dx/llm-client. Hench-specific extensions (section, subsection,
+ * stream, detail) are defined here and use the shared isQuiet() state.
+ *
+ * This module is placed in types/ to avoid circular dependencies
+ * between CLI and agent modules (both need output formatting).
+ *
+ * In quiet mode, only essential output is emitted:
+ * - JSON output (--format=json)
+ * - Error messages (always via console.error)
+ * - Final result identifiers (e.g. run IDs, status)
+ *
+ * Informational messages (progress, hints, summaries) are suppressed.
+ */
+// Re-export shared foundation primitives.
+export { setQuiet, isQuiet, info, result } from "../prd/llm-gateway.js";
+import { isQuiet } from "../prd/llm-gateway.js";
+// ---------------------------------------------------------------------------
+// Streaming output — section headers and labelled lines for agent runs
+// ---------------------------------------------------------------------------
+const SECTION_WIDTH = 60;
+/**
+ * Print a major section header. Suppressed in quiet mode.
+ *
+ *   ══════════════════════════════════════════════════════════════
+ *   ❯ Section Title
+ *   ══════════════════════════════════════════════════════════════
+ */
+export function section(title) {
+    if (isQuiet())
+        return;
+    const rule = "═".repeat(SECTION_WIDTH);
+    console.log(`\n${rule}\n❯ ${title}\n${rule}`);
+}
+/**
+ * Print a minor subsection header. Suppressed in quiet mode.
+ *
+ *   ── Subsection Title ──────────────────────────────────────────
+ */
+export function subsection(title) {
+    if (isQuiet())
+        return;
+    const prefix = `── ${title} `;
+    const pad = Math.max(0, SECTION_WIDTH - prefix.length);
+    console.log(`\n${prefix}${"─".repeat(pad)}`);
+}
+/**
+ * Print a labelled streaming line. Suppressed in quiet mode.
+ * The label is right-padded for alignment.
+ *
+ *   [Agent]   Some agent text…
+ *   [Tool]    read_file({"path":"…"})
+ *   [Result]  contents of file…
+ */
+export function stream(label, text) {
+    if (isQuiet())
+        return;
+    const tag = `[${label}]`.padEnd(10);
+    console.log(`  ${tag} ${text}`);
+}
+/**
+ * Print a dim/secondary detail line. Suppressed in quiet mode.
+ * Useful for metadata like timing, token counts, retry info.
+ */
+export function detail(text) {
+    if (isQuiet())
+        return;
+    console.log(`           ${text}`);
+}
+//# sourceMappingURL=output.js.map

package/packages/hench/dist/types/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/types/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0CAA0C;AAC1C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,8EAA8E;AAC9E,uEAAuE;AACvE,8EAA8E;AAE9E,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,OAAO,EAAE;QAAE,OAAO;IACtB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,OAAO,EAAE;QAAE,OAAO;IACtB,MAAM,MAAM,GAAG,MAAM,KAAK,GAAG,CAAC;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,IAAY;IAChD,IAAI,OAAO,EAAE;QAAE,OAAO;IACtB,MAAM,GAAG,GAAG,IAAI,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,IAAI,OAAO,EAAE;QAAE,OAAO;IACtB,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/packages/hench/dist/validation/completion.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Result of completion validation.
+ *
+ * The agent must produce meaningful changes before a task can be
+ * marked complete. This prevents false completion claims where
+ * the agent says it's done but didn't actually change anything.
+ */
+export interface CompletionValidationResult {
+    valid: boolean;
+    hasChanges: boolean;
+    diffSummary?: string;
+    reason?: string;
+    testsRan?: boolean;
+    testsPassed?: boolean;
+}
+export interface CompletionValidationOptions {
+    /** Shell command to run tests (e.g. "npm test"). */
+    testCommand?: string;
+    /** Timeout for git/test commands in ms. Default: 30_000. */
+    timeout?: number;
+    /** Commit hash captured before the agent started. Diff against this instead of HEAD. */
+    startingHead?: string;
+    /** When true, reject completions that only modify documentation files. */
+    selfHeal?: boolean;
+}
+/**
+ * Validate that a task produced meaningful changes before completion.
+ *
+ * Checks:
+ * 1. `git diff --stat HEAD` must be non-empty (staged + unstaged changes)
+ * 2. If a test command is provided, it must exit successfully
+ */
+export declare function validateCompletion(projectDir: string, options?: CompletionValidationOptions): Promise<CompletionValidationResult>;
+/**
+ * Format a validation result as a human-readable string.
+ */
+export declare function formatValidationResult(result: CompletionValidationResult): string;

package/packages/hench/dist/validation/completion.js

@@ -0,0 +1,83 @@
+import { exec, execShellCmd } from "../process/index.js";
+const DEFAULT_TIMEOUT = 30_000;
+/**
+ * Validate that a task produced meaningful changes before completion.
+ *
+ * Checks:
+ * 1. `git diff --stat HEAD` must be non-empty (staged + unstaged changes)
+ * 2. If a test command is provided, it must exit successfully
+ */
+export async function validateCompletion(projectDir, options) {
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    // Check git diff (staged + unstaged vs starting HEAD or current HEAD)
+    const diffRef = options?.startingHead ?? "HEAD";
+    const { stdout: diffOutput } = await exec("git", ["diff", "--stat", diffRef], { cwd: projectDir, timeout });
+    const hasChanges = diffOutput.trim().length > 0;
+    const diffSummary = hasChanges ? diffOutput.trim() : undefined;
+    if (!hasChanges) {
+        return {
+            valid: false,
+            hasChanges: false,
+            reason: "No changes detected in git diff. Task must produce meaningful changes to be marked complete.",
+        };
+    }
+    // In self-heal mode, reject completions that only modify documentation files
+    if (options?.selfHeal && diffOutput) {
+        const changedFiles = diffOutput
+            .split("\n")
+            .map((line) => line.trim().split("|")[0]?.trim())
+            .filter((f) => f && !f.includes("changed") && !f.includes("insertion") && !f.includes("deletion"));
+        const allDocs = changedFiles.length > 0 && changedFiles.every((f) => /\.(md|adr\.\w+|txt)$/i.test(f) || f.startsWith("docs/"));
+        if (allDocs) {
+            return {
+                valid: false,
+                hasChanges: true,
+                diffSummary,
+                reason: "Self-heal mode requires source code changes. Only documentation files were modified.",
+            };
+        }
+    }
+    // Run tests if configured
+    if (options?.testCommand) {
+        const { error: testError, stderr: testStderr } = await execShellCmd(options.testCommand, { cwd: projectDir, timeout });
+        if (testError) {
+            return {
+                valid: false,
+                hasChanges: true,
+                diffSummary,
+                testsRan: true,
+                testsPassed: false,
+                reason: `Tests failed: ${testStderr.trim() || testError.message}`,
+            };
+        }
+        return {
+            valid: true,
+            hasChanges: true,
+            diffSummary,
+            testsRan: true,
+            testsPassed: true,
+        };
+    }
+    return {
+        valid: true,
+        hasChanges: true,
+        diffSummary,
+    };
+}
+/**
+ * Format a validation result as a human-readable string.
+ */
+export function formatValidationResult(result) {
+    const lines = [];
+    if (result.hasChanges) {
+        lines.push(`Changes detected: ${result.diffSummary ?? "yes"}`);
+    }
+    else {
+        lines.push(result.reason ?? "No changes detected");
+    }
+    if (result.testsRan) {
+        lines.push(result.testsPassed ? "Tests: passed" : `Tests failed: ${result.reason ?? "unknown error"}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=completion.js.map

package/packages/hench/dist/validation/completion.js.map

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

package/packages/hench/dist/validation/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared validation utilities.
+ *
+ * These are used by both hench-core (agent loops) and hench-tooling
+ * (rex tool completion gate). Keeping them in a separate module avoids
+ * cross-boundary imports between agent and tools.
+ */
+export { validateCompletion, formatValidationResult, } from "./completion.js";
+export type { CompletionValidationResult, CompletionValidationOptions, } from "./completion.js";

package/packages/hench/dist/validation/index.js

@@ -0,0 +1,9 @@
+/**
+ * Shared validation utilities.
+ *
+ * These are used by both hench-core (agent loops) and hench-tooling
+ * (rex tool completion gate). Keeping them in a separate module avoids
+ * cross-boundary imports between agent and tools.
+ */
+export { validateCompletion, formatValidationResult, } from "./completion.js";
+//# sourceMappingURL=index.js.map

package/packages/hench/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/packages/hench/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "hench",
+  "version": "0.1.0",
+  "private": true,
+  "license": "Elastic-2.0",
+  "type": "module",
+  "bin": {
+    "hench": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/public.js",
+      "types": "./dist/public.d.ts"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "validate": "tsc --noEmit && vitest run",
+    "prepare": "pnpm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@n-dx/llm-client": "workspace:*",
+    "rex": "workspace:*",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.0"
+  }
+}

package/packages/llm-client/dist/api-provider.d.ts

@@ -0,0 +1,47 @@
+/**
+ * API provider — calls Claude via the Anthropic SDK directly.
+ *
+ * One half of the dual provider architecture. The API provider makes direct
+ * HTTP requests to the Anthropic Messages API using `@anthropic-ai/sdk`.
+ *
+ * ## When this provider is selected
+ *
+ * - Explicitly via `createClient({ mode: "api" })`
+ * - Automatically when an API key is available (from config or env)
+ *
+ * ## Use cases
+ *
+ * - CI/CD pipelines where the Claude CLI isn't installed
+ * - Production environments with direct API access
+ * - Scenarios requiring fine-grained control over API parameters
+ *
+ * ## Error handling
+ *
+ * Errors are classified into categories (auth, timeout, rate-limit, unknown)
+ * with automatic retry on transient failures (429, 500, 502, 503, 529)
+ * using exponential backoff.
+ *
+ * @see {@link createClient} in `create-client.ts` for provider selection logic
+ * @see {@link createCliClient} in `cli-provider.ts` for the alternative provider
+ */
+import type { ClaudeClient, ClaudeClientOptions } from "./types.js";
+import type { LLMProvider } from "./provider-interface.js";
+/** Options specific to the API provider. */
+export interface ApiProviderOptions extends ClaudeClientOptions {
+    /** Maximum number of retries for transient failures (default: 3). */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000). */
+    baseDelayMs?: number;
+    /** Maximum response tokens (default: 8192). */
+    maxTokens?: number;
+}
+/**
+ * Create an API-based Claude client that implements both the legacy
+ * {@link ClaudeClient} interface and the generic {@link LLMProvider} interface.
+ *
+ * Uses the Anthropic SDK to make direct API calls. The API key is resolved
+ * from the unified config or environment variable.
+ *
+ * @throws {ClaudeClientError} with reason "auth" if no API key is available.
+ */
+export declare function createApiClient(options: ApiProviderOptions): ClaudeClient & LLMProvider;

package/packages/llm-client/dist/api-provider.js

@@ -0,0 +1,126 @@
+/**
+ * API provider — calls Claude via the Anthropic SDK directly.
+ *
+ * One half of the dual provider architecture. The API provider makes direct
+ * HTTP requests to the Anthropic Messages API using `@anthropic-ai/sdk`.
+ *
+ * ## When this provider is selected
+ *
+ * - Explicitly via `createClient({ mode: "api" })`
+ * - Automatically when an API key is available (from config or env)
+ *
+ * ## Use cases
+ *
+ * - CI/CD pipelines where the Claude CLI isn't installed
+ * - Production environments with direct API access
+ * - Scenarios requiring fine-grained control over API parameters
+ *
+ * ## Error handling
+ *
+ * Errors are classified into categories (auth, timeout, rate-limit, unknown)
+ * with automatic retry on transient failures (429, 500, 502, 503, 529)
+ * using exponential backoff.
+ *
+ * @see {@link createClient} in `create-client.ts` for provider selection logic
+ * @see {@link createCliClient} in `cli-provider.ts` for the alternative provider
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { ClaudeClientError } from "./types.js";
+import { resolveApiKey, resolveModel } from "./config.js";
+import { parseApiTokenUsage } from "./token-usage.js";
+const RETRY_STATUS_CODES = new Set([429, 500, 502, 503, 529]);
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_TOKENS = 8192;
+/**
+ * Create an API-based Claude client that implements both the legacy
+ * {@link ClaudeClient} interface and the generic {@link LLMProvider} interface.
+ *
+ * Uses the Anthropic SDK to make direct API calls. The API key is resolved
+ * from the unified config or environment variable.
+ *
+ * @throws {ClaudeClientError} with reason "auth" if no API key is available.
+ */
+export function createApiClient(options) {
+    const apiKeyEnv = options.apiKeyEnv ?? "ANTHROPIC_API_KEY";
+    const apiKey = resolveApiKey(options.claudeConfig, apiKeyEnv);
+    if (!apiKey) {
+        throw new ClaudeClientError(`API key not found. Set it via 'n-dx config claude.api_key <key>' or the ${apiKeyEnv} environment variable.`, "auth", false);
+    }
+    const clientOpts = { apiKey };
+    if (options.claudeConfig.api_endpoint) {
+        clientOpts.baseURL = options.claudeConfig.api_endpoint;
+    }
+    const client = new Anthropic(clientOpts);
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const info = {
+        vendor: "claude",
+        mode: "api",
+        ...(options.claudeConfig.model ? { model: options.claudeConfig.model } : {}),
+        capabilities: [],
+    };
+    return {
+        // ── LLMProvider ──────────────────────────────────────────────────────
+        info,
+        async validateAuth() {
+            try {
+                await client.models.list();
+                return true;
+            }
+            catch (err) {
+                const status = err.status;
+                if (status === 401 || status === 403) {
+                    return false;
+                }
+                throw new ClaudeClientError(err.message, "unknown", false);
+            }
+        },
+        // ── ClaudeClient (backward compat) ───────────────────────────────────
+        mode: "api",
+        async complete(request) {
+            let lastError;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    const response = await client.messages.create({
+                        model: resolveModel(request.model),
+                        max_tokens: maxTokens,
+                        messages: [{ role: "user", content: request.prompt }],
+                    });
+                    // Extract text from response blocks
+                    let text = "";
+                    for (const block of response.content) {
+                        if (block.type === "text") {
+                            text += block.text;
+                        }
+                    }
+                    const tokenUsage = parseApiTokenUsage(response.usage);
+                    return { text, tokenUsage };
+                }
+                catch (err) {
+                    lastError = err;
+                    const status = err.status;
+                    // Classify the error
+                    if (status === 401 || status === 403) {
+                        throw new ClaudeClientError(err.message, "auth", false);
+                    }
+                    if (status === 408 || err.message?.includes("timeout")) {
+                        throw new ClaudeClientError(err.message, "timeout", true);
+                    }
+                    if (status && RETRY_STATUS_CODES.has(status) && attempt < maxRetries) {
+                        const delay = baseDelayMs * 2 ** attempt;
+                        await new Promise((r) => setTimeout(r, delay));
+                        continue;
+                    }
+                    if (status && RETRY_STATUS_CODES.has(status)) {
+                        throw new ClaudeClientError(err.message, "rate-limit", true);
+                    }
+                    throw new ClaudeClientError(err.message, "unknown", false);
+                }
+            }
+            throw lastError;
+        },
+    };
+}
+//# sourceMappingURL=api-provider.js.map

package/packages/llm-client/dist/api-provider.js.map

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

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

@@ -0,0 +1,85 @@
+/**
+ * Authentication detection and validation.
+ *
+ * Provides utilities to detect available authentication methods (CLI / API key),
+ * validate credentials before use, and produce human-readable diagnostics when
+ * authentication is misconfigured.
+ */
+import type { AuthMode, ClaudeClientOptions } from "./types.js";
+/**
+ * Check whether the Claude Code CLI binary is reachable.
+ *
+ * Runs `<binary> --version` and resolves `true` if the command exits
+ * successfully (exit code 0), `false` otherwise (not found, permission
+ * error, crash, etc.).
+ */
+export declare function detectCliAvailability(options: ClaudeClientOptions): Promise<boolean>;
+/**
+ * Validate that the resolved API key is accepted by the Anthropic API.
+ *
+ * Makes a minimal `messages.create` call with 1 max_tokens. The call is
+ * expected to succeed (or fail with a non-auth error such as rate-limit),
+ * confirming the key is valid.
+ *
+ * @returns `true` if the key is valid, `false` if authentication fails
+ *   (401/403).
+ * @throws {ClaudeClientError} with reason "auth" when no API key is
+ *   available at all (not configured and not in env).
+ */
+export declare function validateApiKey(options: ClaudeClientOptions): Promise<boolean>;
+/**
+ * Result of the async authentication detection.
+ */
+export interface AuthDetectionResult {
+    /** The recommended authentication mode. */
+    mode: AuthMode;
+    /** Whether the API key was found in configuration. */
+    apiKeyAvailable: boolean;
+    /** Whether the Claude Code CLI binary was found on PATH / configured path. */
+    cliAvailable: boolean;
+}
+/**
+ * Detect the best available authentication method by actually probing the
+ * environment (checking the CLI binary and API key availability).
+ *
+ * Unlike the synchronous `detectAuthMode()` in create-client.ts which only
+ * checks for an API key, this function also verifies CLI availability so the
+ * caller gets a complete picture.
+ *
+ * Priority:
+ * 1. API key present (from config or env) → "api"
+ * 2. CLI binary reachable → "cli"
+ * 3. Neither available → throws with a helpful error message
+ *
+ * @throws {ClaudeClientError} with reason "auth" when neither method is
+ *   available.
+ */
+export declare function detectAvailableAuth(options: ClaudeClientOptions): Promise<AuthDetectionResult>;
+/**
+ * Diagnostic details about the current authentication setup.
+ */
+export interface AuthDiagnostics {
+    /** The API key source, if available. */
+    apiKeySource: "config" | "env" | "none";
+    /** Whether the resolved API key passed validation (undefined if skipped). */
+    apiKeyValid?: boolean;
+    /** Whether the CLI binary was found. */
+    cliAvailable: boolean;
+    /** The recommended mode based on the diagnostics. */
+    recommendedMode: AuthMode | "none";
+    /** Human-readable summary lines for display. */
+    messages: string[];
+}
+/**
+ * Run a full diagnostic check on authentication configuration.
+ *
+ * This is useful for `ndx config` / status commands to tell the user
+ * exactly what is and isn't working.
+ *
+ * When `validateKey` is true (default: false), the function makes a real
+ * API call to verify the key is accepted. This costs a tiny number of
+ * tokens but confirms end-to-end auth.
+ */
+export declare function diagnoseAuth(options: ClaudeClientOptions & {
+    validateKey?: boolean;
+}): Promise<AuthDiagnostics>;