Core APIs - NikCLI Documentation

API Overview

NikCLI provides a comprehensive set of APIs for integrating with external tools, extending functionality, and building custom applications. The APIs are designed following TypeScript-first principles with full type safety and extensive documentation.

Agent APIs

Create, manage, and interact with AI agents

Tool APIs

Extend functionality with custom tools

Configuration APIs

Manage settings and preferences programmatically

Streaming APIs

Real-time communication and progress tracking

Core Interfaces

AgentTask Interface

Represents a task that can be executed by an agent:

interface AgentTask {
  /** Unique identifier for the task */
  id: string;
  
  /** Human-readable description of the task */
  description: string;
  
  /** Task type for routing to appropriate agent */
  type?: 'development' | 'analysis' | 'refactoring' | 'testing' | 'documentation';
  
  /** Priority level (1-10, 10 = highest) */
  priority?: number;
  
  /** Project context and workspace information */
  context: WorkspaceContext;
  
  /** Specific requirements and constraints */
  requirements?: TaskRequirements;
  
  /** Files to focus on (optional) */
  focusFiles?: string[];
  
  /** Expected deliverables */
  deliverables?: string[];
  
  /** Timeout in milliseconds */
  timeout?: number;
  
  /** Recovery strategy in case of failure */
  recoveryStrategy?: RecoveryStrategy;
  
  /** Custom metadata */
  metadata?: Record<string, any>;
}

WorkspaceContext Interface

Provides context about the current project and environment:

interface WorkspaceContext {
  /** Absolute path to the project root */
  projectRoot: string;
  
  /** Detected project type */
  projectType: ProjectType;
  
  /** Technology stack information */
  techStack: TechStack;
  
  /** Package.json contents (if available) */
  packageJson?: PackageJson;
  
  /** Git repository information */
  gitInfo?: GitInfo;
  
  /** Environment configuration */
  environment: EnvironmentInfo;
  
  /** File structure summary */
  fileStructure: FileStructure;
  
  /** Recent changes */
  recentChanges?: RecentChanges[];
  
  /** Coding patterns and conventions */
  patterns: CodingPatterns;
}

AgentExecution Interface

Represents the execution of a task by an agent:

interface AgentExecution {
  /** Execution identifier */
  id: string;
  
  /** Associated task */
  taskId: string;
  
  /** Executing agent */
  agentId: string;
  
  /** Current execution status */
  status: ExecutionStatus;
  
  /** Start timestamp */
  startedAt: number;
  
  /** Completion timestamp (if finished) */
  completedAt?: number;
  
  /** Progress percentage (0-100) */
  progress: number;
  
  /** Current execution stage */
  currentStage: string;
  
  /** Execution results */
  results?: ExecutionResult[];
  
  /** Any errors encountered */
  errors?: AgentError[];
  
  /** Performance metrics */
  metrics: ExecutionMetrics;
  
  /** Real-time event stream */
  stream: EventEmitter;
}

Agent Management APIs

AgentService

Central service for managing agent lifecycle and operations:

Creating Agents

class AgentService {
  /**
   * Create a new agent instance
   */
  async createAgent(config: AgentConfig): Promise<BaseAgent> {
    const agent = await this.agentFactory.createAgent(config);
    this.registerAgent(agent);
    return agent;
  }
  
  /**
   * Create agent from blueprint
   */
  async createFromBlueprint(
    blueprintId: string,
    overrides?: Partial<AgentConfig>
  ): Promise<BaseAgent> {
    const blueprint = await this.getBlueprintById(blueprintId);
    const config = { ...blueprint.config, ...overrides };
    return this.createAgent(config);
  }
}

Managing Agents

/**
 * Get all registered agents
 */
getAgents(): BaseAgent[] {
  return Array.from(this.agents.values());
}

/**
 * Find agent by ID
 */
getAgent(agentId: string): BaseAgent | null {
  return this.agents.get(agentId) || null;
}

/**
 * Find agents by capability
 */
findAgentsByCapability(capability: AgentCapability): BaseAgent[] {
  return this.getAgents().filter(agent => 
    agent.hasCapability(capability)
  );
}

