smartagent/ts/smartagent.interfaces.ts

import * as plugins from './plugins.js';

// ================================
// Agent Configuration Interfaces
// ================================

/**
 * Configuration options for the DualAgentOrchestrator
 */
export interface IDualAgentOptions extends plugins.smartai.ISmartAiOptions {
  /** Name of the agent system */
  name?: string;
  /** Default AI provider for both Driver and Guardian */
  defaultProvider?: plugins.smartai.TProvider;
  /** Optional separate provider for Guardian (for cost optimization) */
  guardianProvider?: plugins.smartai.TProvider;
  /** System message for the Driver agent */
  driverSystemMessage?: string;
  /** Policy prompt for the Guardian agent - REQUIRED */
  guardianPolicyPrompt: string;
  /** Maximum iterations for task completion (default: 20) */
  maxIterations?: number;
  /** Maximum consecutive rejections before aborting (default: 3) */
  maxConsecutiveRejections?: number;
  /** Enable verbose logging */
  verbose?: boolean;
}

// ================================
// Message Interfaces
// ================================

/**
 * Represents a message in the agent's conversation history
 */
export interface IAgentMessage {
  role: 'system' | 'user' | 'assistant' | 'tool' | 'guardian';
  content: string;
  toolName?: string;
  toolResult?: unknown;
  toolCall?: IToolCallProposal;
  guardianDecision?: IGuardianDecision;
  timestamp?: Date;
}

// ================================
// Tool Interfaces
// ================================

/**
 * Represents an action that a tool can perform
 */
export interface IToolAction {
  /** Action name (e.g., 'read', 'write', 'delete') */
  name: string;
  /** Description of what this action does */
  description: string;
  /** JSON schema for action parameters */
  parameters: Record<string, unknown>;
}

/**
 * Proposed tool call from the Driver
 */
export interface IToolCallProposal {
  /** Unique ID for this proposal */
  proposalId: string;
  /** Name of the tool */
  toolName: string;
  /** Specific action to perform */
  action: string;
  /** Parameters for the action */
  params: Record<string, unknown>;
  /** Driver's reasoning for this call */
  reasoning?: string;
}

/**
 * Result of tool execution
 */
export interface IToolExecutionResult {
  success: boolean;
  result?: unknown;
  error?: string;
}

/**
 * Base interface for wrapped tools
 */
export interface IAgentToolWrapper {
  /** Tool name */
  name: string;
  /** Tool description */
  description: string;
  /** Available actions */
  actions: IToolAction[];
  /** Initialize the tool */
  initialize(): Promise<void>;
  /** Cleanup resources */
  cleanup(): Promise<void>;
  /** Execute an action */
  execute(action: string, params: Record<string, unknown>): Promise<IToolExecutionResult>;
  /** Get a summary for Guardian review */
  getCallSummary(action: string, params: Record<string, unknown>): string;
}

// ================================
// Guardian Interfaces
// ================================

/**
 * Request for Guardian evaluation
 */
export interface IGuardianEvaluationRequest {
  /** The proposed tool call */
  proposal: IToolCallProposal;
  /** Current task context */
  taskContext: string;
  /** Recent conversation history (last N messages) */
  recentHistory: IAgentMessage[];
  /** Summary of what the tool call will do */
  callSummary: string;
}

/**
 * Guardian's decision
 */
export interface IGuardianDecision {
  /** Approve or reject */
  decision: 'approve' | 'reject';
  /** Explanation of the decision */
  reason: string;
  /** Specific concerns if rejected */
  concerns?: string[];
  /** Suggestions for the Driver if rejected */
  suggestions?: string;
  /** Confidence level (0-1) */
  confidence?: number;
}

// ================================
// Result Interfaces
// ================================

/**
 * Log entry for tool executions
 */
export interface IToolExecutionLog {
  timestamp: Date;
  toolName: string;
  action: string;
  params: Record<string, unknown>;
  guardianDecision: 'approved' | 'rejected';
  guardianReason: string;
  executionResult?: unknown;
  executionError?: string;
}

/**
 * Status of a dual-agent run
 */
export type TDualAgentRunStatus =
  | 'completed'
  | 'in_progress'
  | 'max_iterations_reached'
  | 'max_rejections_reached'
  | 'clarification_needed'
  | 'error';

/**
 * Result of a dual-agent run
 */
export interface IDualAgentRunResult {
  /** Whether the task was successful */
  success: boolean;
  /** Whether the task is completed */
  completed: boolean;
  /** Final result or response */
  result: string;
  /** Total iterations taken */
  iterations: number;
  /** Full conversation history */
  history: IAgentMessage[];
  /** Current status */
  status: TDualAgentRunStatus;
  /** Number of tool calls made */
  toolCallCount?: number;
  /** Number of Guardian rejections */
  rejectionCount?: number;
  /** Tool execution log */
  toolLog?: IToolExecutionLog[];
  /** Error message if status is 'error' */
  error?: string;
}

// ================================
// Utility Types
// ================================

/**
 * Available tool names
 */
export type TToolName = 'filesystem' | 'http' | 'browser' | 'shell';

/**
 * Generate a unique proposal ID
 */
export function generateProposalId(): string {
  return `proposal_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
}