@herdctl/core 0.0.1 → 0.0.2

package/src/work-sources/adapters/index.ts

@@ -1,64 +0,0 @@
-/**
- * Built-in Work Source Adapters
- *
- * This module exports built-in adapters and registers them with the
- * work source registry at module load time.
- */
-
-import { registerWorkSource, isWorkSourceRegistered } from "../registry.js";
-import {
-  createGitHubAdapter,
-  GitHubWorkSourceAdapter,
-  GitHubAPIError,
-  GitHubAuthError,
-  extractRateLimitInfo,
-  isRateLimitResponse,
-  calculateBackoffDelay,
-  type GitHubWorkSourceConfig,
-  type GitHubIssue,
-  type RateLimitInfo,
-  type RateLimitWarningOptions,
-  type RetryOptions,
-} from "./github.js";
-
-// =============================================================================
-// Re-export Adapters
-// =============================================================================
-
-export {
-  GitHubWorkSourceAdapter,
-  createGitHubAdapter,
-  GitHubAPIError,
-  GitHubAuthError,
-  extractRateLimitInfo,
-  isRateLimitResponse,
-  calculateBackoffDelay,
-};
-export type {
-  GitHubWorkSourceConfig,
-  GitHubIssue,
-  RateLimitInfo,
-  RateLimitWarningOptions,
-  RetryOptions,
-};
-
-// =============================================================================
-// Auto-registration of Built-in Adapters
-// =============================================================================
-
-/**
- * Register built-in adapters
- *
- * This function is called automatically when the module is imported.
- * It only registers adapters that haven't already been registered,
- * allowing tests to pre-register mocks before importing this module.
- */
-function registerBuiltInAdapters(): void {
-  // Register GitHub adapter if not already registered
-  if (!isWorkSourceRegistered("github")) {
-    registerWorkSource("github", createGitHubAdapter);
-  }
-}
-
-// Auto-register on module load
-registerBuiltInAdapters();

package/src/work-sources/errors.ts

@@ -1,71 +0,0 @@
-/**
- * Error classes for work-sources module
- *
- * Provides typed errors with descriptive messages for work source operations.
- */
-
-// =============================================================================
-// Base Error Class
-// =============================================================================
-
-/**
- * Base error class for all work source errors
- */
-export class WorkSourceError extends Error {
-  constructor(message: string, options?: { cause?: Error }) {
-    super(message);
-    this.name = "WorkSourceError";
-    this.cause = options?.cause;
-  }
-}
-
-// =============================================================================
-// Registry Errors
-// =============================================================================
-
-/**
- * Error thrown when attempting to get a work source adapter for an unregistered type
- *
- * This error indicates that no factory has been registered for the requested
- * work source type. Use `registerWorkSource()` to register a factory before
- * attempting to get an adapter.
- */
-export class UnknownWorkSourceError extends WorkSourceError {
-  /** The work source type that was requested */
-  public readonly sourceType: string;
-  /** List of currently registered work source types */
-  public readonly availableTypes: string[];
-
-  constructor(
-    sourceType: string,
-    availableTypes: string[],
-    options?: { cause?: Error }
-  ) {
-    const availableList =
-      availableTypes.length > 0 ? availableTypes.join(", ") : "none";
-    super(
-      `Unknown work source type: "${sourceType}". Available types: ${availableList}`,
-      options
-    );
-    this.name = "UnknownWorkSourceError";
-    this.sourceType = sourceType;
-    this.availableTypes = availableTypes;
-  }
-}
-
-/**
- * Error thrown when attempting to register a work source type that is already registered
- */
-export class DuplicateWorkSourceError extends WorkSourceError {
-  /** The work source type that was already registered */
-  public readonly sourceType: string;
-
-  constructor(sourceType: string, options?: { cause?: Error }) {
-    super(
-      `Work source type "${sourceType}" is already registered. Use a different type name or unregister the existing one first.`,
-      options
-    );
-    this.name = "DuplicateWorkSourceError";
-    this.sourceType = sourceType;
-  }
-}

package/src/work-sources/index.ts

