/**
 * Agent Types
 *
 * Type definitions for the Ductape Agentic Workflows API.
 * Enables AI-driven, autonomous multi-step processes where an LLM
 * dynamically decides the next action based on observations and reasoning.
 */
import { RedisClientType } from 'redis';
import { IActionRequest, INotificationRequest, IDbActionRequest, IStorageRequest, IStepInput } from '../../types';
/**
 * Configuration options for AgentsService initialization
 */
export interface IAgentServiceConfig {
    redis_client: RedisClientType;
    /** Workspace ID */
    workspace_id: string;
    /** Public key for authentication */
    public_key: string;
    /** User ID */
    user_id: string;
    /** Authentication token */
    token: string;
    /** Environment type (staging, production, local) */
    env_type: string;
}
/**
 * Supported LLM providers
 */
export type LLMProvider = 'anthropic' | 'openai' | 'google' | 'cohere' | 'custom';
/**
 * LLM model configuration
 */
export interface ILLMConfig {
    /** LLM provider */
    provider: LLMProvider;
    /** Model identifier (e.g., 'claude-sonnet-4-20250514', 'gpt-4') */
    model: string;
    /** Sampling temperature (0-1) */
    temperature?: number;
    /** Maximum tokens to generate */
    maxTokens?: number;
    /** Top-p sampling */
    topP?: number;
    /** Stop sequences */
    stopSequences?: string[];
    /** API key (can be pulled from secrets) */
    apiKey?: string;
    /** API base URL for custom providers */
    baseUrl?: string;
    /** Custom headers */
    headers?: Record<string, string>;
    /** Request timeout in ms */
    timeout?: number;
}
/**
 * Model configuration overrides
 * These can be applied at runtime to override settings from the model entity
 */
export interface IModelConfigOverrides {
    /** Override temperature */
    temperature?: number;
    /** Override max tokens */
    maxTokens?: number;
    /** Override top-p sampling */
    topP?: number;
    /** Override stop sequences */
    stopSequences?: string[];
    /** Override timeout in ms */
    timeout?: number;
}
/**
 * Tool parameter types
 */
export type ToolParamType = 'string' | 'number' | 'boolean' | 'array' | 'object';
/**
 * Tool parameter definition
 */
export interface IToolParam {
    /** Parameter type */
    type: ToolParamType;
    /** Description for LLM */
    description: string;
    /** Whether parameter is required */
    required?: boolean;
    /** Enum values for constrained inputs */
    enum?: string[];
    /** Default value */
    default?: unknown;
    /** For array types, the item type */
    items?: IToolParam;
    /** For object types, nested properties */
    properties?: Record<string, IToolParam>;
}
/**
 * Tool call result
 */
export interface IToolCallResult {
    /** Tool tag */
    tool: string;
    /** Input parameters used */
    input: Record<string, unknown>;
    /** Tool output */
    output: unknown;
    /** Whether the call was successful */
    success: boolean;
    /** Error message if failed */
    error?: string;
    /** Execution time in ms */
    duration: number;
    /** Timestamp */
    timestamp: number;
}
/**
 * Agent tool definition
 */
export interface IAgentTool<TParams = Record<string, unknown>, TResult = unknown> {
    /** Unique tool identifier */
    tag: string;
    /** Human-readable name */
    name?: string;
    /** Description for LLM to understand when to use this tool */
    description: string;
    /** Input parameter schema */
    parameters: Record<string, IToolParam>;
    /** Tool implementation */
    handler: (ctx: IAgentToolContext, params: TParams) => Promise<TResult>;
    /** Whether this tool requires human confirmation before execution */
    requiresConfirmation?: boolean;
    /** Estimated cost for quota tracking */
    costEstimate?: number;
    /** Timeout for this tool in ms */
    timeout?: number;
    /** Number of retries on failure */
    retries?: number;
    /** Tool-level resilience configuration */
    resilience?: IAgentToolResilienceConfig;
}
/**
 * Short-term memory configuration
 */
export interface IShortTermMemoryConfig {
    /** Maximum messages to keep in context */
    maxMessages?: number;
    /** Summarize conversation after this many messages */
    summarizeAfter?: number;
    /** Include tool call results in context */
    includeToolResults?: boolean;
    /** Strategy for truncation */
    truncationStrategy?: 'fifo' | 'sliding_window' | 'summarize';
}
/**
 * Long-term memory configuration
 */
