@stoneforge/smithy 0.1.0

package/dist/services/agent-pool-service.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 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

package/dist/services/agent-pool-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-pool-service.d.ts","sourceRoot":"","sources":["../../src/services/agent-pool-service.ts"],"names":[],"mappings":"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"}