@ductape/sdk 0.1.6 → 0.1.8

package/dist/agents/types/agents.types.d.ts

@@ -1,1240 +0,0 @@
-/**
- * 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, IFeatureInput } 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;
-    /** Database context */
-    database: IAgentDatabaseContext;
-    /** Graph context */
-    graph: IAgentGraphContext;
-    /** Notification context */
-    notification: IAgentNotificationContext;
-    /** Storage context */
-    storage: IAgentStorageContext;
-    /** Message broker (Ductape primitive). Prefer over publish. */
-    messaging: IAgentMessagingContext;
-    /** @deprecated Prefer ctx.messaging.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.messaging.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.messaging.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 {
-    /** Workflow tag */
-    tag: string;
-    /** Workflow 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, IFeatureInput, };