export interface ILongTermMemoryConfig {
    /** Enable long-term memory */
    enabled: boolean;
    /** Vector store tag for retrieval */
    vectorStore?: string;
    /** Number of results to retrieve */
    retrieveTopK?: number;
    /** Minimum similarity threshold */
    minSimilarity?: number;
    /** Automatically store new learnings */
    autoStore?: boolean;
    /** Namespace for memory isolation */
    namespace?: string;
}
/**
 * Full memory configuration
 */
export interface IAgentMemoryConfig {
    /** Short-term (conversation) memory */
    shortTerm?: IShortTermMemoryConfig;
    /** Long-term (persistent) memory */
    longTerm?: ILongTermMemoryConfig;
}
/**
 * Stop condition based on tool call
 */
export interface IToolStopCondition {
    /** Stop when this tool is called */
    tool: string;
    /** Optional: only stop if tool output matches */
    outputMatch?: Record<string, unknown>;
}
/**
 * Stop condition based on output content
 */
export interface IOutputStopCondition {
    /** Stop when output contains these fields/values */
    output: Record<string, unknown>;
}
/**
 * Stop condition based on LLM response
 */
export interface IMessageStopCondition {
    /** Stop when LLM says it's done (pattern match) */
    messagePattern?: string | RegExp;
}
/**
 * Union of stop condition types
 */
export type StopCondition = IToolStopCondition | IOutputStopCondition | IMessageStopCondition;
/**
 * Termination configuration
 */
export interface IAgentTerminationConfig {
    /** Maximum number of agent loop iterations */
    maxIterations?: number;
    /** Maximum total tokens to use */
    maxTokens?: number;
    /** Timeout duration (ms or duration string like '10m') */
    timeout?: number | string;
    /** Explicit stop conditions */
    stopConditions?: StopCondition[];
    /** Whether to allow manual termination via signal */
    allowManualStop?: boolean;
}
/**
 * Hook timing
 */
export type HookTiming = 'before' | 'after';
/**
 * Agent hook definition
 */
export interface IAgentHook {
    /** Hook name */
    name: string;
    /** When to trigger (before/after) */
    timing: HookTiming;
    /** Event to hook into */
    event: 'iteration' | 'tool_call' | 'llm_call' | 'termination';
    /** Hook handler */
    handler: (ctx: IAgentHookContext) => Promise<void | boolean>;
}
/**
 * Context provided to hooks
 */
export interface IAgentHookContext {
    /** Current agent state */
    state: IAgentState;
    /** Event data */
    event: {
        type: string;
        data: unknown;
    };
    /** Abort the current operation */
    abort: (reason: string) => void;
    /** Modify the operation */
    modify: (changes: Record<string, unknown>) => void;
}
/**
 * Approval request
 */
export interface IApprovalRequest {
    /** Request ID */
    id: string;
    /** Tool being called */
    tool: string;
    /** Parameters to approve */
    params: Record<string, unknown>;
    /** Reason for approval request */
    reason: string;
    /** Timeout for approval */
    timeout?: number;
}
/**
 * Approval response
 */
export interface IApprovalResponse {
    /** Whether approved */
    approved: boolean;
    /** Modified parameters (if changed) */
    modifiedParams?: Record<string, unknown>;
    /** Rejection reason */
    reason?: string;
}
/**
 * Human-in-the-loop configuration
 */
export interface IHumanInLoopConfig {
    /** Enable human-in-the-loop */
    enabled: boolean;
    /** Tools that always require approval */
    alwaysRequireApproval?: string[];
    /** Default timeout for approval requests */
    approvalTimeout?: number | string;
    /** Webhook to call for approvals */
    approvalWebhook?: string;
    /** Broker topic to publish approval requests */
    approvalBroker?: {
        broker: string;
        event: string;
    };
}
/**
 * Stream event types
 */
export type AgentStreamEventType = 'thinking_start' | 'thinking_delta' | 'thinking_end' | 'tool_start' | 'tool_end' | 'message_start' | 'message_delta' | 'message_end' | 'iteration_start' | 'iteration_end' | 'agent_complete' | 'error';
/**
 * Stream event
 */
