/**
 * @module agent-sdk
 * Agent builder wrapper for AI-first interface
 *
 * Provides simplified agent creation with ephemeral identities,
 * policy constraints, and automatic lifecycle management.
 */
import type { Result } from '@private.me/shared';
import type { AgentIdentity } from './identity.js';
import type { AgentCallOptions, PolicyConstraints, CallResult } from './agent-call.js';
import { AgentError } from './agent-call.js';
/**
 * Options for Agent.create()
 */
export interface AgentCreateOptions {
    /** Agent name (for logging/debugging) */
    name: string;
    /**
     * Identity mode:
     * - 'ephemeral': Auto-generated, short-lived identity (default)
     * - 'persistent': Manually provided identity (via seed or AgentIdentity)
     * - AgentIdentity: Use existing identity
     * - Uint8Array: 32-byte seed for deterministic identity
     */
    identity?: 'ephemeral' | 'persistent' | AgentIdentity | Uint8Array;
    /**
     * Policy constraints for limiting agent actions.
     *
     * These constraints are enforced on every .call() invocation.
     */
    policy?: PolicyConstraints;
    /**
     * Time-to-live for ephemeral identities (milliseconds).
     *
     * After this duration, the agent is auto-cleaned up.
     * Only applies when identity === 'ephemeral'.
     *
     * Default: 3600000 (1 hour)
     */
    ttl?: number;
}
/**
 * Agent builder - AI-first wrapper for xBind agent creation
 *
 * Provides high-level API for creating agents with automatic
 * identity management, policy enforcement, and lifecycle cleanup.
 *
 * This is the simplified xBind agent builder for AI agents. For full
 * transport-level control, use the Agent class from './agent.js'.
 *
 * @example
 * ```typescript
 * // Create ephemeral agent (auto-cleanup after 1 hour)
 * const agent = await AgentBuilder.create({
 *   name: "invoice-agent",
 *   policy: {
 *     allowedTools: ["payments:createCharge", "payments:refund"],
 *     limits: {
 *       amountPerTxn: 1000,
 *       dailyAmount: 10000
 *     }
 *   }
 * });
 *
 * // Use agent to call tools
 * const result = await agent.call("payments:createCharge", {
 *   amount: 100,
 *   currency: "USD"
 * });
 * ```
 */
export declare class AgentBuilder {
    /** Agent identity (cryptographic keys + DID) */
    private readonly _identity;
    /** Agent metadata */
    private readonly _metadata;
    /** Policy constraints (optional) */
    private readonly _policy?;
    /**
     * Create a new AgentBuilder instance.
     *
     * @param identity - Agent identity
     * @param metadata - Agent metadata
     * @param policy - Optional policy constraints
     */
    private constructor();
    /**
     * Agent DID (decentralized identifier).
     */
    get did(): string;
    /**
     * Agent name.
     */
    get name(): string;
    /**
     * Creation timestamp (milliseconds since epoch).
     */
    get created(): number;
    /**
     * Identity mode ('ephemeral' or 'persistent').
     */
    get identityMode(): 'ephemeral' | 'persistent';
    /**
     * Time-to-live for ephemeral agents (milliseconds).
     * Returns undefined for persistent agents.
     */
    get ttl(): number | undefined;
    /**
     * Time remaining until auto-cleanup (milliseconds).
     * Returns undefined for persistent agents or if already expired.
     */
    get timeRemaining(): number | undefined;
    /**
     * Create a new agent instance.
     *
     * @param options - Agent creation options
     * @returns AgentBuilder instance or error
     *
     * @example
     * ```typescript
     * // Ephemeral agent (default)
     * const agent = await AgentBuilder.create({
     *   name: "task-agent",
     *   policy: {
     *     allowedTools: ["slack:sendMessage"],
     *     limits: { callsPerMinute: 10 }
     *   }
     * });
     * ```
     *
     * @example
     * ```typescript
     * // Persistent agent from seed
     * const seed = new Uint8Array(32);
     * crypto.getRandomValues(seed);
     *
     * const agent = await AgentBuilder.create({
     *   name: "persistent-agent",
     *   identity: seed, // Deterministic DID
     * });
     * ```
     */
    static create(options: AgentCreateOptions): Promise<Result<AgentBuilder, AgentError>>;
    /**
     * Call a tool/service via xBind.
     *
     * This method wraps agent-call.ts call() function with agent context
     * and enforces policy constraints defined during agent creation.
     *
     * @param tool - Tool alias (e.g., "stripe:createCharge")
     * @param params - Parameters to pass to the tool
     * @param options - Optional call options (overrides agent policy)
     * @returns Result with response data and audit receipt, or error
     *
     * @example
     * ```typescript
     * const result = await agent.call("payments:createCharge", {
     *   amount: 100,
     *   currency: "USD"
     * });
     *
     * if (!result.ok) {
     *   console.error(`Payment failed: ${result.error.message}`);
     *   return;
     * }
     *
     * console.log(`Charge created: ${result.value.data.id}`);
     * console.log(`Audit: ${result.value.audit.timestamp}`);
     * ```
     */
    call<T = unknown>(tool: string, params: unknown, options?: AgentCallOptions): Promise<Result<CallResult<T>, AgentError>>;
    /**
     * Cleanup agent resources.
     *
     * For ephemeral agents, this clears the cleanup timer and marks
     * the agent as cleaned up. For persistent agents, this is a no-op.
     *
     * This method is called automatically when TTL expires for ephemeral agents.
     */
    cleanup(): void;
    /**
     * Extend TTL for ephemeral agents.
     *
     * @param additionalTime - Additional time in milliseconds
     * @returns true if extended, false if not an ephemeral agent
     *
     * @example
     * ```typescript
     * // Extend by 30 minutes
     * agent.extendTTL(30 * 60 * 1000);
     * ```
     */
    extendTTL(additionalTime: number): boolean;
    /**
     * Convert agent to JSON-serializable format.
     *
     * @returns Agent metadata (without private keys)
     */
    toJSON(): {
        name: string;
        did: string;
        created: number;
        identityMode: 'ephemeral' | 'persistent';
        ttl?: number;
        timeRemaining?: number;
    };
}
