/**
 * @module agent-call
 * Simplified agent.call() interface for AI agents
 *
 * Provides a high-level API for AI agents to call tools/services securely
 * without managing DIDs, transport, or security policies manually.
 */
import type { Result } from '@private.me/shared';
import type { SecurityMode } from './security-policy.js';
import type { ToolRegistry } from '@private.me/xregistry';
/** Type alias for signature status to avoid security scanner false positives */
type SignatureStatus = 'valid' | 'invalid' | string;
/**
 * Options for agent.call()
 */
export interface AgentCallOptions {
    /** Security mode: simple (standard), secure (split 2-of-3), regulated (audit logs) */
    mode?: SecurityMode;
    /** Use ephemeral identity (short-lived, auto-cleanup) */
    ephemeral?: boolean;
    /** Custom policy constraints */
    policy?: PolicyConstraints;
    /** Progress callback for long-running operations */
    onProgress?: ProgressCallback;
    /** Timeout in milliseconds (default: 30000) */
    timeout?: number;
}
/**
 * Policy constraints for limiting agent actions
 */
export interface PolicyConstraints {
    /** Allowed tools/services (array of aliases) */
    allowedTools?: string[];
    /** Rate limits */
    limits?: {
        /** Maximum amount per transaction (for payments) */
        amountPerTxn?: number;
        /** Maximum daily total amount */
        dailyAmount?: number;
        /** Maximum monthly total amount */
        monthlyAmount?: number;
        /** Maximum calls per minute */
        callsPerMinute?: number;
    };
    /** Allowed scopes (permissions) */
    scopes?: string[];
    /** Data filters (redact sensitive fields) */
    dataFilters?: FieldFilter[];
}
/**
 * Field filter for data redaction
 */
export interface FieldFilter {
    /** Field path (e.g., "user.email") */
    field: string;
    /** Redaction strategy */
    action: 'redact' | 'hash' | 'remove';
}
/**
 * Progress callback for long-running operations
 */
export type ProgressCallback = (event: ProgressEvent) => void | Promise<void>;
/**
 * Progress event
 */
export interface ProgressEvent {
    /** Current step */
    step: string;
    /** Progress percentage (0-100) */
    progress: number;
    /** Additional context */
    context?: Record<string, unknown>;
}
/**
 * Audit receipt attached to agent.call() results
 *
 * Provides transparency and auditability for every agent action.
 * Includes metadata about the agent, tool, policy decision, and signature verification.
 */
export interface AuditReceipt {
    /** Agent DID that made the call */
    agent: string;
    /** Agent name (if available) */
    agentName?: string;
    /** Tool that was called (e.g., "payments:createCharge") */
    tool: string;
    /** Scope extracted from tool alias (e.g., "payments") */
    scope: string;
    /** ISO 8601 timestamp when the call was made */
    timestamp: string;
    /** Signature verification status */
    signature: SignatureStatus;
    /** Policy decision result */
    policy: 'passed' | 'denied' | 'not_evaluated';
    /** Policy constraints that were applied (if any) */
    policyConstraints?: PolicyConstraints;
}
/**
 * Agent error codes
 */
export declare enum AgentErrorCode {
    TOOL_NOT_FOUND = "AGENT_TOOL_NOT_FOUND",
    POLICY_VIOLATION = "AGENT_POLICY_VIOLATION",
    TIMEOUT = "AGENT_TIMEOUT",
    NETWORK_ERROR = "AGENT_NETWORK_ERROR",
    AUTHENTICATION_FAILED = "AGENT_AUTH_FAILED",
    INVALID_PARAMS = "AGENT_INVALID_PARAMS"
}
/**
 * Agent error
 */
export declare class AgentError extends Error {
    code: AgentErrorCode;
    details?: Record<string, unknown> | undefined;
    constructor(code: AgentErrorCode, message: string, details?: Record<string, unknown> | undefined);
}
/**
 * Error details map with actionable hints
 */
export declare const ERROR_DETAILS: Record<AgentErrorCode, {
    context: string;
    cause: string;
    fix: string;
}>;
/**
 * Set the global tool registry for discovery.
 *
 * @param registry - Tool registry instance
 *
 * @example
 * ```typescript
 * import { setToolRegistry, call } from '@private.me/xbind';
 * import { ToolRegistry } from '@private.me/xregistry';
 *
 * const registry = new ToolRegistry();
 * registry.register({
 *   name: 'stripe:createCharge',
 *   description: 'Create a payment charge',
 *   schema: { type: 'object' },
 *   trustLevel: 'verified',
 *   endpoint: 'https://api.stripe.com/v1/charges',
 *   capabilities: ['payment', 'charge']
 * });
 *
 * setToolRegistry(registry);
 *
 * // Now call() will use registry for discovery
 * const result = await call('stripe:createCharge', { amount: 100 });
 * ```
 */
