@herdctl/core 0.0.1

package/dist/scheduler/schedule-runner.js

@@ -0,0 +1,277 @@
+/**
+ * Schedule Runner for executing triggered schedules
+ *
+ * Handles the actual execution of scheduled work by:
+ * 1. Fetching work items from work sources (if configured)
+ * 2. Building prompts from schedule config and work items
+ * 3. Invoking the JobExecutor to run the agent
+ * 4. Updating schedule state and reporting outcomes
+ */
+import { JobExecutor } from "../runner/index.js";
+import { updateScheduleState, } from "./schedule-state.js";
+import { calculateNextTrigger } from "./interval.js";
+// =============================================================================
+// Default Logger
+// =============================================================================
+const defaultLogger = {
+    debug: (message) => console.debug(`[schedule-runner] ${message}`),
+    info: (message) => console.info(`[schedule-runner] ${message}`),
+    warn: (message) => console.warn(`[schedule-runner] ${message}`),
+    error: (message) => console.error(`[schedule-runner] ${message}`),
+};
+// =============================================================================
+// Build Schedule Prompt
+// =============================================================================
+/**
+ * Build the prompt for a scheduled run
+ *
+ * Constructs the prompt by combining:
+ * 1. The schedule's configured prompt (if any)
+ * 2. Work item details (if a work item was fetched)
+ *
+ * @param schedule - The schedule configuration
+ * @param workItem - Optional work item fetched from work source
+ * @returns The constructed prompt string
+ *
+ * @example Without work item
+ * ```typescript
+ * const prompt = buildSchedulePrompt(
+ *   { type: 'interval', interval: '1h', prompt: 'Check for updates' }
+ * );
+ * // => "Check for updates"
+ * ```
+ *
+ * @example With work item
+ * ```typescript
+ * const prompt = buildSchedulePrompt(
+ *   { type: 'interval', interval: '1h', prompt: 'Process this issue:' },
+ *   { title: 'Fix bug', description: 'There is a bug in auth.ts', ... }
+ * );
+ * // => "Process this issue:\n\n## Work Item: Fix bug\n\nThere is a bug in auth.ts\n\n..."
+ * ```
+ */
+export function buildSchedulePrompt(schedule, workItem) {
+    const parts = [];
+    // Add schedule prompt if configured
+    if (schedule.prompt) {
+        parts.push(schedule.prompt);
+    }
+    // Add work item details if provided
+    if (workItem) {
+        const workItemSection = formatWorkItem(workItem);
+        parts.push(workItemSection);
+    }
+    // If no prompt and no work item, provide a default
+    if (parts.length === 0) {
+        return "Execute scheduled task.";
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Format a work item for inclusion in a prompt
+ */
+function formatWorkItem(workItem) {
+    const lines = [];
+    lines.push(`## Work Item: ${workItem.title}`);
+    lines.push("");
+    if (workItem.description) {
+        lines.push(workItem.description);
+        lines.push("");
+    }
+    // Add metadata
+    const metadata = [];
+    metadata.push(`- **Source:** ${workItem.source}`);
+    metadata.push(`- **ID:** ${workItem.externalId}`);
+    metadata.push(`- **Priority:** ${workItem.priority}`);
+    if (workItem.labels.length > 0) {
+        metadata.push(`- **Labels:** ${workItem.labels.join(", ")}`);
+    }
+    if (workItem.url) {
+        metadata.push(`- **URL:** ${workItem.url}`);
+    }
+    lines.push(metadata.join("\n"));
+    return lines.join("\n");
+}
+// =============================================================================
+// Run Schedule
+// =============================================================================
+/**
+ * Execute a triggered schedule
+ *
+ * This function handles the complete lifecycle of a scheduled execution:
+ * 1. Updates schedule state to 'running'
+ * 2. Fetches work item from work source (if configured)
+ * 3. Builds the prompt from schedule config and work item
+ * 4. Invokes the JobExecutor to run the agent
+ * 5. Reports outcome to work source (if applicable)
+ * 6. Updates schedule state with last_run_at and next_run_at
+ *
+ * @param options - Options for running the schedule
+ * @returns Result of the schedule execution
+ *
+ * @example Basic usage
+ * ```typescript
+ * const result = await runSchedule({
+ *   agent: resolvedAgent,
+ *   scheduleName: 'hourly',
+ *   schedule: { type: 'interval', interval: '1h', prompt: 'Check status' },
+ *   scheduleState: { status: 'idle', last_run_at: null },
+ *   stateDir: '.herdctl',
+ *   sdkQuery: query,
+ * });
+ *
+ * console.log(`Job ${result.jobId} completed: ${result.success}`);
+ * ```
+ *
+ * @example With work source
+ * ```typescript
+ * const result = await runSchedule({
+ *   agent: resolvedAgent,
+ *   scheduleName: 'issue-processor',
+ *   schedule: {
+ *     type: 'interval',
+ *     interval: '5m',
+ *     prompt: 'Process this GitHub issue:',
+ *     work_source: { type: 'github', owner: 'org', repo: 'repo' }
+ *   },
+ *   scheduleState: { status: 'idle', last_run_at: null },
+ *   stateDir: '.herdctl',
+ *   sdkQuery: query,
+ *   workSourceManager: manager,
+ * });
+ *
+ * if (result.workItem) {
+ *   console.log(`Processed work item: ${result.workItem.title}`);
+ * }
+ * ```
+ */
+export async function runSchedule(options) {
+    const { agent, scheduleName, schedule, stateDir, sdkQuery, workSourceManager, logger = defaultLogger, executorOptions, } = options;
+    const stateLogger = { warn: logger.warn };
+    logger.info(`Running schedule ${agent.name}/${scheduleName}`);
+    // Step 1: Update schedule state to 'running'
+    await updateScheduleState(stateDir, agent.name, scheduleName, {
+        status: "running",
+        last_run_at: new Date().toISOString(),
+    }, { logger: stateLogger });
+    let workItem;
+    let processedWorkItem = false;
+    try {
+        // Step 2: Fetch work item if schedule has work_source configured
+        if (schedule.work_source && workSourceManager) {
+            logger.debug(`Fetching work item for ${agent.name}/${scheduleName} from ${schedule.work_source.type}`);
+            const workResult = await workSourceManager.getNextWorkItem(agent, {
+                autoClaim: true,
+            });
+            if (workResult.item && workResult.claimed) {
+                workItem = workResult.item;
+                processedWorkItem = true;
+                logger.info(`Claimed work item ${workItem.id}: ${workItem.title}`);
+            }
+            else if (workResult.item && !workResult.claimed) {
+                // Work item found but claim failed (race condition)
+                logger.warn(`Work item ${workResult.item.id} found but claim failed: ${workResult.claimResult?.reason}`);
+            }
+            else {
+                // No work available
+                logger.debug(`No work items available for ${agent.name}/${scheduleName}`);
+            }
+        }
+        // Step 3: Build the prompt
+        const prompt = buildSchedulePrompt(schedule, workItem);
+        // Step 4: Build trigger metadata
+        const triggerMetadata = {
+            triggerType: "interval",
+            schedule: scheduleName,
+        };
+        if (workItem) {
+            triggerMetadata.workItemId = workItem.id;
+            triggerMetadata.workItemTitle = workItem.title;
+        }
+        // Step 5: Execute the agent via JobExecutor
+        const executor = new JobExecutor(sdkQuery, executorOptions);
+        const runnerResult = await executor.execute({
+            agent,
+            prompt,
+            stateDir,
+            triggerType: "schedule",
+            schedule: scheduleName,
+        });
+        // Step 6: Report outcome to work source if we processed a work item
+        if (workItem && workSourceManager) {
+            const workResult = buildWorkResult(runnerResult);
+            try {
+                await workSourceManager.reportOutcome(workItem.id, workResult, {
+                    agent,
+                });
+                logger.info(`Reported outcome for work item ${workItem.id}: ${workResult.outcome}`);
+            }
+            catch (reportError) {
+                logger.error(`Failed to report outcome for work item ${workItem.id}: ${reportError.message}`);
+                // Don't fail the overall run if reporting fails
+            }
+        }
+        // Step 7: Calculate next trigger time
+        const nextTrigger = schedule.interval
+            ? calculateNextTrigger(new Date(), schedule.interval)
+            : null;
+        // Step 8: Update schedule state with success
+        await updateScheduleState(stateDir, agent.name, scheduleName, {
+            status: "idle",
+            next_run_at: nextTrigger?.toISOString() ?? null,
+            last_error: runnerResult.success ? null : runnerResult.error?.message,
+        }, { logger: stateLogger });
+        logger.info(`Completed schedule ${agent.name}/${scheduleName}: ${runnerResult.success ? "success" : "failed"}`);
+        return {
+            ...runnerResult,
+            workItem,
+            processedWorkItem,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Error running schedule ${agent.name}/${scheduleName}: ${errorMessage}`);
+        // Release work item if we claimed one and execution failed unexpectedly
+        if (workItem && workSourceManager) {
+            try {
+                await workSourceManager.releaseWorkItem(workItem.id, {
+                    agent,
+                    reason: `Unexpected error: ${errorMessage}`,
+                    addComment: true,
+                });
+                logger.info(`Released work item ${workItem.id} due to error`);
+            }
+            catch (releaseError) {
+                logger.error(`Failed to release work item ${workItem.id}: ${releaseError.message}`);
+            }
+        }
+        // Calculate next trigger time even on error
+        const nextTrigger = schedule.interval
+            ? calculateNextTrigger(new Date(), schedule.interval)
+            : null;
+        // Update schedule state with error
+        await updateScheduleState(stateDir, agent.name, scheduleName, {
+            status: "idle",
+            next_run_at: nextTrigger?.toISOString() ?? null,
+            last_error: errorMessage,
+        }, { logger: stateLogger });
+        // Re-throw to let caller handle
+        throw error;
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Build a WorkResult from a RunnerResult for reporting to work sources
+ */
+function buildWorkResult(runnerResult) {
+    const outcome = runnerResult.success ? "success" : "failure";
+    return {
+        outcome,
+        summary: runnerResult.summary ?? (runnerResult.success ? "Task completed successfully" : "Task failed"),
+        error: runnerResult.error?.message,
+        artifacts: runnerResult.jobId ? [`job:${runnerResult.jobId}`] : undefined,
+    };
+}
+//# sourceMappingURL=schedule-runner.js.map

package/dist/scheduler/schedule-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-runner.js","sourceRoot":"","sources":["../../src/scheduler/schedule-runner.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/schedule-state.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Schedule state management
+ *
+ * Provides functions for reading and updating schedule state within fleet state.
+ * Schedule state is stored per-agent in the `schedules` map within AgentState.
+ */
+import { type ScheduleState } from "../state/schemas/fleet-state.js";
+/**
+ * Logger interface for warning messages
+ */
+export interface ScheduleStateLogger {
+    warn: (message: string) => void;
+}
+/**
+ * Options for schedule state operations
+ */
+export interface ScheduleStateOptions {
+    /**
+     * Logger for warning messages
+     * Default: console.warn
+     */
+    logger?: ScheduleStateLogger;
+}
+/**
+ * Partial updates for schedule state
+ */
+export type ScheduleStateUpdates = Partial<ScheduleState>;
+/**
+ * Get the schedule state for a specific agent and schedule
+ *
+ * Returns default state if the agent or schedule doesn't exist.
+ *
+ * @param stateDir - Path to the state directory (e.g., .herdctl)
+ * @param agentName - Name of the agent
+ * @param scheduleName - Name of the schedule
+ * @param options - Options including logger
+ * @returns The schedule state, or default state if not found
+ *
+ * @example
+ * ```typescript
+ * const state = await getScheduleState('.herdctl', 'my-agent', 'hourly');
+ * console.log(state.last_run_at);
+ * console.log(state.next_run_at);
+ * console.log(state.status);
+ * ```
+ */
+export declare function getScheduleState(stateDir: string, agentName: string, scheduleName: string, options?: ScheduleStateOptions): Promise<ScheduleState>;
+/**
+ * Update the schedule state for a specific agent and schedule
+ *
+ * This function:
+ * 1. Reads current fleet state
+ * 2. Applies partial updates to the specified schedule
+ * 3. Writes the updated state back atomically
+ *
+ * If the agent or schedule doesn't exist, it will be created.
+ *
+ * @param stateDir - Path to the state directory (e.g., .herdctl)
+ * @param agentName - Name of the agent
+ * @param scheduleName - Name of the schedule
+ * @param updates - Partial ScheduleState updates to apply
+ * @param options - Options including logger
+ * @returns The updated ScheduleState
+ *
+ * @example
+ * ```typescript
+ * // Mark schedule as running
+ * await updateScheduleState('.herdctl', 'my-agent', 'hourly', {
+ *   status: 'running',
+ *   last_run_at: new Date().toISOString(),
+ * });
+ *
+ * // Record error
+ * await updateScheduleState('.herdctl', 'my-agent', 'hourly', {
+ *   status: 'idle',
+ *   last_error: 'Container exited with code 1',
+ * });
+ *
+ * // Clear error
+ * await updateScheduleState('.herdctl', 'my-agent', 'hourly', {
+ *   last_error: null,
+ * });
+ * ```
+ */
+export declare function updateScheduleState(stateDir: string, agentName: string, scheduleName: string, updates: ScheduleStateUpdates, options?: ScheduleStateOptions): Promise<ScheduleState>;
+/**
+ * Get all schedule states for a specific agent
+ *
+ * Returns an empty object if the agent doesn't exist or has no schedules.
+ *
+ * @param stateDir - Path to the state directory (e.g., .herdctl)
+ * @param agentName - Name of the agent
+ * @param options - Options including logger
+ * @returns Map of schedule names to their state
+ *
+ * @example
+ * ```typescript
+ * const schedules = await getAgentScheduleStates('.herdctl', 'my-agent');
+ * for (const [name, state] of Object.entries(schedules)) {
+ *   console.log(`${name}: ${state.status}, last run: ${state.last_run_at}`);
+ * }
+ * ```
+ */
+export declare function getAgentScheduleStates(stateDir: string, agentName: string, options?: ScheduleStateOptions): Promise<Record<string, ScheduleState>>;
+//# sourceMappingURL=schedule-state.d.ts.map

package/dist/scheduler/schedule-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-state.d.ts","sourceRoot":"","sources":["../../src/scheduler/schedule-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,iCAAiC,CAAC;AAIzC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AASD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAS1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAexB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAuCxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAUxC"}

package/dist/scheduler/schedule-state.js

@@ -0,0 +1,151 @@
+/**
+ * Schedule state management
+ *
+ * Provides functions for reading and updating schedule state within fleet state.
+ * Schedule state is stored per-agent in the `schedules` map within AgentState.
+ */
+import { join } from "node:path";
+import { createDefaultScheduleState, } from "../state/schemas/fleet-state.js";
+import { readFleetState, writeFleetState } from "../state/fleet-state.js";
+import { STATE_FILE_NAME } from "../state/types.js";
+/**
+ * Default console logger
+ */
+const defaultLogger = {
+    warn: (message) => console.warn(`[herdctl] ${message}`),
+};
+/**
+ * Get the state file path from a state directory
+ */
+function getStateFilePath(stateDir) {
+    return join(stateDir, STATE_FILE_NAME);
+}
+/**
+ * Get the schedule state for a specific agent and schedule
+ *
+ * Returns default state if the agent or schedule doesn't exist.
+ *
+ * @param stateDir - Path to the state directory (e.g., .herdctl)
+ * @param agentName - Name of the agent
+ * @param scheduleName - Name of the schedule
+ * @param options - Options including logger
+ * @returns The schedule state, or default state if not found
+ *
+ * @example
+ * ```typescript
+ * const state = await getScheduleState('.herdctl', 'my-agent', 'hourly');
+ * console.log(state.last_run_at);
+ * console.log(state.next_run_at);
+ * console.log(state.status);
+ * ```
+ */
+export async function getScheduleState(stateDir, agentName, scheduleName, options = {}) {
+    const stateFilePath = getStateFilePath(stateDir);
+    const fleetState = await readFleetState(stateFilePath, options);
+    const agentState = fleetState.agents[agentName];
+    if (!agentState || !agentState.schedules) {
+        return createDefaultScheduleState();
+    }
+    const scheduleState = agentState.schedules[scheduleName];
+    if (!scheduleState) {
+        return createDefaultScheduleState();
+    }
+    return scheduleState;
+}
+/**
+ * Update the schedule state for a specific agent and schedule
+ *
+ * This function:
+ * 1. Reads current fleet state
+ * 2. Applies partial updates to the specified schedule
+ * 3. Writes the updated state back atomically
+ *
+ * If the agent or schedule doesn't exist, it will be created.
+ *
+ * @param stateDir - Path to the state directory (e.g., .herdctl)
+ * @param agentName - Name of the agent
+ * @param scheduleName - Name of the schedule
+ * @param updates - Partial ScheduleState updates to apply
+ * @param options - Options including logger
+ * @returns The updated ScheduleState
+ *
+ * @example
+ * ```typescript
+ * // Mark schedule as running
+ * await updateScheduleState('.herdctl', 'my-agent', 'hourly', {
+ *   status: 'running',
+ *   last_run_at: new Date().toISOString(),
+ * });
+ *
+ * // Record error
+ * await updateScheduleState('.herdctl', 'my-agent', 'hourly', {
+ *   status: 'idle',
+ *   last_error: 'Container exited with code 1',
+ * });
+ *
+ * // Clear error
+ * await updateScheduleState('.herdctl', 'my-agent', 'hourly', {
+ *   last_error: null,
+ * });
+ * ```
+ */
+export async function updateScheduleState(stateDir, agentName, scheduleName, updates, options = {}) {
+    const stateFilePath = getStateFilePath(stateDir);
+    const fleetState = await readFleetState(stateFilePath, options);
+    // Get or create agent state
+    const currentAgentState = fleetState.agents[agentName] ?? { status: "idle" };
+    // Get current schedules map or create empty one
+    const currentSchedules = currentAgentState.schedules ?? {};
+    // Get current schedule state or create default
+    const currentScheduleState = currentSchedules[scheduleName] ?? createDefaultScheduleState();
+    // Merge updates
+    const updatedScheduleState = {
+        ...currentScheduleState,
+        ...updates,
+    };
+    // Update the fleet state
+    const updatedFleetState = {
+        ...fleetState,
+        agents: {
+            ...fleetState.agents,
+            [agentName]: {
+                ...currentAgentState,
+                schedules: {
+                    ...currentSchedules,
+                    [scheduleName]: updatedScheduleState,
+                },
+            },
+        },
+    };
+    // Write back
+    await writeFleetState(stateFilePath, updatedFleetState);
+    return updatedScheduleState;
+}
+/**
+ * Get all schedule states for a specific agent
+ *
+ * Returns an empty object if the agent doesn't exist or has no schedules.
+ *
+ * @param stateDir - Path to the state directory (e.g., .herdctl)
+ * @param agentName - Name of the agent
+ * @param options - Options including logger
+ * @returns Map of schedule names to their state
+ *
+ * @example
+ * ```typescript
+ * const schedules = await getAgentScheduleStates('.herdctl', 'my-agent');
+ * for (const [name, state] of Object.entries(schedules)) {
+ *   console.log(`${name}: ${state.status}, last run: ${state.last_run_at}`);
+ * }
+ * ```
+ */
+export async function getAgentScheduleStates(stateDir, agentName, options = {}) {
+    const stateFilePath = getStateFilePath(stateDir);
+    const fleetState = await readFleetState(stateFilePath, options);
+    const agentState = fleetState.agents[agentName];
+    if (!agentState || !agentState.schedules) {
+        return {};
+    }
+    return agentState.schedules;
+}
+//# sourceMappingURL=schedule-state.js.map

package/dist/scheduler/schedule-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-state.js","sourceRoot":"","sources":["../../src/scheduler/schedule-state.ts"],"names":[],"mappings":"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"}