@@ -1,148 +0,0 @@
-/**
- * Work Sources Module
- *
- * Provides a common interface for fetching and managing work items
- * from various sources (GitHub Issues, Linear, etc.).
- *
- * All work source adapters implement the WorkSource interface to ensure
- * consistent behavior across different backends.
- *
- * The registry allows dynamic registration of adapter factories,
- * enabling extensibility without modifying core code.
- *
- * The WorkSourceManager interface defines the contract between work sources
- * and the scheduler/runner, allowing clean integration without coupling.
- */
-
-// Re-export all types
-export * from "./types.js";
-
-// Re-export errors
-export * from "./errors.js";
-
-// Re-export manager interface and types
-export type {
-  WorkSourceManager,
-  WorkSourceManagerFactory,
-  GetNextWorkItemOptions,
-  GetNextWorkItemResult,
-  ReleaseWorkItemOptions,
-  ReportOutcomeOptions,
-} from "./manager.js";
-
-// Re-export registry functions and types
-export {
-  registerWorkSource,
-  getWorkSource,
-  getRegisteredTypes,
-  isWorkSourceRegistered,
-  unregisterWorkSource,
-  clearWorkSourceRegistry,
-} from "./registry.js";
-export type { WorkSourceConfig, WorkSourceFactory } from "./registry.js";
-
-// Re-export built-in adapters (also triggers auto-registration)
-export * from "./adapters/index.js";
-
-// Import types for interface definition
-import type {
-  WorkItem,
-  FetchOptions,
-  FetchResult,
-  ClaimResult,
-  WorkResult,
-  ReleaseOptions,
-  ReleaseResult,
-} from "./types.js";
-
-// =============================================================================
-// WorkSourceAdapter Interface
-// =============================================================================
-
-/**
- * Common interface for all work source adapters
- *
- * Work sources provide work items from external systems (GitHub, Linear, etc.)
- * and handle the lifecycle of claiming, completing, and releasing work.
- *
- * @example
- * ```typescript
- * const github = new GitHubWorkSourceAdapter({ owner: 'org', repo: 'repo' });
- *
- * // Fetch available work
- * const { items } = await github.fetchAvailableWork({ labels: ['agent-ready'] });
- *
- * // Claim a work item
- * const claim = await github.claimWork(items[0].id);
- * if (claim.success) {
- *   // Do work...
- *   await github.completeWork(items[0].id, { outcome: 'success', summary: 'Fixed the bug' });
- * }
- * ```
- */
-export interface WorkSourceAdapter {
-  /**
-   * The type identifier for this work source (e.g., 'github', 'linear')
-   *
-   * Used to prefix work item IDs and identify the source in logs/state.
-   */
-  readonly type: string;
-
-  /**
-   * Fetch available work items from the source
-   *
-   * Returns work items that match the specified filters and are available
-   * to be claimed (not already in progress by another agent).
-   *
-   * @param options - Filtering and pagination options
-   * @returns Promise resolving to fetched items with pagination info
-   */
-  fetchAvailableWork(options?: FetchOptions): Promise<FetchResult>;
-
-  /**
-   * Claim a work item for processing
-   *
-   * Marks the work item as in-progress in the external system to prevent
-   * other agents from picking it up. The exact mechanism depends on the
-   * source (e.g., adding a label, assigning to a bot user).
-   *
-   * @param workItemId - The ID of the work item to claim
-   * @returns Promise resolving to the claim result
-   */
-  claimWork(workItemId: string): Promise<ClaimResult>;
-
-  /**
-   * Complete a work item with the given result
-   *
-   * Updates the external system to reflect completion (e.g., closing an issue,
-   * adding a comment with the summary). The work item is released from claim.
-   *
-   * @param workItemId - The ID of the work item to complete
-   * @param result - The outcome and details of the work
-   * @returns Promise resolving when the completion is recorded
-   */
-  completeWork(workItemId: string, result: WorkResult): Promise<void>;
-
-  /**
-   * Release a claimed work item without completing it
-   *
-   * Returns the work item to available status so other agents can claim it.
-   * Use this when an agent cannot complete the work (e.g., timeout, error).
-   *
-   * @param workItemId - The ID of the work item to release
-   * @param options - Options for the release (reason, add comment, etc.)
-   * @returns Promise resolving to the release result
-   */
-  releaseWork(workItemId: string, options?: ReleaseOptions): Promise<ReleaseResult>;
-
-  /**
-   * Get a specific work item by ID
-   *
-   * Fetches the current state of a work item from the source.
-   * Returns undefined if the work item doesn't exist.
-   *
-   * @param workItemId - The ID of the work item to fetch
-   * @returns Promise resolving to the work item or undefined
-   */
-  getWork(workItemId: string): Promise<WorkItem | undefined>;
-}

