initial

ts/smartagent.interfaces.ts

@@ -0,0 +1,210 @@
+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)}`;
+}