/**
 * Remove agent from registry
 */
async removeAgent(agentId: string): Promise<void> {
  const agent = this.getAgent(agentId);
  if (agent) {
    await agent.cleanup();
    this.agents.delete(agentId);
  }
}

Task Execution

/**
 * Execute task with best suitable agent
 */
async executeTask(task: AgentTask): Promise<AgentExecution> {
  const agent = this.findBestAgent(task);
  if (!agent) {
    throw new Error(`No suitable agent found for task: ${task.type}`);
  }
  
  return await agent.executeTask(task);
}

/**
 * Execute task with specific agent
 */
async executeTaskWithAgent(
  agentId: string,
  task: AgentTask
): Promise<AgentExecution> {
  const agent = this.getAgent(agentId);
  if (!agent) {
    throw new Error(`Agent not found: ${agentId}`);
  }
  
  return await agent.executeTask(task);
}

/**
 * Execute multiple tasks in parallel
 */
async executeParallel(tasks: AgentTask[]): Promise<AgentExecution[]> {
  const executions = tasks.map(task => this.executeTask(task));
  return await Promise.all(executions);
}

BaseAgent Interface

All agents implement the BaseAgent interface:

abstract class BaseAgent {
  /** Agent unique identifier */
  readonly id: string;
  
  /** Agent name and description */
  readonly name: string;
  readonly description: string;
  
  /** Agent capabilities */
  abstract getCapabilities(): AgentCapability[];
  
  /** Agent permissions */
  abstract getPermissions(): AgentPermissions;
  
  /**
   * Execute a task
   */
  abstract executeTask(task: AgentTask): Promise<AgentExecution>;
  
  /**
   * Check if agent can handle a specific task
   */
  abstract canHandleTask(task: AgentTask): boolean;
  
  /**
   * Get current status
   */
  abstract getStatus(): AgentStatus;
  
  /**
   * Cleanup resources
   */
  abstract cleanup(): Promise<void>;
  
  /**
   * Configure agent settings
   */
  configure(config: Partial<AgentConfig>): void {
    Object.assign(this.config, config);
  }
  
  /**
   * Check if agent has specific capability
   */
  hasCapability(capability: AgentCapability): boolean {
    return this.getCapabilities().includes(capability);
  }
  
  /**
   * Subscribe to agent events
   */
  on(event: string, listener: (...args: any[]) => void): void {
    this.eventEmitter.on(event, listener);
  }
  
  /**
   * Emit agent event
   */
  protected emit(event: string, ...args: any[]): void {
    this.eventEmitter.emit(event, ...args);
  }
}

Tool System APIs

ToolService

Manages the tool system and provides secure tool execution:

Tool Registration

class ToolService {
  /**
   * Register a new tool
   */
  registerTool(tool: BaseTool): void {
    this.validateTool(tool);
    this.tools.set(tool.name, tool);
    this.emit('tool-registered', tool);
  }
  
  /**
   * Get available tools for agent
   */
  getToolsForAgent(agent: BaseAgent): BaseTool[] {
    const permissions = agent.getPermissions();
    return Array.from(this.tools.values()).filter(tool =>
      this.hasPermission(permissions, tool)
    );
  }
  
  /**
   * Execute tool with security checks
   */
  async executeTool(
    toolName: string,
    args: any[],
    agent: BaseAgent
  ): Promise<ToolResult> {
    const tool = this.getTool(toolName);
    if (!tool) {
      throw new Error(`Tool not found: ${toolName}`);
    }
    
    // Security validation
    await this.validateExecution(tool, args, agent);
    
    // Execute with timeout and error handling
    return await this.executeWithSafety(tool, args, agent);
  }
}

Tool Interface

interface BaseTool {
  /** Tool unique name */
  name: string;
  
  /** Tool description */
  description: string;
  
  /** Required permissions */
  requiredPermissions: Permission[];
  
  /** Input schema validation */
  inputSchema: JSONSchema;
  
  /** Output schema validation */
  outputSchema: JSONSchema;
  
