@ductape/sdk 0.0.4-v6 → 0.0.4-v61

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

@@ -0,0 +1,1227 @@
+/**
+ * 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;
+    /** Publish context */
+    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>;
+}
+/**
+ * Publish context for agent tools
+ */
+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, };