export interface IAgentStreamEvent {
    /** Event type */
    type: AgentStreamEventType;
    /** Event timestamp */
    timestamp: number;
    /** Event data */
    data: unknown;
    /** Current iteration */
    iteration?: number;
}
/**
 * Streaming configuration
 */
export interface IAgentStreamConfig {
    /** Enable streaming */
    enabled: boolean;
    /** Events to stream */
    events?: AgentStreamEventType[];
    /** Webhook to send events to */
    webhook?: string;
    /** Broker to publish events to */
    broker?: {
        broker: string;
        event: string;
    };
}
/**
 * Tool-level resilience configuration
 * References existing product-level healthchecks, quotas, and fallbacks by tag
 */
export interface IAgentToolResilienceConfig {
    /** Tag of an existing quota to use for this tool */
    quota?: string;
    /** Tag of an existing fallback to use for this tool */
    fallback?: string;
    /** Tag of an existing healthcheck to verify before execution */
    healthcheck?: string;
}
/**
 * Agent-level resilience configuration
 * References existing product-level healthchecks, quotas, and fallbacks
 *
 * Note: Healthchecks, quotas, and fallbacks must be defined at the product level
 * using the resilience API. Agents can only reference existing configurations.
 *
 * @example
 * ```typescript
 * // First, define resilience configs at the product level
 * await ductape.resilience.createHealthcheck({
 *   product: 'my-product',
 *   tag: 'anthropic-health',
 *   // ... healthcheck config
 * });
 *
 * await ductape.resilience.createQuota({
 *   product: 'my-product',
 *   tag: 'llm-quota',
 *   // ... quota config
 * });
 *
 * // Then reference them in agent definition
 * const agent = await ductape.agents.define({
 *   // ...
 *   resilience: {
 *     defaults: {
 *       healthcheck: 'anthropic-health',
 *       quota: 'llm-quota',
 *     },
 *   },
 * });
 * ```
 */
export interface IAgentResilienceConfig {
    /** Default resilience settings applied to all tools */
    defaults?: {
        /** Tag of an existing quota to use by default */
        quota?: string;
        /** Tag of an existing fallback to use by default */
        fallback?: string;
        /** Tag of an existing healthcheck to verify before tool execution */
        healthcheck?: string;
    };
    /** Tool-specific resilience overrides (keyed by tool tag) */
    toolOverrides?: Record<string, IAgentToolResilienceConfig>;
}
/**
 * Full agent definition options
 */
export interface IDefineAgentOptions<TInput = Record<string, unknown>> {
    /** Target product (optional if using builder pattern) */
    product?: string;
    /** Unique agent tag */
    tag: string;
    /** Human-readable name */
    name: string;
    /** Agent description */
    description?: string;
    /**
     * Model tag referencing a model configuration defined at the product level.
     * Model configurations are managed via product.createModel() or the Ductape dashboard.
     */
    model: string;
    /**
     * Model configuration overrides applied at agent level.
     * These override settings from the referenced model entity.
     */
    modelConfig?: IModelConfigOverrides;
    /** System prompt defining agent behavior */
    systemPrompt: string;
    /** Available tools */
    tools: IAgentTool[];
    /** Termination configuration */
    termination?: IAgentTerminationConfig;
    /** Memory configuration */
    memory?: IAgentMemoryConfig;
    /** Hooks for customization */
    hooks?: IAgentHook[];
    /** Human-in-the-loop configuration */
    humanInLoop?: IHumanInLoopConfig;
    /** Streaming configuration */
    streaming?: IAgentStreamConfig;
    /** Input schema validation */
    inputSchema?: Record<string, IToolParam>;
    /** Environment configurations */
    envs?: IAgentEnvConfig[];
    /** Resilience configuration (healthchecks, quotas, fallbacks) */
    resilience?: IAgentResilienceConfig;
}
/**
 * Environment-specific agent configuration
 */
export interface IAgentEnvConfig {
    /** Environment slug */
    slug: string;
    /** Whether active in this env */
    active?: boolean;
    /** Environment-specific model tag override */
    model?: string;
    /** Environment-specific model config overrides */
    modelConfig?: IModelConfigOverrides;
    /** Environment-specific tool overrides */
    toolOverrides?: Record<string, Partial<IAgentTool>>;
}
/**
 * Defined agent (result of define())
 */
