import type { OwnerShipMeta } from '@contractspec/lib.contracts-spec/ownership';
import type { KnowledgeCategory } from '@contractspec/lib.contracts-spec/knowledge/spec';
import type { PolicyRef } from '@contractspec/lib.contracts-spec/policy/spec';
/**
 * Metadata for an agent specification.
 */
export type AgentMeta = OwnerShipMeta;
export type AgentRuntimeAdapterKey = 'langgraph' | 'langchain' | 'workflow-devkit';
export interface AgentRuntimeCapabilities {
    /** Optional external adapter availability map for runtime interoperability. */
    adapters?: Partial<Record<AgentRuntimeAdapterKey, boolean>>;
    /** Whether the agent should persist checkpoints for replay/resume. */
    checkpointing?: boolean;
    /** Whether the agent supports external suspend/resume semantics. */
    suspendResume?: boolean;
    /** Whether the agent can delegate approvals to external gateways. */
    approvalGateway?: boolean;
}
export interface AgentRuntimePorts {
    /** Symbolic checkpoint store adapter identifier. */
    checkpointStore?: string;
    /** Symbolic suspend/resume adapter identifier. */
    suspension?: string;
    /** Symbolic retry classifier identifier. */
    retryClassifier?: string;
    /** Symbolic approval gateway identifier. */
    approvalGateway?: string;
}
export interface AgentRuntimeConfig {
    capabilities?: AgentRuntimeCapabilities;
    ports?: AgentRuntimePorts;
}
/**
 * Configuration for a tool that an agent can use.
 */
export interface AgentToolConfig {
    /** Tool name (unique within the agent) */
    name: string;
    /** Human-readable description for the LLM */
    description?: string;
    /** JSON Schema fragment for tool parameters */
    schema?: Record<string, unknown>;
    /** Optional cooldown in milliseconds between invocations */
    cooldownMs?: number;
    /** Maximum execution time before timeout */
    timeoutMs?: number;
    /** Whether the tool can be executed without human approval (AI SDK needsApproval = !automationSafe) */
    automationSafe?: boolean;
    /** Explicit approval requirement (overrides automationSafe) */
    requiresApproval?: boolean;
    /** Optional policy guard that must evaluate to allow the tool call */
    policy?: PolicyRef;
}
/**
 * Reference to a knowledge space that the agent can access.
 */
export interface AgentKnowledgeRef {
    /** Knowledge space key */
    key: string;
    /** Optional specific version */
    version?: number;
    /** Filter by knowledge category */
    category?: KnowledgeCategory;
    /** Whether the knowledge is required (static injection) or optional (dynamic RAG) */
    required?: boolean;
    /** Additional instructions appended when the space is available */
    instructions?: string;
}
/**
 * Memory configuration for agent session persistence.
 */
export interface AgentMemoryConfig {
    /** Maximum entries to keep in memory */
    maxEntries?: number;
    /** Time-to-live in minutes */
    ttlMinutes?: number;
    /** Number of messages before triggering summarization */
    summaryTrigger?: number;
    /** Whether to persist to long-term storage */
    persistLongTerm?: boolean;
}
/**
 * Confidence policy for agent responses.
 */
export interface AgentConfidencePolicy {
    /** Minimum acceptable confidence before escalation. Defaults to 0.7 */
    min?: number;
    /** Default value used when provider does not report confidence */
    default?: number;
}
/**
 * Escalation policy for handling uncertain or failed agent responses.
 */
export interface AgentEscalationPolicy {
    /** Auto escalate when confidence < threshold */
    confidenceThreshold?: number;
    /** Escalate when a tool throws irrecoverable errors */
    onToolFailure?: boolean;
    /** Escalate when iteration budget exceeded */
    onTimeout?: boolean;
    /** Optional human approval workflow ID */
    approvalWorkflow?: string;
}
/**
 * Combined policy configuration for an agent.
 */
export interface AgentPolicy {
    confidence?: AgentConfidencePolicy;
    escalation?: AgentEscalationPolicy;
    /** Feature flags to apply to this agent */
    flags?: string[];
}
/**
 * Complete specification for a ContractSpec agent.
 */
export interface AgentSpec {
    meta: AgentMeta;
    /** System instructions for the agent */
    instructions: string;
    /** Human-readable description */
    description?: string;
    /** Tags for categorization */
    tags?: string[];
    /** Default locale for the agent (e.g., 'en', 'fr'). Falls back to 'en' if unset. */
    locale?: string;
    /** Tools the agent can use */
    tools: AgentToolConfig[];
    /** Memory/session configuration */
    memory?: AgentMemoryConfig;
    /** Knowledge spaces the agent can access */
    knowledge?: AgentKnowledgeRef[];
    /** Policy configuration */
    policy?: AgentPolicy;
    /** Runtime adapter and portability config. */
    runtime?: AgentRuntimeConfig;
    /** Maximum steps per generation (defaults to 10) */
    maxSteps?: number;
}
/**
 * Define and validate an agent specification.
 *
 * @param spec - The agent specification
 * @returns The frozen, validated specification
 * @throws Error if the specification is invalid
 */
export declare function defineAgent(spec: AgentSpec): AgentSpec;
/**
 * Generate a unique key for an agent spec.
 */
export declare function agentKey(meta: AgentMeta): string;
