@herdctl/core 0.0.1 → 0.0.2

package/src/scheduler/schedule-runner.ts

@@ -1,442 +0,0 @@
-/**
- * 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 type { ResolvedAgent, Schedule } from "../config/index.js";
-import type { ScheduleState } from "../state/schemas/fleet-state.js";
-import type { RunnerResult, SDKQueryFunction } from "../runner/index.js";
-import type {
-  WorkSourceManager,
-  WorkItem,
-  WorkResult,
-  WorkOutcome,
-} from "../work-sources/index.js";
-import { JobExecutor, type JobExecutorOptions } from "../runner/index.js";
-import {
-  updateScheduleState,
-  type ScheduleStateLogger,
-} from "./schedule-state.js";
-import { calculateNextTrigger } from "./interval.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Logger interface for schedule runner
- */
-export interface ScheduleRunnerLogger {
-  debug: (message: string) => void;
-  info: (message: string) => void;
-  warn: (message: string) => void;
-  error: (message: string) => void;
-}
-
-/**
- * Trigger metadata passed to the JobExecutor
- */
-export interface TriggerMetadata {
-  /** The type of trigger */
-  triggerType: "interval";
-  /** The name of the schedule that triggered */
-  schedule: string;
-  /** Work item ID if this run is processing a work item */
-  workItemId?: string;
-  /** Work item title for reference */
-  workItemTitle?: string;
-}
-
-/**
- * Options for running a schedule
- */
-export interface RunScheduleOptions {
-  /** The agent to run */
-  agent: ResolvedAgent;
-  /** The name of the schedule */
-  scheduleName: string;
-  /** The schedule configuration */
-  schedule: Schedule;
-  /** Current schedule state */
-  scheduleState: ScheduleState;
-  /** Path to the state directory (e.g., .herdctl) */
-  stateDir: string;
-  /** The SDK query function for agent execution */
-  sdkQuery: SDKQueryFunction;
-  /** Optional work source manager for fetching work items */
-  workSourceManager?: WorkSourceManager;
-  /** Optional logger */
-  logger?: ScheduleRunnerLogger;
-  /** Optional job executor options */
-  executorOptions?: JobExecutorOptions;
-}
-
-/**
- * Result of running a schedule, extending RunnerResult with schedule-specific info
- */
-export interface ScheduleRunResult extends RunnerResult {
-  /** The work item that was processed (if any) */
-  workItem?: WorkItem;
-  /** Whether a work item was fetched and processed */
-  processedWorkItem: boolean;
-}
-
-// =============================================================================
-// Default Logger
-// =============================================================================
-
-const defaultLogger: ScheduleRunnerLogger = {
-  debug: (message: string) => console.debug(`[schedule-runner] ${message}`),
-  info: (message: string) => console.info(`[schedule-runner] ${message}`),
-  warn: (message: string) => console.warn(`[schedule-runner] ${message}`),
-  error: (message: string) => 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: Schedule,
-  workItem?: WorkItem
-): string {
-  const parts: string[] = [];
-
-  // 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: WorkItem): string {
-  const lines: string[] = [];
-
-  lines.push(`## Work Item: ${workItem.title}`);
-  lines.push("");
-
-  if (workItem.description) {
-    lines.push(workItem.description);
-    lines.push("");
-  }
-
-  // Add metadata
-  const metadata: string[] = [];
-  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: RunScheduleOptions
-): Promise<ScheduleRunResult> {
-  const {
-    agent,
-    scheduleName,
-    schedule,
-    stateDir,
-    sdkQuery,
-    workSourceManager,
-    logger = defaultLogger,
-    executorOptions,
-  } = options;
-
-  const stateLogger: ScheduleStateLogger = { 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: WorkItem | undefined;
-  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: 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 as Error).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 as Error).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: RunnerResult): WorkResult {
-  const outcome: WorkOutcome = 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,
-  };
-}

package/src/scheduler/schedule-state.ts

@@ -1,211 +0,0 @@
-/**
- * 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 {
-  type ScheduleState,
-  type FleetState,
-  createDefaultScheduleState,
-} from "../state/schemas/fleet-state.js";
-import { readFleetState, writeFleetState } from "../state/fleet-state.js";
-import { STATE_FILE_NAME } from "../state/types.js";
-
-/**
- * Logger interface for warning messages
- */
-export interface ScheduleStateLogger {
-  warn: (message: string) => void;
-}
-
-/**
- * Default console logger
- */
-const defaultLogger: ScheduleStateLogger = {
-  warn: (message: string) => console.warn(`[herdctl] ${message}`),
-};
-
-/**
- * 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 state file path from a state directory
- */
-function getStateFilePath(stateDir: string): string {
-  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: string,
-  agentName: string,
-  scheduleName: string,
-  options: ScheduleStateOptions = {}
-): Promise<ScheduleState> {
-  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: string,
-  agentName: string,
-  scheduleName: string,
-  updates: ScheduleStateUpdates,
-  options: ScheduleStateOptions = {}
-): Promise<ScheduleState> {
-  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: ScheduleState = {
-    ...currentScheduleState,
-    ...updates,
-  };
-
-  // Update the fleet state
-  const updatedFleetState: FleetState = {
-    ...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: string,
-  agentName: string,
-  options: ScheduleStateOptions = {}
-): Promise<Record<string, ScheduleState>> {
-  const stateFilePath = getStateFilePath(stateDir);
-  const fleetState = await readFleetState(stateFilePath, options);
-
-  const agentState = fleetState.agents[agentName];
-  if (!agentState || !agentState.schedules) {
-    return {};
-  }
-
-  return agentState.schedules;
-}