export interface IDefinedAgent {
    /** Agent tag */
    tag: string;
    /** Agent name */
    name: string;
    /** Description */
    description?: string;
    /** Model tag referencing a product-level model configuration */
    model: string;
    /** Agent-level model config overrides */
    modelConfig?: IModelConfigOverrides;
    /** System prompt */
    systemPrompt: string;
    /** Tool definitions (without handlers for storage) */
    toolSchemas: IAgentToolSchema[];
    /** Termination config */
    termination?: IAgentTerminationConfig;
    /** Memory config */
    memory?: IAgentMemoryConfig;
    /** Human-in-loop config */
    humanInLoop?: IHumanInLoopConfig;
    /** Streaming config */
    streaming?: IAgentStreamConfig;
    /** Input schema */
    inputSchema?: Record<string, IToolParam>;
    /** Environment configs */
    envs?: IAgentEnvConfig[];
    /** Resilience config */
    resilience?: IAgentResilienceConfig;
}
/**
 * Tool schema (without handler, for storage/API)
 */
export interface IAgentToolSchema {
    tag: string;
    name?: string;
    description: string;
    parameters: Record<string, IToolParam>;
    requiresConfirmation?: boolean;
    costEstimate?: number;
    timeout?: number;
    retries?: number;
    /** Tool-level resilience configuration */
    resilience?: IAgentToolResilienceConfig;
}
/**
 * Options for running an agent
 */
export interface IRunAgentOptions {
    /** Product tag */
    product: string;
    /** Environment slug */
    env: string;
    /** Agent tag */
    tag: string;
    /** Agent input */
    input: Record<string, unknown>;
    /** Initial conversation context */
    conversationContext?: IConversationMessage[];
    /** Session token in format: session_tag:jwt_token */
    session?: string;
    /** Idempotency key */
    idempotency_key?: string;
    /** Cache tag */
    cache?: string;
    /** Override termination config */
    termination?: Partial<IAgentTerminationConfig>;
    /** Runtime model configuration overrides (merged with model entity settings) */
    modelConfig?: IModelConfigOverrides;
    /** Enable streaming */
    stream?: boolean;
    /** Stream callback */
    onStream?: (event: IAgentStreamEvent) => void;
}
/**
 * Conversation message
 */
export interface IConversationMessage {
    /** Message role */
    role: 'user' | 'assistant' | 'system' | 'tool';
    /** Message content */
    content: string;
    /** Tool call info (for tool messages) */
    toolCall?: {
        id: string;
        name: string;
        input: Record<string, unknown>;
    };
    /** Tool result (for tool messages) */
    toolResult?: unknown;
    /** Timestamp */
    timestamp?: number;
}
/**
 * Agent execution state
 */
export interface IAgentState {
    /** Execution ID */
    execution_id: string;
    /** Agent tag */
    agent_tag: string;
    /** Current status */
    status: AgentStatus;
    /** Input data */
    input: Record<string, unknown>;
    /** Current iteration */
    iteration: number;
    /** Conversation history */
    conversation: IConversationMessage[];
    /** Tool call history */
    toolCalls: IToolCallResult[];
    /** Custom state data */
    data: Record<string, unknown>;
    /** Token usage */
    usage: ITokenUsage;
    /** Start timestamp */
    startedAt: number;
    /** Last update timestamp */
    updatedAt: number;
    /** Error if failed */
    error?: string;
}
/**
 * Agent execution status
 */
export type AgentStatus = 'pending' | 'running' | 'waiting_approval' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timeout';
/**
 * Token usage tracking
 */
export interface ITokenUsage {
    /** Input tokens */
    inputTokens: number;
    /** Output tokens */
    outputTokens: number;
    /** Total tokens */
    totalTokens: number;
    /** Cache read tokens */
    cacheReadTokens?: number;
    /** Cache write tokens */
    cacheWriteTokens?: number;
}
/**
 * Agent execution result
 */
