/**
 * Agent Pool Service
 *
 * This service manages agent pools - configurations that limit the maximum
 * number of agents running concurrently. The dispatch daemon consults this
 * service before spawning agents to ensure pool limits are respected.
 *
 * Key features:
 * - Create, update, delete agent pools
 * - Track active agents per pool (via session manager integration)
 * - Check spawn permissions based on pool capacity
 * - Priority-based agent type selection when pool has limited slots
 *
 * @module
 */
import type { EntityId, ElementId } from '@stoneforge/core';
import type { QuarryAPI } from '@stoneforge/quarry';
import type { AgentRole, WorkerMode, StewardFocus, AgentPoolStatus, AgentPool, AgentPoolFilter, CreatePoolInput, UpdatePoolInput, PoolSpawnCheck, PoolSpawnRequest } from '../types/index.js';
import type { SessionManager } from '../runtime/session-manager.js';
import type { AgentRegistry } from './agent-registry.js';
/**
 * Agent Pool Service interface for managing agent concurrency limits.
 *
 * The service provides methods for:
 * - Creating and managing pool configurations
 * - Checking pool capacity before spawning agents
 * - Tracking active agents per pool
 * - Priority-based spawn decisions
 */
export interface AgentPoolService {
    /**
     * Creates a new agent pool.
     *
     * @param input - Pool creation input
     * @returns The created pool
     */
    createPool(input: CreatePoolInput): Promise<AgentPool>;
    /**
     * Gets a pool by ID.
     *
     * @param poolId - The pool element ID
     * @returns The pool or undefined if not found
     */
    getPool(poolId: ElementId): Promise<AgentPool | undefined>;
    /**
     * Gets a pool by name.
     *
     * @param name - The pool name
     * @returns The pool or undefined if not found
     */
    getPoolByName(name: string): Promise<AgentPool | undefined>;
    /**
     * Lists all pools matching the filter.
     *
     * @param filter - Optional filter criteria
     * @returns Array of pools
     */
    listPools(filter?: AgentPoolFilter): Promise<AgentPool[]>;
    /**
     * Updates a pool configuration.
     *
     * @param poolId - The pool element ID
     * @param updates - The updates to apply
     * @returns The updated pool
     */
    updatePool(poolId: ElementId, updates: UpdatePoolInput): Promise<AgentPool>;
    /**
     * Deletes a pool.
     *
     * @param poolId - The pool element ID
     */
    deletePool(poolId: ElementId): Promise<void>;
    /**
     * Gets the current status of a pool (active count, available slots).
     *
     * @param poolId - The pool element ID
     * @returns The pool status
     */
    getPoolStatus(poolId: ElementId): Promise<AgentPoolStatus>;
    /**
     * Refreshes the status of all pools based on current sessions.
     * This synchronizes pool status with the actual running agents.
     */
    refreshAllPoolStatus(): Promise<void>;
    /**
     * Checks if an agent can be spawned based on pool constraints.
     * Returns information about which pool governs the decision.
     *
     * @param request - The spawn request with agent type information
     * @returns The spawn check result
     */
    canSpawn(request: PoolSpawnRequest): Promise<PoolSpawnCheck>;
    /**
     * Gets all pools that an agent type belongs to.
     *
     * @param role - The agent role
     * @param workerMode - Worker mode (for workers)
     * @param stewardFocus - Steward focus (for stewards)
     * @returns Array of pools containing this agent type
     */
    getPoolsForAgentType(role: Exclude<AgentRole, 'director'>, workerMode?: WorkerMode, stewardFocus?: StewardFocus): Promise<AgentPool[]>;
    /**
     * Determines the next agent type to spawn based on priority.
     * Used when a pool has available slots and multiple pending tasks.
     *
     * @param poolId - The pool element ID
     * @param pendingRequests - Array of pending spawn requests
     * @returns The highest priority request that can be spawned, or undefined
     */
    getNextSpawnPriority(poolId: ElementId, pendingRequests: PoolSpawnRequest[]): Promise<PoolSpawnRequest | undefined>;
    /**
     * Notifies the service that an agent has been spawned.
     * Updates pool status accordingly.
     *
     * @param agentId - The spawned agent ID
     */
    onAgentSpawned(agentId: EntityId): Promise<void>;
    /**
     * Notifies the service that an agent session has ended.
     * Updates pool status accordingly.
     *
     * @param agentId - The agent ID whose session ended
     */
    onAgentSessionEnded(agentId: EntityId): Promise<void>;
}
/**
 * Implementation of the Agent Pool Service.
 */
export declare class AgentPoolServiceImpl implements AgentPoolService {
    private readonly api;
    private readonly sessionManager;
    private readonly agentRegistry;
    /**
     * In-memory cache of pool status.
     * Key: pool ID, Value: status
     */
    private readonly statusCache;
    constructor(api: QuarryAPI, sessionManager: SessionManager, agentRegistry: AgentRegistry);
    createPool(input: CreatePoolInput): Promise<AgentPool>;
    getPool(poolId: ElementId): Promise<AgentPool | undefined>;
    getPoolByName(name: string): Promise<AgentPool | undefined>;
    listPools(filter?: AgentPoolFilter): Promise<AgentPool[]>;
    updatePool(poolId: ElementId, updates: UpdatePoolInput): Promise<AgentPool>;
    deletePool(poolId: ElementId): Promise<void>;
    getPoolStatus(poolId: ElementId): Promise<AgentPoolStatus>;
    refreshAllPoolStatus(): Promise<void>;
    canSpawn(request: PoolSpawnRequest): Promise<PoolSpawnCheck>;
    getPoolsForAgentType(role: Exclude<AgentRole, 'director'>, workerMode?: WorkerMode, stewardFocus?: StewardFocus): Promise<AgentPool[]>;
    getNextSpawnPriority(poolId: ElementId, pendingRequests: PoolSpawnRequest[]): Promise<PoolSpawnRequest | undefined>;
    onAgentSpawned(agentId: EntityId): Promise<void>;
    onAgentSessionEnded(agentId: EntityId): Promise<void>;
    /**
     * Converts an Entity to an AgentPool
     */
    private entityToPool;
    /**
     * Computes the current pool status from session manager
     */
    private computePoolStatus;
    /**
     * Checks if an agent is governed by a pool configuration
     */
    private isAgentGovernedByPool;
    /**
     * Finds the matching type config for a spawn request
     */
    private findMatchingTypeConfig;
    /**
     * Gets a type key for a spawn request (for activeByType tracking)
     */
    private getTypeKey;
    /**
     * Gets a type key for an agent entity
     */
    private getAgentTypeKey;
}
/**
 * Creates an AgentPoolService instance
 */
export declare function createAgentPoolService(api: QuarryAPI, sessionManager: SessionManager, agentRegistry: AgentRegistry): AgentPoolService;
//# sourceMappingURL=agent-pool-service.d.ts.map