@defai.digital/ax-cli 4.1.10 → 4.1.14

package/dist/sdk/index.d.ts

@@ -1,54 +1,116 @@
 /**
- * AX CLI SDK - Programmatic API for AX CLI
+ * AX CLI SDK v1.4.0 - Programmatic API for AX CLI
  *
- * This SDK allows you to use AX CLI as a library instead of spawning CLI processes.
- * Perfect for integrations, VSCode extensions, and programmatic AI agent usage.
+ * Use AX CLI as a library for integrations, VSCode extensions, and programmatic AI agents.
+ *
+ * ## Installation
+ *
+ * ```bash
+ * npm install @defai.digital/ax-cli
+ * ```
  *
  * ## Quick Start
  *
- * 1. Run `ax-cli setup` to configure credentials (one-time setup)
- * 2. Use the SDK in your code
+ * ```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
  *
- * @example
  * ```typescript
- * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
+ * import { createGLMAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
  *
- * // Create agent (credentials from ax-cli setup)
- * const agent = await createAgent({
- *   maxToolRounds: 50  // Optional: 1-1000, default 400
+ * const agent = await createGLMAgent();
+ *
+ * agent.on('stream', (chunk) => {
+ *   if (chunk.type === 'content') {
+ *     process.stdout.write(chunk.content);
+ *   }
  * });
  *
  * try {
- *   // Listen to streaming responses
- *   agent.on('stream', (chunk) => {
- *     if (chunk.type === 'content') {
- *       console.log(chunk.content);
- *     }
- *   });
- *
- *   // Process messages
- *   const result = await agent.processUserMessage('List all TypeScript files');
- *   console.log('Done!', result.length, 'messages');
+ *   await agent.processUserMessage('Explain async/await');
  * } catch (error) {
- *   // Handle structured errors
  *   if (SDKError.isSDKError(error)) {
- *     if (error.code === SDKErrorCode.SETUP_NOT_RUN) {
- *       console.error('Please run: ax-cli setup');
- *     }
+ *     console.error(`Error [${error.code}]: ${error.message}`);
  *   }
  * } finally {
- *   // Always cleanup resources
  *   agent.dispose();
  * }
  * ```
  *
- * ## Testing
+ * ## 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/testing';
+ * import { createMockAgent } from '@defai.digital/ax-cli/sdk';
  *
- * const mockAgent = createMockAgent(['Response 1', 'Response 2']);
- * const result = await mockAgent.processUserMessage('Test');
+ * const mock = createMockAgent(['Hello!', 'How can I help?']);
+ * const result = await mock.processUserMessage('Hi');
+ * expect(result).toContain('Hello!');
  * ```
  *
  * @packageDocumentation
@@ -59,54 +121,67 @@ 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 { getSettingsManager } from '../utils/settings-manager.js';
-export type { SettingsManager } from '../utils/settings-manager.js';
-export { createTokenCounter } from '../utils/token-counter.js';
-export type { TokenCounter } from '../utils/token-counter.js';
-export { loadCustomInstructions } from '../utils/custom-instructions.js';
-export { buildSystemPrompt } from '../utils/prompt-builder.js';
-export { getUsageTracker } from '../utils/usage-tracker.js';
-export { extractErrorMessage, createErrorMessage, ErrorCategory } from '../utils/error-handler.js';
-export { loadMCPConfig } from '../mcp/config.js';
-export { getMCPManager, initializeMCPServers, getMcpConnectionCount, getMCPConnectionStatus, getMCPPrompts, discoverMCPPrompts, getMCPResources, } from '../llm/tools.js';
-export type { MCPConfig } from '../mcp/config.js';
-export type { MCPServerConfig, MCPTool } from '../mcp/client.js';
-export { MCPManager } from '../mcp/client.js';
-export { MCPManagerV2, createServerName, createToolName, type ServerName, type ToolName, type ConnectionState, type MCPPrompt, } from '../mcp/client-v2.js';
-export { promptToSlashCommand, parsePromptCommand, formatPromptResult, getPromptDescription, } from '../mcp/prompts.js';
-export { listAllResources, getResourceContent, parseMCPReference, extractMCPReferences, resolveMCPReferences, searchResources, type MCPResource, } from '../mcp/resources.js';
-export { ZAI_SERVER_NAMES, ZAI_ENDPOINTS, ZAI_VISION_PACKAGE, ZAI_MCP_TEMPLATES, ZAI_QUOTA_LIMITS, generateZAIServerConfig, getAllZAIServerNames, isZAIServer, getZAITemplate, type ZAIServerName, type ZAIPlanTier, type ZAIMCPTemplate, } from '../mcp/zai-templates.js';
-export { detectZAIServices, getEnabledZAIServers, validateZAIApiKey, getZAIApiKey, isZAIMCPConfigured, getRecommendedServers, isGLMModel, isZAIBaseURL, formatZAIStatus, type ZAIServiceStatus, } from '../mcp/zai-detector.js';
-export { getPermissionManager, initializePermissionManager, PermissionManager, PermissionTier, type PermissionRequest, type PermissionResult, type RiskLevel, } from '../permissions/permission-manager.js';
-export { getTaskPlanner, isComplexRequest } from '../planner/index.js';
-export type { TaskPlanner, TaskPlan, TaskPhase, PhaseResult, PlanResult, } from '../planner/index.js';
-export { getCheckpointManager } from '../checkpoint/index.js';
-export type { CheckpointManager, Checkpoint } from '../checkpoint/index.js';
-export { ContextStore, getContextStore, resetDefaultStore } from '../memory/context-store.js';
-export type { StoreResult } from '../memory/context-store.js';
-export type { ProjectMemory, CacheStats } from '../memory/types.js';
-export { ProgressReporter, getProgressReporter, ProgressEventType, type ProgressEvent } from './progress-reporter.js';
-export { UnifiedLogger, getUnifiedLogger, LogLevel, parseLogLevel, getLogLevelName, type LogEntry, type LogSource, type LogFilter } from './unified-logger.js';
-export { ToolRegistry, getToolRegistry, registerTools, createToolExecutor, type RegisteredTool, type ToolExecutor, type ToolExecutionContext, type ToolRegistrationOptions } from './tool-registry.js';
-export { ToolRegistry as InternalToolRegistry, type ToolDefinition, type ToolCategory } from '../tools/registry.js';
-export { GLM_MODELS, DEFAULT_MODEL, AGENT_CONFIG, PLANNER_CONFIG, VerbosityLevel, UI_CONFIG, type SupportedModel, } from '../constants.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;
     /**
@@ -212,6 +287,7 @@ export interface AgentOptions {
  * @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
@@ -252,20 +328,175 @@ export interface AgentOptions {
  * ```
  */
 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 config - Optional configuration overrides
+ * @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',
@@ -273,7 +504,7 @@ export declare function createAgent(options?: AgentOptions): Promise<LLMAgent>;
  * });
  * ```
  */
-export declare function createSubagent(role: import('../agent/subagent-types.js').SubagentRole, config?: Partial<import('../agent/subagent-types.js').SubagentConfig>): Subagent;
+export declare function createSubagent(role: import('../agent/subagent-types.js').SubagentRole, options?: SubagentOptions): Subagent;
 /**
  * Remove auto-cleanup handlers from an agent
  *
@@ -328,3 +559,343 @@ export declare function removeCleanupHandlers(agent: LLMAgent): void;
  * 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-3'
+ * ```
+ */
+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;