export interface IAgentExecutionResult<TOutput = unknown> {
    /** Execution ID */
    execution_id: string;
    /** Final status */
    status: AgentStatus;
    /** Output data */
    output?: TOutput;
    /** Final assistant message */
    finalMessage?: string;
    /** Error message if failed */
    error?: string;
    /** Number of iterations */
    iterations: number;
    /** All tool calls made */
    toolCalls: IToolCallResult[];
    /** Token usage */
    usage: ITokenUsage;
    /** Execution time in ms */
    executionTime: number;
    /** Termination reason */
    terminationReason?: string;
}
/**
 * Context for tool handlers - provides access to Ductape components
 */
export interface IAgentToolContext {
    /** Agent input (read-only) */
    readonly input: Record<string, unknown>;
    /** Execution metadata */
    readonly execution_id: string;
    readonly agent_tag: string;
    readonly env: string;
    readonly product: string;
    /** Current iteration */
    readonly iteration: number;
    /** Get conversation history */
    getConversationHistory(): IConversationMessage[];
    /** Get tool call history */
    getToolCallHistory(): IToolCallResult[];
    /** Session token in format: session_tag:jwt_token */
    readonly session?: string;
    /** Action context */
    action: IAgentActionContext;
    /** Alias for action — preferred name for calling app actions */
    api: IAgentActionContext;
    /** Database context */
    database: IAgentDatabaseContext;
    /** Graph context */
    graph: IAgentGraphContext;
    /** Notification context */
    notification: IAgentNotificationContext;
    /** Storage context */
    storage: IAgentStorageContext;
    /** Message broker (Ductape primitive). Prefer over publish. */
    events: IAgentMessagingContext;
    /** @deprecated Prefer ctx.events.produce() */
    publish: IAgentPublishContext;
    /** Feature context */
    feature: IAgentFeatureContext;
    /** Resilience context (quotas, fallbacks, healthchecks) */
    resilience: IAgentResilienceContext;
    /** Set custom state */
    setState(key: string, value: unknown): void;
    /** Get custom state */
    getState<T>(key: string): T | undefined;
    /** Store in long-term memory */
    remember(content: string, metadata?: Record<string, unknown>): Promise<void>;
    /** Retrieve from long-term memory */
    recall(query: string, topK?: number): Promise<IMemoryResult[]>;
    /** Logger */
    log: IAgentLogger;
}
/**
 * Memory retrieval result
 */
export interface IMemoryResult {
    content: string;
    metadata?: Record<string, unknown>;
    similarity: number;
}
/**
 * Logger interface
 */
export interface IAgentLogger {
    debug(message: string, data?: Record<string, unknown>): void;
    info(message: string, data?: Record<string, unknown>): void;
    warn(message: string, data?: Record<string, unknown>): void;
    error(message: string, data?: Record<string, unknown>): void;
}
/**
 * Action context for agent tools
 */
export interface IAgentActionContext {
    run<T>(options: {
        app: string;
        event: string;
        input: IActionRequest;
        retries?: number;
        timeout?: number;
    }): Promise<T>;
}
/**
 * Database context for agent tools
 */
export interface IAgentDatabaseContext {
    execute<T>(options: {
        database: string;
        event: string;
        input: IDbActionRequest;
        retries?: number;
        timeout?: number;
    }): Promise<T>;
    query<T>(options: {
        database: string;
        event: string;
        params?: Record<string, unknown>;
    }): Promise<T[]>;
    insert<T>(options: {
        database: string;
        event: string;
        data: Record<string, unknown>;
    }): Promise<T>;
    update<T>(options: {
        database: string;
        event: string;
        data: Record<string, unknown>;
        where: Record<string, unknown>;
    }): Promise<T>;
    delete(options: {
        database: string;
        event: string;
        where: Record<string, unknown>;
    }): Promise<boolean>;
}
/**
 * Graph context for agent tools
 */
