types.ts

/**
 * Agent Script Types
 * Based on Salesforce Agent Script Recipes
 * @see https://developer.salesforce.com/sample-apps/agent-script-recipes/getting-started/overview
 */

/**
 * Agent Script Config Block
 * Defines agent metadata and configuration
 */
export interface AgentScriptConfig {
  agent_name?: string
  developer_name: string
  default_agent_user?: string
  description?: string
}

/**
 * Agent Script System Block
 * Defines global settings and instructions
 */
export interface AgentScriptSystemBlock {
  instructions: string
  messages?: {
    welcome?: string
    error?: string
    [key: string]: string | undefined
  }
  system_instructions?: string
}

/**
 * Agent Script Variable Declaration
 * Defines state management
 */
export interface AgentScriptVariable {
  type: "string" | "number" | "boolean" | "object" | "array"
  mutable: boolean
  linked?: boolean
  default?: string | number | boolean | Record<string, unknown> | unknown[]
  description?: string
}

/**
 * Agent Script Language Block
 * Defines locale configuration
 */
export interface AgentScriptLanguageBlock {
  default_locale: string
  additional_locales?: string
  all_additional_locales?: boolean
}

/**
 * Agent Script Action Definition
 * Defines external integrations (Flow, Apex, API)
 */
export interface AgentScriptActionDefinition {
  description: string
  inputs?: Record<string, string>
  outputs?: Record<
    string,
    string | { description?: string; [key: string]: unknown }
  >
  target: string // flow://, apex://, or API endpoint
}

/**
 * Agent Script Reasoning Action
 * Actions available to LLM in reasoning block
 */
export interface AgentScriptReasoningAction {
  action?: string // Action reference like @actions.action_name
  description?: string
  available_when?: string // Conditional availability
  with?: Record<string, unknown> // Input bindings
  set?: Record<string, unknown> // Output mappings
}

/**
 * Agent Script Reasoning Block
 * Defines topic behavior and available actions
 */
export interface AgentScriptReasoningBlock {
  instructions?: string | string[] // Can use -> for procedural instructions
  actions?: Record<string, AgentScriptReasoningAction | string>
  before_reasoning?: string // Lifecycle hook
  after_reasoning?: string // Lifecycle hook
}

/**
 * Agent Script Topic Block
 * Defines individual topics with reasoning and actions
 */
export interface AgentScriptTopicBlock {
  description: string
  reasoning?: AgentScriptReasoningBlock
  actions?: Record<string, AgentScriptActionDefinition>
  system_instructions?: string // Topic-specific system override
}

/**
 * Complete Agent Script Structure
 * Following official Salesforce Agent Script format
 */
export interface AgentScriptStructure {
  config: AgentScriptConfig
  system: AgentScriptSystemBlock
  variables?: Record<string, AgentScriptVariable>
  language?: AgentScriptLanguageBlock
  start_agent?: AgentScriptTopicBlock
  [topicName: string]: unknown // Dynamic topic blocks
}

/**
 * Agent Script Generation Options
 */
export interface AgentScriptGenerationOptions {
  includeComments?: boolean
  includeExamples?: boolean
  yamlIndent?: number
  generateVariables?: boolean
  includeLanguageConfig?: boolean
}

/**
 * Abstract interfaces for planner data structures
 * These replace the Salesforce model dependencies
 */

/**
 * Represents a variable/attribute definition
 */
export interface PlannerVariable {
  Id?: string
  DeveloperName?: string
  parameterName?: string
  mappingType?: string
  description?: string
}

/**
 * Represents an action/function definition
 */
export interface PlannerAction {
  Id?: string
  DeveloperName?: string
  MasterLabel?: string
  Description?: string
  InvocationTarget?: string
  InvocationTargetType?: string
  Source?: string
  Metadata?: {
    inputs?: Record<string, string>
    outputs?: Record<string, string | Record<string, unknown>>
    [key: string]: unknown
  }
}

/**
 * Represents a topic/plugin definition
 */
export interface PlannerTopic {
  Id?: string
  DeveloperName?: string
  MasterLabel?: string
  Description?: string
  Scope?: string
  actions?: PlannerAction[]
  Metadata?: {
    description?: string
    scope?: string
    [key: string]: unknown
  }
}

/**
 * Represents a planner definition
 * This is the main input to the generator
 */
export interface PlannerDefinition {
  Id?: string
  MasterLabel?: string
  DeveloperName?: string
  topics?: PlannerTopic[]
  actions?: PlannerAction[]
  variables?: PlannerVariable[]
  Metadata?: {
    description?: string
    [key: string]: unknown
  }
}