  /**
   * Execute the tool
   */
  execute(args: any[], context: ToolContext): Promise<ToolResult>;
  
  /**
   * Validate tool arguments
   */
  validate(args: any[]): ValidationResult;
  
  /**
   * Check if tool is available
   */
  isAvailable(): boolean;
}

Security and Permissions

interface ToolContext {
  /** Executing agent */
  agent: BaseAgent;
  
  /** Current workspace */
  workspace: WorkspaceContext;
  
  /** Execution environment */
  environment: EnvironmentInfo;
  
  /** Security policies */
  policies: SecurityPolicy[];
  
  /** Approval system */
  approvalSystem: ApprovalSystem;
}

interface ToolResult {
  /** Execution success status */
  success: boolean;
  
  /** Result data */
  data?: any;
  
  /** Error information */
  error?: Error;
  
  /** Execution metrics */
  metrics: {
    executionTime: number;
    memoryUsage: number;
    cpuUsage: number;
  };
  
  /** Security audit trail */
  auditTrail: AuditEvent[];
}

Configuration APIs

ConfigManager

Provides programmatic access to configuration management:

Configuration Access

class ConfigManager {
  /**
   * Get configuration value
   */
  get<T = any>(key: string, defaultValue?: T): T {
    return this.config.get(key, defaultValue);
  }
  
  /**
   * Set configuration value
   */
  set(key: string, value: any): void {
    this.config.set(key, value);
    this.save();
  }
  
  /**
   * Get all configuration
   */
  getAll(): Record<string, any> {
    return { ...this.config.store };
  }
  
  /**
   * Reset configuration
   */
  reset(): void {
    this.config.clear();
    this.loadDefaults();
  }
}

Provider Management

/**
 * Configure AI provider
 */
configureProvider(
  provider: AIProvider,
  config: ProviderConfig
): void {
  this.validateProviderConfig(provider, config);
  this.set(`providers.${provider}`, config);
}

/**
 * Get provider configuration
 */
getProviderConfig(provider: AIProvider): ProviderConfig | null {
  return this.get(`providers.${provider}`, null);
}

/**
 * Test provider connection
 */
async testProvider(provider: AIProvider): Promise<ConnectionTest> {
  const config = this.getProviderConfig(provider);
  if (!config) {
    throw new Error(`Provider not configured: ${provider}`);
  }
  
  return await this.connectionTester.test(provider, config);
}

Security Configuration

/**
 * Set security mode
 */
setSecurityMode(mode: SecurityMode): void {
  this.set('security.mode', mode);
  this.applySecurityPolicies(mode);
}

/**
 * Configure execution policies
 */
setExecutionPolicy(policy: ExecutionPolicy): void {
  this.validatePolicy(policy);
  this.set('security.executionPolicy', policy);
}

/**
 * Enable/disable auto-approval
 */
setAutoApproval(enabled: boolean, riskLevel?: RiskLevel): void {
  this.set('security.autoApproval.enabled', enabled);
  if (riskLevel) {
    this.set('security.autoApproval.maxRiskLevel', riskLevel);
  }
}

Streaming APIs

Real-time Communication

NikCLI provides real-time APIs for monitoring agent progress and system events:

Agent Streams

interface AgentStream {
  /** Agent identifier */
  agentId: string;
  
  /** Task identifier */
  taskId: string;
  
  /** Subscribe to progress updates */
  onProgress(callback: (progress: ProgressUpdate) => void): void;
  
  /** Subscribe to stage changes */
  onStage(callback: (stage: StageUpdate) => void): void;
  
  /** Subscribe to results */
  onResult(callback: (result: ExecutionResult) => void): void;
  
  /** Subscribe to errors */
  onError(callback: (error: AgentError) => void): void;
  
  /** Subscribe to completion */
  onComplete(callback: (execution: AgentExecution) => void): void;
  
  /** Unsubscribe from all events */
  close(): void;
}

System Events

interface SystemEventStream {
  /** Subscribe to agent lifecycle events */
  onAgentEvent(callback: (event: AgentEvent) => void): void;
  
  /** Subscribe to configuration changes */
  onConfigChange(callback: (change: ConfigChange) => void): void;
  