export interface IAgentGraphContext {
    execute<T>(options: {
        graph: string;
        action: string;
        input: Record<string, unknown>;
    }): Promise<T>;
    createNode<T>(options: {
        graph: string;
        labels: string[];
        properties: Record<string, unknown>;
    }): Promise<T>;
    updateNode<T>(options: {
        graph: string;
        id: string | number;
        properties: Record<string, unknown>;
    }): Promise<T>;
    deleteNode(options: {
        graph: string;
        id: string | number;
    }): Promise<void>;
    createRelationship<T>(options: {
        graph: string;
        from: string;
        to: string;
        type: string;
        properties?: Record<string, unknown>;
    }): Promise<T>;
    traverse<T>(options: {
        graph: string;
        startNodeId: string | number;
        direction?: 'outgoing' | 'incoming' | 'both';
        relationshipTypes?: string[];
        maxDepth?: number;
    }): Promise<T>;
    query<T>(options: {
        graph: string;
        action: string;
        params?: Record<string, unknown>;
    }): Promise<T[]>;
}
/**
 * Notification context for agent tools
 */
export interface IAgentNotificationContext {
    send(options: {
        notification: string;
        event: string;
        input: INotificationRequest;
        retries?: number;
    }): Promise<void>;
    email(options: {
        notification: string;
        event: string;
        recipients: string[];
        subject: Record<string, unknown>;
        template: Record<string, unknown>;
    }): Promise<void>;
    push(options: {
        notification: string;
        event: string;
        tokens: string[];
        title: Record<string, unknown>;
        body: Record<string, unknown>;
        data?: Record<string, unknown>;
    }): Promise<void>;
    sms(options: {
        notification: string;
        event: string;
        phones: string[];
        message: Record<string, unknown>;
    }): Promise<void>;
}
/**
 * Storage context for agent tools
 */
export interface IAgentStorageContext {
    upload(options: {
        storage: string;
        event: string;
        input: IStorageRequest;
        retries?: number;
    }): Promise<IFileUploadResult>;
    download(options: {
        storage: string;
        event: string;
        input: IStorageRequest;
    }): Promise<IFileDownloadResult>;
    delete(options: {
        storage: string;
        event: string;
        input: {
            file_key: string;
        };
    }): Promise<void>;
}
/**
 * Messaging context for agent tools (Ductape primitive).
 * Use ctx.events.produce() to publish to a message broker.
 */
export interface IAgentMessagingContext {
    produce(options: {
        event: string;
        message: Record<string, unknown>;
    }): Promise<void>;
}
/**
 * Publish context for agent tools
 * @deprecated Prefer ctx.events.produce()
 */
export interface IAgentPublishContext {
    send(options: {
        broker: string;
        event: string;
        input: {
            message: Record<string, unknown>;
        };
        retries?: number;
    }): Promise<void>;
}
/**
 * Feature context for agent tools
 */
export interface IAgentFeatureContext {
    run<T>(options: {
        feature: string;
        input: Record<string, unknown>;
        retries?: number;
        timeout?: number;
    }): Promise<T>;
}
/**
 * Quota context for agent resilience operations
 */
export interface IAgentQuotaContext {
    /**
     * Run an operation through a quota (weighted load balancing)
     * Distributes requests across providers based on weight
     */
    run<T>(options: {
        /** Quota tag defined at product level */
        tag: string;
        /** Input to pass to the provider */
        input: Record<string, unknown>;
        /** Session token in format: session_tag:jwt_token */
        session?: string;
    }): Promise<T>;
    /**
     * Get current quota usage/status
     */
    status(options: {
        /** Quota tag */
        tag: string;
    }): Promise<IAgentQuotaStatus>;
}
/**
 * Fallback context for agent resilience operations
 */
export interface IAgentFallbackContext {
    /**
     * Run an operation through a fallback chain
     * Tries primary provider first, falls back to alternatives on failure
     */
    run<T>(options: {
        /** Fallback tag defined at product level */
        tag: string;
        /** Input to pass to the provider */
        input: Record<string, unknown>;
        /** Session token in format: session_tag:jwt_token */
        session?: string;
    }): Promise<T>;
}
/**
 * Healthcheck context for agent resilience operations
 */
