@herdctl/core 0.0.1

package/dist/fleet-manager/job-queue.d.ts

@@ -0,0 +1,422 @@
+/**
+ * Job Queue module for concurrency control
+ *
+ * Provides a job queue with per-agent and fleet-wide concurrency limits.
+ * Jobs queue when limits are reached and are processed FIFO within priority levels.
+ *
+ * @example
+ * ```typescript
+ * const queue = new JobQueue({
+ *   defaultAgentConcurrency: 1,
+ *   fleetConcurrency: 10,
+ * });
+ *
+ * // Enqueue a job
+ * const result = queue.enqueue({
+ *   agentName: 'my-agent',
+ *   scheduleName: 'hourly',
+ *   priority: 5,
+ * });
+ *
+ * if (result.queued) {
+ *   console.log(`Job queued at position ${result.position}`);
+ * } else {
+ *   console.log(`Job ready to run: ${result.jobId}`);
+ * }
+ *
+ * // Dequeue when ready
+ * const job = queue.dequeue('my-agent');
+ * ```
+ */
+import { EventEmitter } from "node:events";
+/**
+ * Priority level for queued jobs
+ * Lower numbers = higher priority
+ * Default priority is 5 (normal)
+ */
+export type JobPriority = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+/**
+ * Configuration options for the JobQueue
+ */
+export interface JobQueueOptions {
+    /**
+     * Default concurrency limit per agent
+     * Can be overridden per-agent via setAgentConcurrency()
+     * Default: 1
+     */
+    defaultAgentConcurrency?: number;
+    /**
+     * Fleet-wide concurrency limit (optional)
+     * When set, limits total concurrent jobs across all agents
+     * Default: undefined (no fleet-wide limit)
+     */
+    fleetConcurrency?: number;
+    /**
+     * Logger for queue operations
+     */
+    logger?: JobQueueLogger;
+}
+/**
+ * Logger interface for job queue operations
+ */
+export interface JobQueueLogger {
+    debug: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+/**
+ * A queued job entry
+ */
+export interface QueuedJob {
+    /**
+     * Unique ID for this queued job
+     */
+    id: string;
+    /**
+     * Name of the agent this job is for
+     */
+    agentName: string;
+    /**
+     * Name of the schedule that triggered this job (optional)
+     */
+    scheduleName?: string;
+    /**
+     * Job priority (1-10, lower = higher priority)
+     * Default: 5 (normal)
+     */
+    priority: JobPriority;
+    /**
+     * ISO timestamp when the job was queued
+     */
+    queuedAt: string;
+    /**
+     * Prompt override for this job (optional)
+     */
+    prompt?: string;
+    /**
+     * Whether this is from a scheduled trigger
+     */
+    isScheduled: boolean;
+}
+/**
+ * Options for enqueueing a job
+ */
+export interface EnqueueOptions {
+    /**
+     * Name of the agent to run
+     */
+    agentName: string;
+    /**
+     * Name of the schedule (optional)
+     */
+    scheduleName?: string;
+    /**
+     * Job priority (1-10, lower = higher priority)
+     * Default: 5
+     */
+    priority?: JobPriority;
+    /**
+     * Prompt override (optional)
+     */
+    prompt?: string;
+    /**
+     * Whether this is from a scheduled trigger
+     * Scheduled triggers are NOT queued - they emit schedule:skipped instead
+     * Default: false
+     */
+    isScheduled?: boolean;
+}
+/**
+ * Result of enqueueing a job
+ */
+export interface EnqueueResult {
+    /**
+     * The queued job ID
+     */
+    jobId: string;
+    /**
+     * Whether the job was actually queued (vs ready to run immediately)
+     */
+    queued: boolean;
+    /**
+     * Position in the queue (1-based) if queued
+     * Undefined if not queued (ready to run)
+     */
+    position?: number;
+    /**
+     * Reason the job was queued, if applicable
+     */
+    reason?: "agent_at_capacity" | "fleet_at_capacity";
+}
+/**
+ * Result when a scheduled job is skipped due to concurrency
+ */
+export interface ScheduleSkipResult {
+    /**
+     * The agent that was at capacity
+     */
+    agentName: string;
+    /**
+     * The schedule that was skipped
+     */
+    scheduleName?: string;
+    /**
+     * Reason for skipping
+     */
+    reason: "agent_at_capacity" | "fleet_at_capacity";
+    /**
+     * Current running count
+     */
+    currentRunning: number;
+    /**
+     * The limit that was hit
+     */
+    limit: number;
+}
+/**
+ * Status of the job queue for a specific agent
+ */
+export interface AgentQueueStatus {
+    /**
+     * Name of the agent
+     */
+    agentName: string;
+    /**
+     * Number of jobs currently running for this agent
+     */
+    runningCount: number;
+    /**
+     * Maximum concurrent jobs allowed for this agent
+     */
+    maxConcurrent: number;
+    /**
+     * Number of jobs queued for this agent
+     */
+    queuedCount: number;
+    /**
+     * The queued jobs for this agent (in order)
+     */
+    queuedJobs: QueuedJob[];
+}
+/**
+ * Overall queue status
+ */
+export interface QueueStatus {
+    /**
+     * Total jobs currently running across all agents
+     */
+    totalRunning: number;
+    /**
+     * Fleet-wide concurrency limit (if set)
+     */
+    fleetConcurrency: number | null;
+    /**
+     * Default per-agent concurrency limit
+     */
+    defaultAgentConcurrency: number;
+    /**
+     * Total jobs queued across all agents
+     */
+    totalQueued: number;
+    /**
+     * Per-agent queue status
+     */
+    agents: Map<string, AgentQueueStatus>;
+}
+/**
+ * Events emitted by the JobQueue
+ */
+export interface JobQueueEventMap {
+    /**
+     * Emitted when a job is enqueued
+     */
+    "job:queued": [job: QueuedJob, position: number];
+    /**
+     * Emitted when a job is dequeued and ready to run
+     */
+    "job:dequeued": [job: QueuedJob];
+    /**
+     * Emitted when a scheduled trigger is skipped due to concurrency
+     */
+    "schedule:skipped": [result: ScheduleSkipResult];
+    /**
+     * Emitted when a job completes and capacity becomes available
+     */
+    "capacity:available": [agentName: string, available: number];
+}
+/**
+ * Job queue with concurrency control
+ *
+ * Manages a FIFO queue (within priority levels) with:
+ * - Per-agent concurrency limits
+ * - Optional fleet-wide concurrency limit
+ * - Priority-based ordering (lower number = higher priority)
+ *
+ * Scheduled triggers are NOT queued - instead, a schedule:skipped event
+ * is emitted when the agent or fleet is at capacity.
+ */
+export declare class JobQueue extends EventEmitter {
+    private readonly defaultAgentConcurrency;
+    private readonly fleetConcurrency;
+    private readonly logger;
+    private readonly agentConcurrencyLimits;
+    private readonly runningJobs;
+    private readonly queuedJobs;
+    private totalRunningCount;
+    constructor(options?: JobQueueOptions);
+    /**
+     * Set the concurrency limit for a specific agent
+     *
+     * @param agentName - The agent name
+     * @param limit - The concurrency limit (must be >= 1)
+     */
+    setAgentConcurrency(agentName: string, limit: number): void;
+    /**
+     * Get the concurrency limit for an agent
+     *
+     * @param agentName - The agent name
+     * @returns The concurrency limit (agent-specific or default)
+     */
+    getAgentConcurrency(agentName: string): number;
+    /**
+     * Get the fleet-wide concurrency limit
+     *
+     * @returns The fleet concurrency limit or null if not set
+     */
+    getFleetConcurrency(): number | null;
+    /**
+     * Get the default agent concurrency limit
+     *
+     * @returns The default agent concurrency limit
+     */
+    getDefaultAgentConcurrency(): number;
+    /**
+     * Check if there's capacity to run a job for an agent
+     *
+     * @param agentName - The agent name
+     * @returns Object with canRun boolean and reason if false
+     */
+    checkCapacity(agentName: string): {
+        canRun: boolean;
+        reason?: "agent_at_capacity" | "fleet_at_capacity";
+        currentRunning: number;
+        limit: number;
+    };
+    /**
+     * Enqueue a job or return immediately if capacity is available
+     *
+     * For scheduled triggers (isScheduled: true), jobs are NOT queued.
+     * Instead, a schedule:skipped event is emitted and null is returned.
+     *
+     * @param options - Enqueue options
+     * @returns EnqueueResult if job is queued/ready, or null if scheduled and at capacity
+     */
+    enqueue(options: EnqueueOptions): EnqueueResult | null;
+    /**
+     * Dequeue the next job for an agent
+     *
+     * Returns the next queued job if one exists, otherwise null.
+     * Does NOT check capacity - caller should check capacity first.
+     *
+     * @param agentName - The agent name
+     * @returns The next queued job or null
+     */
+    dequeue(agentName: string): QueuedJob | null;
+    /**
+     * Peek at the next job in the queue without removing it
+     *
+     * @param agentName - The agent name
+     * @returns The next queued job or null
+     */
+    peek(agentName: string): QueuedJob | null;
+    /**
+     * Remove a specific job from the queue
+     *
+     * @param jobId - The job ID to remove
+     * @returns true if the job was found and removed
+     */
+    remove(jobId: string): boolean;
+    /**
+     * Mark a job as running for an agent
+     *
+     * @param agentName - The agent name
+     * @param jobId - The job ID
+     */
+    markRunning(agentName: string, jobId: string): void;
+    /**
+     * Mark a job as completed for an agent
+     *
+     * This frees up capacity and may allow queued jobs to run.
+     *
+     * @param agentName - The agent name
+     * @param jobId - The job ID
+     */
+    markCompleted(agentName: string, jobId: string): void;
+    /**
+     * Get the number of running jobs for an agent
+     *
+     * @param agentName - The agent name
+     * @returns Number of currently running jobs
+     */
+    getRunningCount(agentName: string): number;
+    /**
+     * Get the total number of running jobs across all agents
+     *
+     * @returns Total running job count
+     */
+    getTotalRunningCount(): number;
+    /**
+     * Get the IDs of running jobs for an agent
+     *
+     * @param agentName - The agent name
+     * @returns Set of running job IDs
+     */
+    getRunningJobIds(agentName: string): Set<string>;
+    /**
+     * Get the queue status for a specific agent
+     *
+     * @param agentName - The agent name
+     * @returns Agent queue status
+     */
+    getAgentQueueStatus(agentName: string): AgentQueueStatus;
+    /**
+     * Get the overall queue status
+     *
+     * @returns Overall queue status with per-agent details
+     */
+    getQueueStatus(): QueueStatus;
+    /**
+     * Get the queue depth (number of queued jobs) for an agent
+     *
+     * @param agentName - The agent name
+     * @returns Number of queued jobs
+     */
+    getQueueDepth(agentName: string): number;
+    /**
+     * Get the total queue depth across all agents
+     *
+     * @returns Total number of queued jobs
+     */
+    getTotalQueueDepth(): number;
+    /**
+     * Clear all queued jobs (does not affect running jobs)
+     */
+    clearQueue(): void;
+    /**
+     * Clear queued jobs for a specific agent
+     *
+     * @param agentName - The agent name
+     * @returns Number of jobs cleared
+     */
+    clearAgentQueue(agentName: string): number;
+    /**
+     * Reset all state (running jobs, queued jobs, concurrency limits)
+     */
+    reset(): void;
+    /**
+     * Generate a unique job ID
+     */
+    private generateJobId;
+}
+//# sourceMappingURL=job-queue.d.ts.map

package/dist/fleet-manager/job-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-queue.d.ts","sourceRoot":"","sources":["../../src/fleet-manager/job-queue.ts"],"names":[],"mappings":"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"}