/**
 * Agent instance registry -- runtime tracking of live agent processes.
 *
 * Provides CRUD operations for the `agent_instances` table:
 * registration, deregistration, heartbeat, status updates, and queries.
 *
 * This is the DB-backed runtime registry for live agent *instances*.
 * The file-based registry in `skills/agents/registry.ts` tracks installed
 * agent *definitions* -- those are complementary, not competing, concepts.
 *
 * @module agents/registry
 */
import { type AgentErrorLogRow, type AgentErrorType, type AgentInstanceRow, type AgentInstanceStatus, type AgentType } from '../store/schema/agent-schema.js';
/**
 * Generate a unique agent instance ID.
 * Format: `agt_{YYYYMMDDHHmmss}_{6hex}`
 */
export declare function generateAgentId(): string;
/** Options for registering a new agent instance. */
export interface RegisterAgentOptions {
    agentType: AgentType;
    sessionId?: string;
    taskId?: string;
    parentAgentId?: string;
    metadata?: Record<string, unknown>;
}
/**
 * Register a new agent instance in the database.
 * Sets initial status to 'starting' and records the first heartbeat.
 */
export declare function registerAgent(opts: RegisterAgentOptions, cwd?: string): Promise<AgentInstanceRow>;
/**
 * Deregister (stop) an agent instance.
 * Sets status to 'stopped' and records the stop timestamp.
 */
export declare function deregisterAgent(id: string, cwd?: string): Promise<AgentInstanceRow | null>;
/**
 * Record a heartbeat for an agent instance.
 * Updates `last_heartbeat` and returns the current status so the agent
 * can detect if it has been externally marked for shutdown.
 */
export declare function heartbeat(id: string, cwd?: string): Promise<AgentInstanceStatus | null>;
/** Options for updating agent status. */
export interface UpdateStatusOptions {
    status: AgentInstanceStatus;
    error?: string;
    taskId?: string;
}
/**
 * Update agent status with optional error tracking.
 * When status is 'error' or 'crashed', increments the error count
 * and logs the error to the agent_error_log table.
 */
export declare function updateAgentStatus(id: string, opts: UpdateStatusOptions, cwd?: string): Promise<AgentInstanceRow | null>;
/**
 * Increment the completed task count for an agent.
 */
export declare function incrementTasksCompleted(id: string, cwd?: string): Promise<void>;
/** Filters for listing agent instances. */
export interface ListAgentFilters {
    status?: AgentInstanceStatus | AgentInstanceStatus[];
    agentType?: AgentType | AgentType[];
    sessionId?: string;
    parentAgentId?: string;
}
/**
 * List agent instances with optional filters.
 */
export declare function listAgentInstances(filters?: ListAgentFilters, cwd?: string): Promise<AgentInstanceRow[]>;
/**
 * Get a single agent instance by ID.
 */
export declare function getAgentInstance(id: string, cwd?: string): Promise<AgentInstanceRow | null>;
/**
 * Classify an error as retriable, permanent, or unknown.
 *
 * Retriable errors are transient conditions (network, rate limits, locks)
 * where a retry may succeed. Permanent errors are structural (auth,
 * not found, constraint violations) where retrying is pointless.
 */
export declare function classifyError(error: unknown): AgentErrorType;
/**
 * Get the error history for a specific agent.
 */
export declare function getAgentErrorHistory(agentId: string, cwd?: string): Promise<AgentErrorLogRow[]>;
/**
 * Check agent health by finding instances whose last heartbeat exceeds the threshold.
 * Default threshold: 30000ms (30 seconds) as specified by the BRAIN spec.
 *
 * Returns agents that appear to have crashed (stale heartbeat).
 */
export declare function checkAgentHealth(thresholdMs?: number, cwd?: string): Promise<AgentInstanceRow[]>;
/**
 * Mark an agent instance as crashed.
 * Increments error count and sets status to 'crashed'.
 */
export declare function markCrashed(id: string, reason?: string, cwd?: string): Promise<AgentInstanceRow | null>;
/** Agent health report summary. */
export interface AgentHealthReport {
    total: number;
    active: number;
    idle: number;
    starting: number;
    error: number;
    crashed: number;
    stopped: number;
    totalErrors: number;
    staleAgents: AgentInstanceRow[];
}
/**
 * Generate a health report summarizing all agent instances.
 * Includes counts by status and identifies stale agents.
 */
export declare function getHealthReport(thresholdMs?: number, cwd?: string): Promise<AgentHealthReport>;
//# sourceMappingURL=registry.d.ts.map