export interface IAgentHealthcheckContext {
    /**
     * Check health status of a provider/service
     */
    check(options: {
        /** Healthcheck tag defined at product level */
        tag: string;
        /** Environment to check */
        env?: string;
    }): Promise<IAgentHealthcheckResult>;
    /**
     * Get healthcheck status for all configured checks
     */
    status(): Promise<Record<string, IAgentHealthcheckResult>>;
}
/**
 * Resilience context for agent tools
 * Provides access to quota, fallback, and healthcheck operations
 *
 * @example
 * ```typescript
 * // Run through quota
 * const result = await ctx.resilience.quota.run({
 *   tag: 'llm-quota',
 *   input: { prompt: 'Hello' },
 * });
 *
 * // Run through fallback
 * const result = await ctx.resilience.fallback.run({
 *   tag: 'llm-fallback',
 *   input: { prompt: 'Hello' },
 * });
 *
 * // Check health
 * const health = await ctx.resilience.healthcheck.check({
 *   tag: 'api-health',
 * });
 * ```
 */
export interface IAgentResilienceContext {
    /** Quota operations */
    quota: IAgentQuotaContext;
    /** Fallback operations */
    fallback: IAgentFallbackContext;
    /** Healthcheck operations */
    healthcheck: IAgentHealthcheckContext;
}
/**
 * Healthcheck result
 */
export interface IAgentHealthcheckResult {
    /** Healthcheck tag */
    tag: string;
    /** Current status */
    status: 'healthy' | 'unhealthy' | 'degraded' | 'unknown';
    /** Last check timestamp */
    lastChecked?: number;
    /** Last successful check timestamp */
    lastAvailable?: number;
    /** Latency of last check in ms */
    lastLatency?: number;
    /** Average latency in ms */
    averageLatency?: number;
    /** Error message if unhealthy */
    error?: string;
}
/**
 * Quota status
 */
export interface IAgentQuotaStatus {
    /** Quota tag */
    tag: string;
    /** Total quota configured */
    totalQuota?: number;
    /** Current usage */
    usedQuota?: number;
    /** Remaining quota */
    remainingQuota?: number;
    /** Provider statuses */
    providers: Array<{
        name: string;
        weight: number;
        uses: number;
        status: 'available' | 'unavailable' | 'degraded';
        healthcheck?: string;
    }>;
}
/**
 * File upload result
 */
export interface IFileUploadResult {
    file_key: string;
    url?: string;
    size?: number;
    content_type?: string;
}
/**
 * File download result
 */
export interface IFileDownloadResult {
    content: Buffer | string;
    content_type?: string;
    size?: number;
}
/**
 * Options for converting an agent into a tool
 */
export interface IAgentAsToolOptions {
    /** Custom tool tag (defaults to agent tag) */
    toolTag?: string;
    /** Custom tool name (defaults to agent name) */
    toolName?: string;
    /** Custom tool description (defaults to agent description) */
    toolDescription?: string;
    /** Whether this agent-tool requires confirmation */
    requiresConfirmation?: boolean;
    /** Timeout for the agent execution */
    timeout?: number;
    /** Number of retries on failure */
    retries?: number;
    /** Input parameter overrides (narrow down what parent can pass) */
    inputSchema?: Record<string, IToolParam>;
    /** Transform input before passing to agent */
    inputTransform?: (params: Record<string, unknown>) => Record<string, unknown>;
    /** Transform agent output before returning to parent */
    outputTransform?: (result: IAgentExecutionResult) => unknown;
    /** Whether to include full execution details or just output */
    includeDetails?: boolean;
}
/**
 * Agent tool definition (an agent wrapped as a tool)
 */
export interface IAgentToolDefinition {
    /** Agent tag to invoke */
    agentTag: string;
    /** Product containing the agent */
    product: string;
    /** Environment to run in (inherits from parent if not specified) */
    env?: string;
    /** Tool options */
    options?: IAgentAsToolOptions;
}
/**
 * Multi-agent orchestration mode
 */
export type MultiAgentMode = 'sequential' | 'parallel' | 'hierarchical' | 'collaborative';
/**
 * Agent in a multi-agent workflow
 */
export interface IMultiAgentMember {
    /** Agent tag */
    agent: string;
    /** Role in the workflow */
    role?: string;
    /** Input mapping from orchestrator */
    inputMapping?: Record<string, string>;
    /** Condition to include this agent */
    condition?: string;
}
/**
 * Multi-agent workflow definition
 */