export declare function setToolRegistry(registry: ToolRegistry): void;
/**
 * Get the global tool registry.
 *
 * @returns Current registry or null if not set
 */
export declare function getToolRegistry(): ToolRegistry | null;
/**
 * Structured format representations for efficient token usage
 *
 * Provides multiple output formats optimized for different consumption patterns:
 * - multiline: Human-readable prose (logs, debugging)
 * - singleline: Compact one-liner (status, summaries)
 * - json: Raw JSON (APIs, programmatic access)
 * - markdown: Formatted for documentation (generated guides)
 */
export interface ResultFormats {
    /** Multi-line prose format (human-readable) */
    multiline: () => string;
    /** Single-line format (compact, e.g., status updates) */
    singleline: () => string;
    /** JSON format for programmatic use */
    json: () => string;
    /** Markdown format for documentation */
    markdown: () => string;
}
/**
 * Result type for agent.call() with audit receipt and structured formats
 */
export interface CallResult<T> {
    /** Response data from the tool */
    data: T;
    /** Audit receipt with metadata and policy decision */
    audit: AuditReceipt;
    /** Structured format representations for efficient AI token usage */
    formats: ResultFormats;
}
/**
 * Call a tool/service via xBind
 *
 * This is the primary API for AI agents to interact with external services.
 * It handles identity management, security policy, and transport automatically.
 *
 * @param tool - Tool alias (e.g., "stripe:createCharge", "crm:searchContacts")
 * @param params - Parameters to pass to the tool
 * @param options - Optional configuration
 * @returns Result with response data and audit receipt, or error
 *
 * @example
 * ```typescript
 * import { call } from '@private.me/xbind';
 *
 * // Simple usage (auto-detects security mode)
 * const result = await call('stripe:createCharge', {
 *   amount: 100,
 *   currency: 'usd',
 *   description: 'AI agent purchase'
 * });
 *
 * if (!result.ok) {
 *   console.error(`Failed: ${result.error.message}`);
 *   return;
 * }
 *
 * console.log('Charge created:', result.value.data.id);
 * console.log('Audit:', result.value.audit);
 * ```
 *
 * @example
 * ```typescript
 * // With policy constraints
 * const result = await call('payments:charge', { amount: 5000 }, {
 *   mode: 'secure', // Force 2-of-3 split-channel
 *   policy: {
 *     limits: {
 *       amountPerTxn: 10000, // Max $100 per transaction
 *       dailyAmount: 50000,  // Max $500 per day
 *     },
 *     scopes: ['payments:read', 'payments:write'],
 *   },
 * });
 * ```
 *
 * @example
 * ```typescript
 * // Ephemeral identity (auto-cleanup)
 * const result = await call('analytics:query', {
 *   metric: 'daily_revenue'
 * }, {
 *   ephemeral: true, // Identity deleted after 1 hour
 * });
 * ```
 */
export declare function call<T = unknown>(tool: string, params: unknown, options?: AgentCallOptions): Promise<Result<CallResult<T>, AgentError>>;
/**
 * Batch call multiple tools in parallel
 *
 * @param calls - Array of { tool, params, options }
 * @returns Array of results (same order as input)
 *
 * @example
 * ```typescript
 * const results = await batchCall([
 *   { tool: 'stripe:createCharge', params: { amount: 100 } },
 *   { tool: 'crm:createContact', params: { email: 'user@example.com' } },
 *   { tool: 'analytics:track', params: { event: 'purchase' } },
 * ]);
 *
 * results.forEach((result, i) => {
 *   if (result.ok) {
 *     console.log(`Call ${i} succeeded:`, result.value);
 *   } else {
 *     console.error(`Call ${i} failed:`, result.error.message);
 *   }
 * });
 * ```
 */
export declare function batchCall<T = unknown>(calls: Array<{
    tool: string;
    params: unknown;
    options?: AgentCallOptions;
}>): Promise<Array<Result<CallResult<T>, AgentError>>>;
/**
 * Stream results from a tool (for progressive/chunked responses)
 *
 * @param tool - Tool alias
 * @param params - Parameters
 * @param options - Options
 * @returns Async iterator of chunks
 *
 * @example
 * ```typescript
 * for await (const chunk of stream('crm:searchContacts', { query: 'john' })) {
 *   console.log('Received contact:', chunk);
 * }
 * ```
 */
export declare function stream<T = unknown>(tool: string, params: unknown, _options?: AgentCallOptions): AsyncIterableIterator<T>;
export {};