  /** Subscribe to security events */
  onSecurityEvent(callback: (event: SecurityEvent) => void): void;
  
  /** Subscribe to tool executions */
  onToolExecution(callback: (execution: ToolExecution) => void): void;
  
  /** Subscribe to performance metrics */
  onMetrics(callback: (metrics: SystemMetrics) => void): void;
}

Stream Management

class StreamManager {
  /**
   * Create agent stream
   */
  createAgentStream(
    agentId: string,
    taskId: string
  ): AgentStream {
    const stream = new AgentStreamImpl(agentId, taskId);
    this.streams.set(`${agentId}:${taskId}`, stream);
    return stream;
  }
  
  /**
   * Get system event stream
   */
  getSystemStream(): SystemEventStream {
    return this.systemStream;
  }
  
  /**
   * Close all streams
   */
  closeAll(): void {
    for (const stream of this.streams.values()) {
      stream.close();
    }
    this.streams.clear();
  }
}

Error Handling

Error Types and Recovery

Error Classification

enum ErrorType {
  VALIDATION_ERROR = 'validation_error',
  PERMISSION_DENIED = 'permission_denied',
  RESOURCE_NOT_FOUND = 'resource_not_found',
  EXECUTION_TIMEOUT = 'execution_timeout',
  AGENT_UNAVAILABLE = 'agent_unavailable',
  TOOL_ERROR = 'tool_error',
  CONFIGURATION_ERROR = 'configuration_error',
  NETWORK_ERROR = 'network_error',
  UNKNOWN_ERROR = 'unknown_error'
}

class NikCLIError extends Error {
  constructor(
    message: string,
    public readonly type: ErrorType,
    public readonly code: string,
    public readonly details?: any,
    public readonly recoverable: boolean = false
  ) {
    super(message);
    this.name = 'NikCLIError';
  }
}

Recovery Strategies

interface RecoveryStrategy {
  /** Maximum number of retry attempts */
  maxRetries: number;
  
  /** Backoff strategy */
  backoffStrategy: 'linear' | 'exponential' | 'fixed';
  
  /** Base delay in milliseconds */
  baseDelay: number;
  
  /** Fallback operations */
  fallbackOperations?: Operation[];
  
  /** User notification settings */
  notifyUser: boolean;
  
  /** Custom recovery handler */
  customHandler?: (error: NikCLIError) => Promise<any>;
}

Error Handling Utilities

/**
 * Execute operation with automatic retry
 */
async function withRetry<T>(
  operation: () => Promise<T>,
  strategy: RecoveryStrategy
): Promise<T> {
  let lastError: Error;
  
  for (let attempt = 0; attempt <= strategy.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      
      if (attempt < strategy.maxRetries && isRetryable(error)) {
        const delay = calculateDelay(attempt, strategy);
        await sleep(delay);
      }
    }
  }
  
  throw lastError;
}

Next Steps

Tool System

Learn about the tool system and creating custom tools

Streaming APIs

Master real-time communication and progress tracking

Integrations

Integrate NikCLI with external tools and services

Examples

See practical examples of API usage

All APIs are fully typed with TypeScript. Use your IDE’s IntelliSense for comprehensive autocomplete and documentation while developing.

API Reference

​API Overview

Agent APIs

Tool APIs

Configuration APIs

Streaming APIs

​Core Interfaces

​AgentTask Interface

​WorkspaceContext Interface

​AgentExecution Interface

​Agent Management APIs

​AgentService

​BaseAgent Interface

​Tool System APIs

​ToolService

​Configuration APIs

​ConfigManager

​Streaming APIs

​Real-time Communication

​Error Handling

​Error Types and Recovery

​Next Steps

Tool System

Streaming APIs

Integrations

Examples

API Overview

Core Interfaces

AgentTask Interface

WorkspaceContext Interface

AgentExecution Interface

Agent Management APIs

AgentService

BaseAgent Interface

Tool System APIs

ToolService

Configuration APIs

ConfigManager

Streaming APIs

Real-time Communication

Error Handling

Error Types and Recovery

Next Steps