export interface IMultiAgentWorkflow {
    /** Feature tag */
    tag: string;
    /** Feature name */
    name: string;
    /** Orchestration mode */
    mode: MultiAgentMode;
    /** Participating agents */
    agents: IMultiAgentMember[];
    /** Orchestrator agent (for hierarchical mode) */
    orchestrator?: string;
    /** Final aggregation logic */
    aggregation?: 'merge' | 'vote' | 'first' | 'custom';
    /** Custom aggregation handler */
    aggregationHandler?: (results: IAgentExecutionResult[]) => unknown;
}
/**
 * Schedule configuration for dispatched agents
 */
export interface IAgentSchedule {
    /** Start time (timestamp or ISO string) */
    start_at?: number | string;
    /** Cron expression for recurring */
    cron?: string;
    /** Interval in ms for recurring */
    every?: number;
    /** Maximum number of executions */
    limit?: number;
    /** End date for recurring */
    endDate?: number | string;
    /** Timezone */
    tz?: string;
}
/**
 * Options for dispatching an agent
 */
export interface IDispatchAgentOptions {
    /** Product tag */
    product: string;
    /** Environment slug */
    env: string;
    /** Agent tag */
    agent: string;
    /** Agent input */
    input: Record<string, unknown>;
    /** Schedule configuration */
    schedule?: IAgentSchedule;
    /** Session token in format: session_tag:jwt_token */
    session?: string;
    /** Cache tag */
    cache?: string;
    /** Number of retries */
    retries?: number;
}
/**
 * Dispatch result
 */
export interface IDispatchAgentResult {
    /** Job ID */
    job_id: string;
    /** Job status */
    status: 'scheduled' | 'queued' | 'running';
    /** Scheduled timestamp */
    scheduled_at?: number;
    /** Whether this is a recurring job */
    recurring?: boolean;
    /** Next run timestamp (for recurring) */
    next_run_at?: number;
}
/**
 * Options for sending a signal to an agent
 */
export interface ISendAgentSignalOptions {
    /** Product tag */
    product: string;
    /** Environment slug */
    env: string;
    /** Execution ID */
    execution_id: string;
    /** Signal name */
    signal: 'stop' | 'pause' | 'resume' | 'approve' | 'reject' | 'input' | string;
    /** Signal payload */
    payload?: Record<string, unknown>;
}
/**
 * Options for getting agent execution status
 */
export interface IAgentStatusOptions {
    /** Product tag */
    product: string;
    /** Environment slug */
    env: string;
    /** Execution ID */
    execution_id: string;
}
/**
 * Options for listing agent executions
 */
export interface IListAgentExecutionsOptions {
    /** Product tag */
    product: string;
    /** Environment slug */
    env: string;
    /** Agent tag (optional filter) */
    agent?: string;
    /** Status filter */
    status?: AgentStatus | AgentStatus[];
    /** Start date filter */
    from?: number | string;
    /** End date filter */
    to?: number | string;
    /** Page number */
    page?: number;
    /** Page size */
    limit?: number;
}
/**
 * Agent execution list result
 */
export interface IAgentExecutionListResult {
    /** Executions */
    executions: Array<{
        execution_id: string;
        agent_tag: string;
        status: AgentStatus;
        startedAt: number;
        completedAt?: number;
        iterations: number;
        usage: ITokenUsage;
    }>;
    /** Total count */
    total: number;
    /** Current page */
    page: number;
    /** Page size */
    limit: number;
}
/**
 * Cost tracking data
 */
export interface IAgentCostData {
    /** Execution ID */
    execution_id: string;
    /** Token costs */
    tokenCost: {
        inputCost: number;
        outputCost: number;
        totalCost: number;
        currency: string;
    };
    /** Tool costs (if tracked) */
    toolCosts?: Record<string, number>;
    /** Total cost */
    totalCost: number;
}
/**
 * Observability event
 */
export interface IAgentObservabilityEvent {
    /** Event ID */
    id: string;
    /** Execution ID */
    execution_id: string;
    /** Event type */
    type: string;
    /** Event timestamp */
    timestamp: number;
    /** Event data */
    data: Record<string, unknown>;
    /** Span info (for tracing) */
    span?: {
        traceId: string;
        spanId: string;
        parentSpanId?: string;
    };
}
export { IActionRequest, INotificationRequest, IDbActionRequest, IStorageRequest, IStepInput, };