@defai.digital/ax-cli 4.4.6 → 4.4.10

package/dist/sdk/index.d.ts

@@ -1,901 +0,0 @@
-/**
- * AX CLI SDK v1.4.0 - Programmatic API for AX CLI
- *
- * Use AX CLI as a library for integrations, VSCode extensions, and programmatic AI agents.
- *
- * ## Installation
- *
- * ```bash
- * npm install @defai.digital/ax-cli
- * ```
- *
- * ## Quick Start
- *
- * ```typescript
- * import { createAgent, createGLMAgent, createGrokAgent } from '@defai.digital/ax-cli/sdk';
- *
- * // Option 1: Auto-detect provider
- * const agent = await createAgent();
- *
- * // Option 2: Explicit provider
- * const glmAgent = await createGLMAgent();   // Uses ~/.ax-glm/config.json
- * const grokAgent = await createGrokAgent(); // Uses ~/.ax-grok/config.json
- *
- * // Process messages
- * const result = await agent.processUserMessage('Analyze this code');
- * agent.dispose();
- * ```
- *
- * ## Public API (v1.4.0)
- *
- * ### Agent Creation
- * - `createAgent(options?)` - Create agent with auto-detected or specified provider
- * - `createGLMAgent(options?)` - Create GLM (Z.AI) agent
- * - `createGrokAgent(options?)` - Create Grok (xAI) agent
- * - `tryCreateAgent(options?)` - Create agent without throwing (returns result object)
- * - `withAgent(fn, options?)` - Run function with auto-disposed agent
- *
- * ### Error Handling
- * - `SDKError` - Structured error class with error codes
- * - `SDKErrorCode` - Error code enum (SETUP_NOT_RUN, API_KEY_MISSING, etc.)
- *
- * ### Agent Utilities
- * - `getAgentInfo(agent)` - Get provider, model, config info
- * - `getAgentStatus(agent)` - Check if agent is available/busy/disposed
- * - `isAgentDisposed(agent)` - Check disposal state
- * - `disposeAsync(agent)` - Dispose with async hook support
- *
- * ### Provider Utilities
- * - `detectProvider()` - Auto-detect configured provider
- * - `checkProviderHealth(provider?)` - Check if provider is configured
- * - `getAllProviderHealth()` - Check all providers
- *
- * ### Version Info
- * - `SDK_VERSION`, `CLI_VERSION` - Version constants
- * - `getSDKVersion()`, `getCLIVersion()` - Version strings
- * - `isSDKVersionCompatible(minVersion)` - Version check
- *
- * ### Testing
- * - `createMockAgent(responses)` - Create mock for testing
- * - `createMockSettings(overrides)` - Mock settings manager
- *
- * ## Example: Streaming Responses
- *
- * ```typescript
- * import { createGLMAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
- *
- * const agent = await createGLMAgent();
- *
- * agent.on('stream', (chunk) => {
- *   if (chunk.type === 'content') {
- *     process.stdout.write(chunk.content);
- *   }
- * });
- *
- * try {
- *   await agent.processUserMessage('Explain async/await');
- * } catch (error) {
- *   if (SDKError.isSDKError(error)) {
- *     console.error(`Error [${error.code}]: ${error.message}`);
- *   }
- * } finally {
- *   agent.dispose();
- * }
- * ```
- *
- * ## Example: Parallel Providers
- *
- * ```typescript
- * import { createGLMAgent, createGrokAgent } from '@defai.digital/ax-cli/sdk';
- *
- * // Run GLM and Grok in parallel
- * const [glm, grok] = await Promise.all([
- *   createGLMAgent(),
- *   createGrokAgent(),
- * ]);
- *
- * const [glmResult, grokResult] = await Promise.all([
- *   glm.processUserMessage('Analyze with GLM'),
- *   grok.processUserMessage('Analyze with Grok'),
- * ]);
- *
- * glm.dispose();
- * grok.dispose();
- * ```
- *
- * ## Example: Testing
- *
- * ```typescript
- * import { createMockAgent } from '@defai.digital/ax-cli/sdk';
- *
- * const mock = createMockAgent(['Hello!', 'How can I help?']);
- * const result = await mock.processUserMessage('Hi');
- * expect(result).toContain('Hello!');
- * ```
- *
- * @packageDocumentation
- */
-export { LLMAgent } from '../agent/llm-agent.js';
-export { Subagent } from '../agent/subagent.js';
-export { SubagentOrchestrator } from '../agent/subagent-orchestrator.js';
-export { ContextManager } from '../agent/context-manager.js';
-import { LLMAgent } from '../agent/llm-agent.js';
-import { Subagent } from '../agent/subagent.js';
-import { SDKError } from './errors.js';
-import { type ProviderType } from '../utils/provider-context.js';
-export { withFileLock, withFileLockSync, SafeJsonFile, LockGuard, cleanupStaleLocks, type LockOptions, } from '../utils/file-lock.js';
-export { LLMClient } from '../llm/client.js';
-export type { LLMMessage, LLMTool, LLMToolCall, LLMResponse, SearchParameters, SearchOptions, } from '../llm/client.js';
-export type { ChatOptions, ThinkingConfig, SamplingConfig, GLM46StreamChunk, } from '../llm/types.js';
-export type { ChatEntry, StreamingChunk } from '../agent/llm-agent.js';
-export type { ToolResult, Tool, EditorCommand, AgentState } from '../types/index.js';
-export { SubagentRole, SubagentState, type SubagentConfig, type SubagentTask, type SubagentResult, type SubagentStatus, } from '../agent/subagent-types.js';
-export { CLI_VERSION, SDK_VERSION, SDK_API_VERSION, getCLIVersion, getSDKVersion, getSDKInfo, getVersionString, isSDKVersionCompatible, } from './version.js';
-export { SDKError, SDKErrorCode } from './errors.js';
-export { MockAgent, createMockAgent, MockSettingsManager, createMockSettings, MockMCPServer, createMockMCPServer, waitForAgent, createMockToolResult, assertToolSuccess, assertToolFailure } from './testing.js';
-export type { MockMCPServerOptions } from './testing.js';
-export type { ProviderType } from '../utils/provider-context.js';
-export { detectProvider } from '../utils/provider-context.js';
-/**
- * Agent configuration options for SDK users
- *
- * SECURITY: Credentials (apiKey, baseURL) must be configured via "ax-cli setup"
- * and are NOT exposed through the SDK API to prevent security vulnerabilities.
- *
- * MULTI-PROVIDER SUPPORT (v5.0):
- * When running multiple providers in parallel (ax-glm and ax-grok), use the
- * `provider` option to specify which provider's configuration to use.
- * Each provider has isolated:
- * - Configuration files (~/.ax-glm/ vs ~/.ax-grok/)
- * - Cache directories
- * - Memory stores
- * - History
- *
- * @example
- * ```typescript
- * // Run GLM and Grok agents in parallel
- * const glmAgent = await createAgent({ provider: 'glm' });
- * const grokAgent = await createAgent({ provider: 'grok' });
- *
- * // Use both simultaneously
- * const [glmResult, grokResult] = await Promise.all([
- *   glmAgent.processUserMessage('Analyze with GLM'),
- *   grokAgent.processUserMessage('Analyze with Grok'),
- * ]);
- * ```
- */
-export interface AgentOptions {
-    /**
-     * Provider to use for configuration
-     *
-     * When specified, the agent will use the provider-specific configuration
-     * from the corresponding directory:
-     * - 'glm': Uses ~/.ax-glm/config.json
-     * - 'grok': Uses ~/.ax-grok/config.json
-     * - 'generic': Uses ~/.ax-cli/config.json
-     *
-     * If not specified, automatically detects based on:
-     * 1. AX_PROVIDER environment variable
-     * 2. Which provider's API key is set (ZAI_API_KEY, XAI_API_KEY)
-     * 3. Falls back to 'generic'
-     *
-     * @default auto-detect
-     */
-    provider?: ProviderType;
-    /** Maximum number of tool execution rounds (1-1000, default: 400) */
-    maxToolRounds?: number;
-    /**
-     * Enable debug mode for verbose logging
-     *
-     * When enabled, the SDK will log detailed information about:
-     * - Agent initialization
-     * - Message processing
-     * - Tool executions
-     * - Errors and warnings
-     *
-     * Debug logs are written to stderr and prefixed with [AX SDK DEBUG].
-     *
-     * @default false
-     */
-    debug?: boolean;
-    /**
-     * Enable automatic cleanup on process exit signals
-     *
-     * When enabled (default), the SDK automatically registers cleanup handlers for:
-     * - process.exit
-     * - SIGINT (Ctrl+C)
-     * - SIGTERM
-     * - SIGHUP
-     *
-     * Set to false if you want manual control over cleanup (useful for libraries,
-     * long-running services, or when you want to manage agent lifecycle yourself).
-     *
-     * @default true (backward compatible - cleanup enabled by default)
-     *
-     * @example
-     * ```typescript
-     * // Auto-cleanup enabled (default behavior)
-     * const agent = await createAgent();
-     *
-     * // Manual cleanup control
-     * const agent = await createAgent({ autoCleanup: false });
-     * // ... use agent ...
-     * agent.dispose(); // Manual cleanup
-     * ```
-     */
-    autoCleanup?: boolean;
-    /**
-     * Lifecycle hook called before agent disposal
-     *
-     * This hook is called BEFORE the agent's dispose() method runs, allowing you to:
-     * - Save state or checkpoint data
-     * - Log metrics or analytics
-     * - Notify external systems
-     * - Perform custom cleanup
-     *
-     * Can be async (returns Promise<void>) or sync (returns void).
-     *
-     * @param None
-     * @returns void or Promise<void>
-     *
-     * @example
-     * ```typescript
-     * const agent = await createAgent({
-     *   onDispose: async () => {
-     *     console.log('Agent disposing, saving state...');
-     *     await saveAgentState(agent);
-     *   }
-     * });
-     * ```
-     */
-    onDispose?: () => void | Promise<void>;
-    /**
-     * Error handler called when agent encounters errors
-     *
-     * This hook is called whenever the agent encounters an error during:
-     * - Message processing
-     * - Tool execution
-     * - Stream handling
-     *
-     * Use this to implement custom error handling, logging, or recovery logic.
-     *
-     * @param error - The error that occurred
-     * @returns void
-     *
-     * @example
-     * ```typescript
-     * const agent = await createAgent({
-     *   onError: (error) => {
-     *     console.error('Agent error:', error);
-     *     metrics.incrementErrorCount();
-     *     errorLogger.log(error);
-     *   }
-     * });
-     * ```
-     */
-    onError?: (error: Error) => void;
-}
-/**
- * Create a new LLM Agent with configuration
- *
- * SECURITY: All credentials (API key, base URL, model) must be configured
- * via "ax-cli setup" command. This prevents security vulnerabilities where
- * credentials could be exposed in code or logs.
- *
- * @param options - Agent configuration options (non-sensitive only)
- * @returns Configured LLM Agent instance
- * @throws {SDKError} With code SETUP_NOT_RUN if ax-cli setup has not been run
- * @throws {SDKError} With code API_KEY_MISSING if API key not configured
- * @throws {SDKError} With code BASE_URL_MISSING if base URL not configured
- * @throws {SDKError} With code MODEL_MISSING if model not configured
- * @throws {SDKError} With code VALIDATION_ERROR if options are invalid
- *
- * @example
- * ```typescript
- * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
- *
- * // First, user must run: ax-cli setup
- * // Then use SDK with settings from setup:
- *
- * const agent = await createAgent({
- *   maxToolRounds: 50  // Optional: 1-1000, default 400
- * });
- *
- * try {
- *   agent.on('stream', (chunk) => {
- *     if (chunk.type === 'content') {
- *       console.log(chunk.content);
- *     }
- *   });
- *
- *   const result = await agent.processUserMessage('Analyze this codebase');
- *   console.log(result);
- * } catch (error) {
- *   if (SDKError.isSDKError(error)) {
- *     switch (error.code) {
- *       case SDKErrorCode.SETUP_NOT_RUN:
- *         console.error('Run ax-cli setup first');
- *         break;
- *       case SDKErrorCode.API_KEY_MISSING:
- *         console.error('API key not configured');
- *         break;
- *     }
- *   }
- * } finally {
- *   // Always cleanup resources
- *   agent.dispose();
- * }
- * ```
- */
-export declare function createAgent(options?: AgentOptions): Promise<LLMAgent>;
-/**
- * Create an agent configured for GLM (Z.AI)
- *
- * Convenience function that creates an agent with provider: 'glm'.
- * Uses configuration from ~/.ax-glm/config.json.
- *
- * @param options - Agent options (provider is set to 'glm')
- * @returns Configured LLM Agent for GLM
- *
- * @example
- * ```typescript
- * const agent = await createGLMAgent();
- * const result = await agent.processUserMessage('Hello');
- * agent.dispose();
- * ```
- */
-export declare function createGLMAgent(options?: Omit<AgentOptions, 'provider'>): Promise<LLMAgent>;
-/**
- * Create an agent configured for Grok (xAI)
- *
- * Convenience function that creates an agent with provider: 'grok'.
- * Uses configuration from ~/.ax-grok/config.json.
- *
- * @param options - Agent options (provider is set to 'grok')
- * @returns Configured LLM Agent for Grok
- *
- * @example
- * ```typescript
- * const agent = await createGrokAgent();
- * const result = await agent.processUserMessage('Hello');
- * agent.dispose();
- * ```
- */
-export declare function createGrokAgent(options?: Omit<AgentOptions, 'provider'>): Promise<LLMAgent>;
-/**
- * Result type for tryCreateAgent
- */
-export type CreateAgentResult = {
-    success: true;
-    agent: LLMAgent;
-    error: undefined;
-} | {
-    success: false;
-    agent: undefined;
-    error: SDKError;
-};
-/**
- * Create an agent without throwing errors
- *
- * Unlike createAgent(), this function returns a result object instead of throwing.
- * Useful for graceful error handling without try-catch blocks.
- *
- * @param options - Agent configuration options
- * @returns Result object with either agent or error
- *
- * @example
- * ```typescript
- * const result = await tryCreateAgent({ provider: 'glm' });
- *
- * if (result.success) {
- *   // Use agent
- *   await result.agent.processUserMessage('Hello');
- *   result.agent.dispose();
- * } else {
- *   // Handle error without try-catch
- *   console.error('Failed:', result.error.code, result.error.message);
- * }
- * ```
- */
-export declare function tryCreateAgent(options?: AgentOptions): Promise<CreateAgentResult>;
-/**
- * Run a function with a temporary agent that is automatically disposed
- *
- * This helper creates an agent, runs your function, and ensures the agent
- * is properly disposed even if an error occurs. Useful for:
- * - One-off agent operations
- * - Scripts that need cleanup guarantees
- * - Testing scenarios
- *
- * @param fn - Function to run with the agent
- * @param options - Agent configuration options
- * @returns Result of the function
- *
- * @example
- * ```typescript
- * // Simple usage
- * const result = await withAgent(async (agent) => {
- *   return await agent.processUserMessage('Analyze this code');
- * });
- *
- * // With options
- * const result = await withAgent(
- *   async (agent) => {
- *     agent.on('stream', console.log);
- *     return await agent.processUserMessage('Hello');
- *   },
- *   { provider: 'glm', maxToolRounds: 50 }
- * );
- * ```
- */
-export declare function withAgent<T>(fn: (agent: LLMAgent) => Promise<T>, options?: AgentOptions): Promise<T>;
-/**
- * Run a function with a temporary agent, returning result or error
- *
- * Combines withAgent and tryCreateAgent - creates agent, runs function,
- * disposes, and returns result without throwing. Ideal for error-tolerant
- * workflows.
- *
- * @param fn - Function to run with the agent
- * @param options - Agent configuration options
- * @returns Result object with either value or error
- *
- * @example
- * ```typescript
- * const result = await tryWithAgent(async (agent) => {
- *   return await agent.processUserMessage('Hello');
- * }, { provider: 'grok' });
- *
- * if (result.success) {
- *   console.log('Got response:', result.value);
- * } else {
- *   console.error('Failed:', result.error.message);
- * }
- * ```
- */
-export declare function tryWithAgent<T>(fn: (agent: LLMAgent) => Promise<T>, options?: AgentOptions): Promise<{
-    success: true;
-    value: T;
-    error: undefined;
-} | {
-    success: false;
-    value: undefined;
-    error: SDKError;
-}>;
-/**
- * Options for creating a subagent
- */
-export interface SubagentOptions extends Partial<import('../agent/subagent-types.js').SubagentConfig> {
-    /**
-     * Provider to use for this subagent's configuration
-     *
-     * When specified, the subagent will use provider-specific settings.
-     * Important for parallel multi-provider scenarios.
-     *
-     * @default auto-detect based on environment
-     */
-    provider?: ProviderType;
-}
-/**
- * Create a specialized subagent for specific tasks
- *
- * @param role - The role/specialty of the subagent
- * @param options - Optional configuration including provider
- * @returns Configured Subagent instance
- *
- * @example
- * ```typescript
- * // Basic usage
- * const testAgent = createSubagent(SubagentRole.TESTING, {
- *   maxToolRounds: 20,
- *   priority: 2
- * });
- *
- * // With provider for parallel support
- * const glmSubagent = createSubagent(SubagentRole.ANALYSIS, {
- *   provider: 'glm',
- *   maxToolRounds: 30
- * });
- *
- * const result = await testAgent.execute({
- *   id: 'task-1',
- *   description: 'Write unit tests for auth module',
- *   context: { files: ['src/auth.ts'] }
- * });
- * ```
- */
-export declare function createSubagent(role: import('../agent/subagent-types.js').SubagentRole, options?: SubagentOptions): Subagent;
-/**
- * Remove auto-cleanup handlers from an agent
- *
- * Use this function to remove the automatic cleanup handlers registered by createAgent()
- * when autoCleanup was enabled (default). This gives you manual control over when the
- * agent is disposed.
- *
- * **Use Cases:**
- * - Long-running services that manage agent lifecycle manually
- * - Testing scenarios where you want precise control over cleanup
- * - Library code that embeds agents
- *
- * **Note:** Only works if agent was created with autoCleanup: true (default).
- * If autoCleanup was false, this function does nothing.
- *
- * @param agent - The agent instance created with createAgent()
- *
- * @example
- * ```typescript
- * // Create agent with auto-cleanup (default)
- * const agent = await createAgent();
- *
- * // Later, take manual control
- * removeCleanupHandlers(agent);
- *
- * // Now you must manually dispose
- * agent.dispose();
- * ```
- *
- * @example
- * ```typescript
- * // For manual cleanup from the start, use autoCleanup: false
- * const agent = await createAgent({ autoCleanup: false });
- * // No need to call removeCleanupHandlers
- * agent.dispose(); // Manual cleanup
- * ```
- */
-export declare function removeCleanupHandlers(agent: LLMAgent): void;
-/**
- * Initialize SDK and MCP servers
- *
- * SECURITY: This function does NOT accept credentials. All credentials must be
- * configured via "ax-cli setup" command. This function only initializes MCP servers.
- *
- * @example
- * ```typescript
- * // Initialize MCP servers from ax-cli settings
- * await initializeSDK();
- * ```
- *
- * @deprecated Most SDK users don't need to call this - createAgent() handles initialization.
- * Only call this if you need to pre-initialize MCP servers.
- */
-export declare function initializeSDK(): Promise<void>;
-/**
- * Information about an agent's configuration
- */
-export interface AgentInfo {
-    /** Provider type ('glm', 'grok', or 'generic') */
-    provider: ProviderType;
-    /** Provider display name */
-    providerDisplayName: string;
-    /** Current model in use */
-    model: string | undefined;
-    /** Base URL for API calls */
-    baseURL: string | undefined;
-    /** Whether the agent has been disposed */
-    isDisposed: boolean;
-    /** Configuration directory path */
-    configDir: string;
-    /** CLI command name for this provider */
-    cliName: string;
-    /** When the agent was created */
-    createdAt: Date;
-}
-/**
- * Get information about an agent created with createAgent()
- *
- * This function extracts the provider, model, and configuration information
- * from an agent instance. Useful for debugging, logging, and multi-provider
- * scenarios where you need to know which provider an agent is using.
- *
- * @param agent - The agent instance created with createAgent()
- * @returns AgentInfo object with provider/model details, or null if not SDK-created
- *
- * @example
- * ```typescript
- * const glmAgent = await createAgent({ provider: 'glm' });
- * const grokAgent = await createAgent({ provider: 'grok' });
- *
- * const glmInfo = getAgentInfo(glmAgent);
- * console.log(glmInfo?.provider);  // 'glm'
- * console.log(glmInfo?.model);     // 'glm-4.6'
- *
- * const grokInfo = getAgentInfo(grokAgent);
- * console.log(grokInfo?.provider); // 'grok'
- * console.log(grokInfo?.model);    // 'grok-4-0709'
- * ```
- */
-export declare function getAgentInfo(agent: LLMAgent): AgentInfo | null;
-/**
- * Get the model an agent is using
- *
- * Quick accessor to get just the model name from an SDK-created agent.
- * Returns undefined if the agent was not created via createAgent().
- *
- * @param agent - The agent instance
- * @returns The model name or undefined
- *
- * @example
- * ```typescript
- * const agent = await createAgent({ provider: 'glm' });
- * console.log(getAgentModel(agent)); // 'glm-4.6'
- * ```
- */
-export declare function getAgentModel(agent: LLMAgent): string | undefined;
-/**
- * Get the base URL an agent is using
- *
- * Quick accessor to get just the base URL from an SDK-created agent.
- * Returns undefined if the agent was not created via createAgent().
- *
- * @param agent - The agent instance
- * @returns The base URL or undefined
- *
- * @example
- * ```typescript
- * const agent = await createAgent({ provider: 'grok' });
- * console.log(getAgentBaseURL(agent)); // 'https://api.x.ai/v1'
- * ```
- */
-export declare function getAgentBaseURL(agent: LLMAgent): string | undefined;
-/**
- * Get the provider an agent is using
- *
- * Quick accessor to get just the provider type from an SDK-created agent.
- * Returns undefined if the agent was not created via createAgent().
- *
- * @param agent - The agent instance
- * @returns The provider type or undefined
- *
- * @example
- * ```typescript
- * const agent = await createAgent({ provider: 'glm' });
- * console.log(getAgentProvider(agent)); // 'glm'
- * ```
- */
-export declare function getAgentProvider(agent: LLMAgent): ProviderType | undefined;
-/**
- * Get when an agent was created
- *
- * Quick accessor to get the creation timestamp from an SDK-created agent.
- * Useful for logging, monitoring, and debugging agent lifecycle.
- * Returns undefined if the agent was not created via createAgent().
- *
- * @param agent - The agent instance
- * @returns The creation Date or undefined
- *
- * @example
- * ```typescript
- * const agent = await createAgent();
- * console.log(getAgentCreatedAt(agent)); // Date object
- * ```
- */
-export declare function getAgentCreatedAt(agent: LLMAgent): Date | undefined;
-/**
- * Get how long an agent has been running (age in milliseconds)
- *
- * Returns the time elapsed since the agent was created. Useful for:
- * - Monitoring long-running agents
- * - Implementing agent timeouts
- * - Debugging performance issues
- * - Logging agent lifecycle metrics
- *
- * @param agent - The agent instance
- * @returns Age in milliseconds, or undefined if not SDK-created
- *
- * @example
- * ```typescript
- * const agent = await createAgent();
- *
- * // ... some work ...
- *
- * const ageMs = getAgentAge(agent);
- * if (ageMs !== undefined) {
- *   console.log(`Agent running for ${Math.round(ageMs / 1000)}s`);
- *
- *   // Implement timeout
- *   if (ageMs > 5 * 60 * 1000) { // 5 minutes
- *     console.warn('Agent running too long, disposing');
- *     agent.dispose();
- *   }
- * }
- * ```
- */
-export declare function getAgentAge(agent: LLMAgent): number | undefined;
-/**
- * Format agent age as human-readable string
- *
- * Convenience function to get agent age as a formatted string.
- * Returns undefined if agent was not created via createAgent().
- *
- * @param agent - The agent instance
- * @returns Formatted age string (e.g., "1m 30s", "2h 15m"), or undefined
- *
- * @example
- * ```typescript
- * const agent = await createAgent();
- * // ... work ...
- * console.log(`Agent age: ${formatAgentAge(agent)}`); // "Agent age: 1m 30s"
- * ```
- */
-export declare function formatAgentAge(agent: LLMAgent): string | undefined;
-/**
- * Check if an agent is busy (bash executing) or disposed
- *
- * This function provides a quick check to determine if an agent is available
- * to process new messages. An agent is considered "busy" if:
- * - It has been disposed (cannot be used at all)
- * - It is currently executing a bash command
- *
- * Useful for:
- * - Pre-flight checks before sending messages
- * - Implementing request queuing
- * - Health monitoring dashboards
- *
- * @param agent - The agent instance to check
- * @returns Object with availability status
- *
- * @example
- * ```typescript
- * const agent = await createAgent();
- *
- * // Check before processing
- * const status = getAgentStatus(agent);
- * if (!status.available) {
- *   console.log('Agent not available:', status.reason);
- *   return;
- * }
- *
- * await agent.processUserMessage('Hello');
- * ```
- */
-export declare function getAgentStatus(agent: LLMAgent): {
-    /** Whether the agent is available to process messages */
-    available: boolean;
-    /** Whether the agent has been disposed */
-    isDisposed: boolean;
-    /** Whether the agent is executing bash command */
-    isBusy: boolean;
-    /** Reason why agent is unavailable (if not available) */
-    reason?: string;
-    /** Agent age in milliseconds (if SDK-created) */
-    ageMs?: number;
-};
-/**
- * Result of a provider health check
- */
-export interface ProviderHealthResult {
-    /** Whether the provider is healthy and ready */
-    healthy: boolean;
-    /** Provider type checked */
-    provider: ProviderType;
-    /** Whether API key is configured */
-    hasApiKey: boolean;
-    /** Whether base URL is configured */
-    hasBaseURL: boolean;
-    /** Whether model is configured */
-    hasModel: boolean;
-    /** Human-readable status message */
-    message: string;
-    /** Error details if unhealthy */
-    error?: string;
-}
-/**
- * Check if a provider is properly configured and ready to use
- *
- * This function validates that a provider has all required configuration
- * (API key, base URL, model) without actually creating an agent or making
- * API calls. Useful for:
- * - Pre-flight checks before creating agents
- * - Setup wizards and configuration UIs
- * - Health checks in long-running services
- *
- * @param provider - Provider to check (defaults to auto-detect)
- * @returns ProviderHealthResult with configuration status
- *
- * @example
- * ```typescript
- * // Check specific provider
- * const glmHealth = checkProviderHealth('glm');
- * if (!glmHealth.healthy) {
- *   console.error('GLM not configured:', glmHealth.message);
- *   console.log('Run: ax-glm setup');
- * }
- *
- * // Check all providers
- * const providers: ProviderType[] = ['glm', 'grok'];
- * for (const p of providers) {
- *   const health = checkProviderHealth(p);
- *   console.log(`${p}: ${health.healthy ? '✓' : '✗'} ${health.message}`);
- * }
- * ```
- */
-export declare function checkProviderHealth(provider?: ProviderType): ProviderHealthResult;
-/**
- * Get health status for all supported providers
- *
- * @returns Array of health results for all providers
- *
- * @example
- * ```typescript
- * const allHealth = getAllProviderHealth();
- * const configured = allHealth.filter(h => h.healthy);
- * console.log(`${configured.length} providers ready`);
- * ```
- */
-export declare function getAllProviderHealth(): ProviderHealthResult[];
-/**
- * Check if an agent has been disposed
- *
- * This function provides a reliable way to check if an agent created with
- * createAgent() has been disposed. Works regardless of the `autoCleanup` setting.
- *
- * @param agent - The agent instance to check
- * @returns true if the agent has been disposed, false otherwise
- * @returns undefined if the agent was not created via createAgent()
- *
- * @example
- * ```typescript
- * const agent = await createAgent();
- * console.log(isAgentDisposed(agent)); // false
- *
- * agent.dispose();
- * console.log(isAgentDisposed(agent)); // true
- * ```
- */
-export declare function isAgentDisposed(agent: LLMAgent): boolean | undefined;
-/**
- * Dispose an agent asynchronously, properly awaiting the onDispose hook
- *
- * The standard `agent.dispose()` is synchronous and fires async onDispose hooks
- * in a fire-and-forget manner. Use this function when you need to ensure the
- * onDispose hook completes before continuing.
- *
- * @param agent - The agent instance to dispose
- * @returns Promise that resolves when disposal is complete
- *
- * @example
- * ```typescript
- * const agent = await createAgent({
- *   onDispose: async () => {
- *     await saveState(); // This WILL be awaited with disposeAsync
- *   }
- * });
- *
- * // ... use agent ...
- *
- * // Properly await cleanup
- * await disposeAsync(agent);
- * console.log('Cleanup complete, state saved');
- * ```
- */
-export declare function disposeAsync(agent: LLMAgent): Promise<void>;
-/**
- * Information about a subagent's configuration
- */
-export interface SubagentInfo {
-    /** Provider type if configured */
-    provider: ProviderType | undefined;
-    /** Provider display name if configured */
-    providerDisplayName: string | undefined;
-    /** Configuration directory path if configured */
-    configDir: string | undefined;
-    /** CLI command name for this provider if configured */
-    cliName: string | undefined;
-    /** The subagent's role */
-    role: import('../agent/subagent-types.js').SubagentRole;
-}
-/**
- * Get information about a subagent created with createSubagent()
- *
- * @param subagent - The subagent instance
- * @returns SubagentInfo object with provider details
- *
- * @example
- * ```typescript
- * const subagent = createSubagent(SubagentRole.TESTING, { provider: 'glm' });
- * const info = getSubagentInfo(subagent);
- * console.log(info.provider); // 'glm'
- * console.log(info.role);     // SubagentRole.TESTING
- * ```
- */
-export declare function getSubagentInfo(subagent: Subagent): SubagentInfo;