package/src/work-sources/manager.ts

@@ -1,413 +0,0 @@
-/**
- * Work Source Manager Interface
- *
- * Defines the contract between work sources and the scheduler/runner.
- * The scheduler uses this interface to fetch work, report outcomes,
- * and manage work source instances per agent.
- *
- * This module defines ONLY the interface - no scheduler logic is implemented here.
- * The scheduler implementation will import and use this interface.
- *
- * @example Scheduler Usage Pattern
- * ```typescript
- * // The scheduler will use the manager like this:
- * const manager: WorkSourceManager = getWorkSourceManager();
- *
- * // 1. Get next available work for an agent
- * const workItem = await manager.getNextWorkItem(agent);
- * if (!workItem) {
- *   // No work available, scheduler may check other agents or wait
- *   return;
- * }
- *
- * // 2. Work item is already claimed by getNextWorkItem()
- * // Build prompt from work item and execute job
- * const prompt = buildPromptFromWorkItem(workItem);
- * const result = await executeJob({ agent, prompt, ... });
- *
- * // 3. Report outcome to update external system
- * await manager.reportOutcome(workItem.id, {
- *   outcome: result.success ? 'success' : 'failure',
- *   summary: result.summary ?? 'Job completed',
- *   error: result.error?.message,
- * });
- * ```
- *
- * @example Error Handling Pattern
- * ```typescript
- * try {
- *   const workItem = await manager.getNextWorkItem(agent);
- *   // ... execute work ...
- *   await manager.reportOutcome(workItem.id, { outcome: 'success', summary: '...' });
- * } catch (error) {
- *   // On unexpected error, release the work item back to available pool
- *   if (workItem) {
- *     await manager.releaseWorkItem(workItem.id, `Unexpected error: ${error.message}`);
- *   }
- * }
- * ```
- *
- * @example Multiple Agents Pattern
- * ```typescript
- * // Manager caches adapters per agent to avoid repeated instantiation
- * for (const agent of agents) {
- *   // Each call uses cached adapter for the agent's work source
- *   const workItem = await manager.getNextWorkItem(agent);
- *   // ...
- * }
- * ```
- */
-
-import type { ResolvedAgent } from "../config/loader.js";
-import type {
-  WorkItem,
-  WorkResult,
-  ClaimResult,
-  ReleaseResult,
-  ReleaseOptions,
-  FetchOptions,
-} from "./types.js";
-import type { WorkSourceAdapter } from "./index.js";
-
-// =============================================================================
-// Manager Types
-// =============================================================================
-
-/**
- * Options for fetching the next work item
- *
- * Allows the scheduler to customize work item selection beyond
- * what's configured in the agent's work source.
- */
-export interface GetNextWorkItemOptions {
-  /**
-   * Additional labels to filter by (combined with agent's configured labels)
-   */
-  labels?: string[];
-
-  /**
-   * Whether to automatically claim the work item
-   * Defaults to true - the scheduler typically wants to claim immediately
-   */
-  autoClaim?: boolean;
-
-  /**
-   * Custom fetch options to pass to the adapter
-   * These override the default options for this specific fetch
-   */
-  fetchOptions?: Partial<FetchOptions>;
-}
-
-/**
- * Result of getting the next work item
- *
- * Includes both the work item (if found) and claim status (if autoClaim was true).
- * This allows the scheduler to handle various scenarios:
- * - No work available (item is null)
- * - Work found and claimed successfully
- * - Work found but claim failed (race condition with another agent)
- */
-export interface GetNextWorkItemResult {
-  /**
-   * The work item, or null if no work is available
-   */
-  item: WorkItem | null;
-
-  /**
-   * Whether the work item was claimed
-   * Only relevant when autoClaim is true and item is not null
-   */
-  claimed: boolean;
-
-  /**
-   * Claim result details if claiming was attempted
-   * Contains failure reason if claimed is false
-   */
-  claimResult?: ClaimResult;
-}
-
-/**
- * Options for releasing a work item
- */
-export interface ReleaseWorkItemOptions extends ReleaseOptions {
-  /**
-   * The agent that claimed the work item
-   * Used to resolve the correct adapter for the release operation
-   */
-  agent: ResolvedAgent;
-}
-
-/**
- * Options for reporting work outcome
- */
-export interface ReportOutcomeOptions {
-  /**
-   * The agent that processed the work item
-   * Used to resolve the correct adapter for the completion operation
-   */
-  agent: ResolvedAgent;
-}
-
-// =============================================================================
-// WorkSourceManager Interface
-// =============================================================================
-
-/**
- * Interface for managing work sources and coordinating with the scheduler
- *
- * The WorkSourceManager provides a high-level interface for the scheduler to:
- * 1. Fetch available work items for agents
- * 2. Claim work items to prevent race conditions
- * 3. Report outcomes after job completion
- * 4. Release work items on error/timeout
- *
- * The manager handles:
- * - Work source adapter instantiation and caching per agent
- * - Resolving work source configuration from agent configs
- * - Coordinating claim/release lifecycle
- *
- * Implementation Notes for Scheduler Authors:
- * - Call getNextWorkItem() with autoClaim=true (default) for atomic fetch+claim
- * - Always call reportOutcome() or releaseWorkItem() after processing
- * - The manager caches adapters, so repeated calls are efficient
- * - If an agent has no work_source configured, getNextWorkItem returns { item: null }
- *
- * @example Basic Scheduler Loop
- * ```typescript
- * async function processAgent(manager: WorkSourceManager, agent: ResolvedAgent) {
- *   // Check if we can run more instances
- *   if (activeJobs[agent.name] >= (agent.instances?.max_concurrent ?? 1)) {
- *     return; // Already at capacity
- *   }
- *
- *   // Try to get work
- *   const { item, claimed, claimResult } = await manager.getNextWorkItem(agent);
- *
- *   if (!item) {
- *     return; // No work available
- *   }
- *
- *   if (!claimed) {
- *     // Someone else claimed it first (race condition)
- *     console.log(`Work ${item.id} claimed by another agent: ${claimResult?.reason}`);
- *     return;
- *   }
- *
- *   // Execute the job
- *   try {
- *     const result = await executeJob(agent, item);
- *     await manager.reportOutcome(item.id, result, { agent });
- *   } catch (error) {
- *     await manager.releaseWorkItem(item.id, {
- *       agent,
- *       reason: error.message,
- *       addComment: true,
- *     });
- *   }
- * }
- * ```
- */
-export interface WorkSourceManager {
-  /**
-   * Get the next available work item for an agent
-   *
-   * Fetches the highest priority available work item from the agent's
-   * configured work source. By default, also claims the item atomically
-   * to prevent race conditions with other agents.
-   *
-   * @param agent - The resolved agent configuration
-   * @param options - Options for fetching and claiming
-   * @returns Result containing the work item (if any) and claim status
-   *
-   * @remarks
-   * - Returns { item: null, claimed: false } if agent has no work_source
-   * - Returns { item: null, claimed: false } if no work is available
-   * - With autoClaim=true, claimed=false means another agent claimed it first
-   * - The scheduler should handle claim failures by retrying or moving on
-   *
-   * @example
-   * ```typescript
-   * const result = await manager.getNextWorkItem(agent);
-   *
-   * if (!result.item) {
-   *   console.log('No work available for agent:', agent.name);
-   *   return;
-   * }
-   *
-   * if (!result.claimed) {
-   *   console.log('Work was claimed by another agent');
-   *   return;
-   * }
-   *
-   * // Safe to process the work item
-   * console.log('Processing:', result.item.title);
-   * ```
-   */
-  getNextWorkItem(
-    agent: ResolvedAgent,
-    options?: GetNextWorkItemOptions
-  ): Promise<GetNextWorkItemResult>;
-
-  /**
-   * Report the outcome of processing a work item
-   *
-   * Updates the external system (GitHub, Linear, etc.) with the job result.
-   * This typically involves:
-   * - Adding a comment with the summary
-   * - Closing the issue/task if successful
-   * - Removing in-progress labels
-   * - Adding completion labels
-   *
-   * @param taskId - The work item ID (from WorkItem.id)
-   * @param result - The outcome of the work
-   * @param options - Options including the agent that processed the item
-   *
-   * @remarks
-   * - Must be called after job completion (success or failure)
-   * - For failures, use result.outcome='failure' and include result.error
-   * - The external system behavior depends on the adapter implementation
-   *
-   * @example
-   * ```typescript
-   * // Success case
-   * await manager.reportOutcome(
-   *   workItem.id,
-   *   {
-   *     outcome: 'success',
-   *     summary: 'Fixed the authentication bug',
-   *     details: 'Updated the JWT validation logic...',
-   *     artifacts: ['https://github.com/org/repo/pull/123'],
-   *   },
-   *   { agent }
-   * );
-   *
-   * // Failure case
-   * await manager.reportOutcome(
-   *   workItem.id,
-   *   {
-   *     outcome: 'failure',
-   *     summary: 'Unable to reproduce the issue',
-   *     error: 'Tests pass on all environments',
-   *   },
-   *   { agent }
-   * );
-   * ```
-   */
-  reportOutcome(
-    taskId: string,
-    result: WorkResult,
-    options: ReportOutcomeOptions
-  ): Promise<void>;
-
-  /**
-   * Release a claimed work item without completing it
-   *
-   * Returns the work item to the available pool so other agents can claim it.
-   * Use this when:
-   * - Job times out
-   * - Unexpected error prevents completion
-   * - Agent is shutting down mid-task
-   * - Manual intervention is needed
-   *
-   * @param taskId - The work item ID (from WorkItem.id)
-   * @param options - Release options including reason and agent
-   * @returns Result indicating if the release was successful
-   *
-   * @remarks
-   * - Always call this or reportOutcome after claiming work
-   * - If addComment is true, posts a comment explaining the release
-   * - The work item becomes available for other agents to claim
-   *
-   * @example
-   * ```typescript
-   * // On timeout
-   * await manager.releaseWorkItem(workItem.id, {
-   *   agent,
-   *   reason: 'Job timed out after 30 minutes',
-   *   addComment: true,
-   * });
-   *
-   * // On error
-   * await manager.releaseWorkItem(workItem.id, {
-   *   agent,
-   *   reason: `Unexpected error: ${error.message}`,
-   *   addComment: true,
-   * });
-   * ```
-   */
-  releaseWorkItem(
-    taskId: string,
-    options: ReleaseWorkItemOptions
-  ): Promise<ReleaseResult>;
-
-  /**
-   * Get the work source adapter for an agent
-   *
-   * Returns the cached adapter instance for the agent's work source,
-   * or null if the agent has no work source configured.
-   *
-   * This is useful for:
-   * - Direct adapter operations not covered by the manager
-   * - Inspecting adapter state or configuration
-   * - Testing and debugging
-   *
-   * @param agent - The resolved agent configuration
-   * @returns The adapter instance or null
-   *
-   * @remarks
-   * - Adapters are cached per agent (by agent name + work source type)
-   * - Creating new adapters is cheap but caching improves consistency
-   * - The adapter is created lazily on first access
-   *
-   * @example
-   * ```typescript
-   * const adapter = await manager.getAdapter(agent);
-   *
-   * if (!adapter) {
-   *   console.log('Agent has no work source configured');
-   *   return;
-   * }
-   *
-   * // Direct adapter operations
-   * const workItem = await adapter.getWork('github:12345');
-   * ```
-   */
-  getAdapter(agent: ResolvedAgent): Promise<WorkSourceAdapter | null>;
-
-  /**
-   * Clear the adapter cache
-   *
-   * Removes all cached adapter instances. Use this when:
-   * - Configuration has changed and adapters need to be recreated
-   * - Testing requires fresh adapter instances
-   * - Memory cleanup is needed
-   *
-   * @remarks
-   * - Subsequent getAdapter/getNextWorkItem calls will create new adapters
-   * - In-flight operations on old adapters are not affected
-   * - Does not affect external system state
-   */
-  clearCache(): void;
-}
-
-// =============================================================================
-// Factory Function Type
-// =============================================================================
-
-/**
- * Factory function for creating WorkSourceManager instances
- *
- * The scheduler will use this to get a manager instance. The default
- * implementation is provided by the work-sources module, but this can
- * be customized for testing or advanced use cases.
- *
- * @example
- * ```typescript
- * // Default usage
- * const manager = createWorkSourceManager();
- *
- * // With custom options (future extension point)
- * const manager = createWorkSourceManager({ cache: customCache });
- * ```
- */
-export type WorkSourceManagerFactory = () => WorkSourceManager;