@herdctl/core 0.0.1 → 0.0.2

package/src/state/schemas/fleet-state.ts

@@ -1,120 +0,0 @@
-/**
- * Zod schemas for fleet state (state.yaml)
- *
- * Defines the schema for tracking fleet-wide state including agent status
- */
-
-import { z } from "zod";
-
-// =============================================================================
-// Schedule State Schemas
-// =============================================================================
-
-/**
- * Possible states for a schedule
- */
-export const ScheduleStatusSchema = z.enum(["idle", "running", "disabled"]);
-
-/**
- * State information for a single schedule
- */
-export const ScheduleStateSchema = z.object({
-  /** ISO timestamp of when this schedule last ran */
-  last_run_at: z.string().nullable().optional(),
-  /** ISO timestamp of when this schedule will next run */
-  next_run_at: z.string().nullable().optional(),
-  /** Current status of the schedule */
-  status: ScheduleStatusSchema.default("idle"),
-  /** Last error message if the schedule encountered an error */
-  last_error: z.string().nullable().optional(),
-});
-
-// =============================================================================
-// Agent Status Schemas
-// =============================================================================
-
-/**
- * Possible states for an agent
- */
-export const AgentStatusSchema = z.enum(["idle", "running", "error"]);
-
-/**
- * State information for a single agent
- */
-export const AgentStateSchema = z.object({
-  /** Current status of the agent */
-  status: AgentStatusSchema.default("idle"),
-  /** ID of the currently running job, if any */
-  current_job: z.string().nullable().optional(),
-  /** ID of the last completed job */
-  last_job: z.string().nullable().optional(),
-  /** Name of the schedule that will trigger the next run */
-  next_schedule: z.string().nullable().optional(),
-  /** ISO timestamp of when the next scheduled run will occur */
-  next_trigger_at: z.string().nullable().optional(),
-  /** Docker container ID if running in container */
-  container_id: z.string().nullable().optional(),
-  /** Error message if status is 'error' */
-  error_message: z.string().nullable().optional(),
-  /** Map of schedule names to their state */
-  schedules: z.record(z.string(), ScheduleStateSchema).optional(),
-});
-
-// =============================================================================
-// Fleet State Schemas
-// =============================================================================
-
-/**
- * Fleet metadata stored in state.yaml
- */
-export const FleetMetadataSchema = z.object({
-  /** ISO timestamp of when the fleet was first started */
-  started_at: z.string().optional(),
-});
-
-/**
- * Top-level fleet state schema (state.yaml)
- */
-export const FleetStateSchema = z.object({
-  /** Fleet metadata */
-  fleet: FleetMetadataSchema.optional().default({}),
-  /** Map of agent names to their current state */
-  agents: z.record(z.string(), AgentStateSchema).optional().default({}),
-});
-
-// =============================================================================
-// Type Exports
-// =============================================================================
-
-export type ScheduleStatus = z.infer<typeof ScheduleStatusSchema>;
-export type ScheduleState = z.infer<typeof ScheduleStateSchema>;
-export type AgentStatus = z.infer<typeof AgentStatusSchema>;
-export type AgentState = z.infer<typeof AgentStateSchema>;
-export type FleetMetadata = z.infer<typeof FleetMetadataSchema>;
-export type FleetState = z.infer<typeof FleetStateSchema>;
-
-// =============================================================================
-// Default State
-// =============================================================================
-
-/**
- * Create a new empty fleet state
- */
-export function createInitialFleetState(): FleetState {
-  return {
-    fleet: {},
-    agents: {},
-  };
-}
-
-/**
- * Create a default schedule state
- */
-export function createDefaultScheduleState(): ScheduleState {
-  return {
-    last_run_at: null,
-    next_run_at: null,
-    status: "idle",
-    last_error: null,
-  };
-}

package/src/state/schemas/index.ts

@@ -1,67 +0,0 @@
-/**
- * State management schemas
- *
- * Re-exports all Zod schemas for state management
- */
-
-export {
-  ScheduleStatusSchema,
-  ScheduleStateSchema,
-  AgentStatusSchema,
-  AgentStateSchema,
-  FleetMetadataSchema,
-  FleetStateSchema,
-  createInitialFleetState,
-  createDefaultScheduleState,
-  type ScheduleStatus,
-  type ScheduleState,
-  type AgentStatus,
-  type AgentState,
-  type FleetMetadata,
-  type FleetState,
-} from "./fleet-state.js";
-
-export {
-  JobStatusSchema,
-  TriggerTypeSchema,
-  ExitReasonSchema,
-  JobMetadataSchema,
-  generateJobId,
-  createJobMetadata,
-  type JobStatus,
-  type TriggerType,
-  type ExitReason,
-  type JobMetadata,
-  type CreateJobOptions,
-} from "./job-metadata.js";
-
-export {
-  JobOutputTypeSchema,
-  JobOutputBaseSchema,
-  SystemMessageSchema,
-  AssistantMessageSchema,
-  ToolUseMessageSchema,
-  ToolResultMessageSchema,
-  ErrorMessageSchema,
-  JobOutputMessageSchema,
-  validateJobOutputMessage,
-  isValidJobOutputInput,
-  type JobOutputType,
-  type JobOutputBase,
-  type SystemMessage,
-  type AssistantMessage,
-  type ToolUseMessage,
-  type ToolResultMessage,
-  type ErrorMessage,
-  type JobOutputMessage,
-  type JobOutputInput,
-} from "./job-output.js";
-
-export {
-  SessionModeSchema,
-  SessionInfoSchema,
-  createSessionInfo,
-  type SessionMode,
-  type SessionInfo,
-  type CreateSessionOptions,
-} from "./session-info.js";

package/src/state/schemas/job-metadata.ts

@@ -1,181 +0,0 @@
-/**
- * Zod schemas for job metadata (job-<id>.yaml)
- *
- * Defines the schema for tracking individual job execution metadata
- * including timing, status, and execution context.
- */
-
-import { z } from "zod";
-
-// =============================================================================
-// Job Status Schemas
-// =============================================================================
-
-/**
- * Possible states for a job
- */
-export const JobStatusSchema = z.enum([
-  "pending",
-  "running",
-  "completed",
-  "failed",
-  "cancelled",
-]);
-
-/**
- * How the job was triggered
- */
-export const TriggerTypeSchema = z.enum([
-  "manual",
-  "schedule",
-  "webhook",
-  "chat",
-  "fork",
-]);
-
-/**
- * Reason why a job exited
- */
-export const ExitReasonSchema = z.enum([
-  "success",
-  "error",
-  "timeout",
-  "cancelled",
-  "max_turns",
-]);
-
-// =============================================================================
-// Job Metadata Schema
-// =============================================================================
-
-/**
- * Job metadata schema for individual job files
- *
- * Each job is stored as .herdctl/jobs/job-<id>.yaml
- */
-export const JobMetadataSchema = z.object({
-  /** Unique job identifier (format: job-YYYY-MM-DD-<random6>) */
-  id: z.string().regex(/^job-\d{4}-\d{2}-\d{2}-[a-z0-9]{6}$/, {
-    message: "Job ID must match format: job-YYYY-MM-DD-<random6>",
-  }),
-
-  /** Name of the agent that executed this job */
-  agent: z.string().min(1),
-
-  /** Schedule name that triggered the job (if applicable) */
-  schedule: z.string().nullable().optional(),
-
-  /** How the job was triggered */
-  trigger_type: TriggerTypeSchema,
-
-  /** Current status of the job */
-  status: JobStatusSchema,
-
-  /** Reason the job exited (only set when status is completed/failed/cancelled) */
-  exit_reason: ExitReasonSchema.nullable().optional(),
-
-  /** Session ID for the Claude agent session */
-  session_id: z.string().nullable().optional(),
-
-  /** Job ID this was forked from (if trigger_type is 'fork') */
-  forked_from: z
-    .string()
-    .regex(/^job-\d{4}-\d{2}-\d{2}-[a-z0-9]{6}$/)
-    .nullable()
-    .optional(),
-
-  /** ISO timestamp when the job started */
-  started_at: z.string(),
-
-  /** ISO timestamp when the job finished (null if still running) */
-  finished_at: z.string().nullable().optional(),
-
-  /** Duration of the job in seconds (calculated when finished) */
-  duration_seconds: z.number().nonnegative().nullable().optional(),
-
-  /** The prompt that was given to the agent */
-  prompt: z.string().nullable().optional(),
-
-  /** Brief summary of what the job accomplished */
-  summary: z.string().nullable().optional(),
-
-  /** Path to the output file containing full session output */
-  output_file: z.string().nullable().optional(),
-});
-
-// =============================================================================
-// Type Exports
-// =============================================================================
-
-export type JobStatus = z.infer<typeof JobStatusSchema>;
-export type TriggerType = z.infer<typeof TriggerTypeSchema>;
-export type ExitReason = z.infer<typeof ExitReasonSchema>;
-export type JobMetadata = z.infer<typeof JobMetadataSchema>;
-
-// =============================================================================
-// Factory Functions
-// =============================================================================
-
-/**
- * Options for creating a new job
- */
-export interface CreateJobOptions {
-  /** Name of the agent executing the job */
-  agent: string;
-  /** How the job was triggered */
-  trigger_type: TriggerType;
-  /** Schedule name (for scheduled jobs) */
-  schedule?: string | null;
-  /** The prompt given to the agent */
-  prompt?: string | null;
-  /** Parent job ID (for forked jobs) */
-  forked_from?: string | null;
-}
-
-/**
- * Generate a unique job ID with format: job-YYYY-MM-DD-<random6>
- *
- * @param date - Optional date to use (defaults to now)
- * @param randomFn - Optional random function for testing
- */
-export function generateJobId(
-  date: Date = new Date(),
-  randomFn: () => string = () => Math.random().toString(36).slice(2, 8)
-): string {
-  const year = date.getFullYear();
-  const month = String(date.getMonth() + 1).padStart(2, "0");
-  const day = String(date.getDate()).padStart(2, "0");
-  const random = randomFn().slice(0, 6).padEnd(6, "0");
-
-  return `job-${year}-${month}-${day}-${random}`;
-}
-
-/**
- * Create initial job metadata for a new job
- *
- * @param options - Job creation options
- * @param idGenerator - Optional function to generate job ID (for testing)
- */
-export function createJobMetadata(
-  options: CreateJobOptions,
-  idGenerator: () => string = generateJobId
-): JobMetadata {
-  const now = new Date().toISOString();
-
-  return {
-    id: idGenerator(),
-    agent: options.agent,
-    schedule: options.schedule ?? null,
-    trigger_type: options.trigger_type,
-    status: "pending",
-    exit_reason: null,
-    session_id: null,
-    forked_from: options.forked_from ?? null,
-    started_at: now,
-    finished_at: null,
-    duration_seconds: null,
-    prompt: options.prompt ?? null,
-    summary: null,
-    output_file: null,
-  };
-}

package/src/state/schemas/job-output.ts

@@ -1,177 +0,0 @@
-/**
- * Zod schemas for job output messages (job-<id>.jsonl)
- *
- * Defines the schema for streaming job output from Claude SDK.
- * Each line in the JSONL file is a JobOutputMessage.
- */
-
-import { z } from "zod";
-
-// =============================================================================
-// Message Type Schema
-// =============================================================================
-
-/**
- * Types of messages from Claude SDK streaming output
- */
-export const JobOutputTypeSchema = z.enum([
-  "system",
-  "assistant",
-  "tool_use",
-  "tool_result",
-  "error",
-]);
-
-// =============================================================================
-// Base Message Schema
-// =============================================================================
-
-/**
- * Base fields present in all job output messages
- */
-export const JobOutputBaseSchema = z.object({
-  /** Message type */
-  type: JobOutputTypeSchema,
-  /** ISO timestamp when message was recorded */
-  timestamp: z.string(),
-});
-
-// =============================================================================
-// Specific Message Type Schemas
-// =============================================================================
-
-/**
- * System message schema
- */
-export const SystemMessageSchema = JobOutputBaseSchema.extend({
-  type: z.literal("system"),
-  /** System message content */
-  content: z.string().optional(),
-  /** Optional subtype for system messages */
-  subtype: z.string().optional(),
-});
-
-/**
- * Assistant message schema
- */
-export const AssistantMessageSchema = JobOutputBaseSchema.extend({
-  type: z.literal("assistant"),
-  /** Assistant response content */
-  content: z.string().optional(),
-  /** Whether this is a partial/streaming chunk */
-  partial: z.boolean().optional(),
-  /** Token usage info if available */
-  usage: z
-    .object({
-      input_tokens: z.number().optional(),
-      output_tokens: z.number().optional(),
-    })
-    .optional(),
-});
-
-/**
- * Tool use message schema
- */
-export const ToolUseMessageSchema = JobOutputBaseSchema.extend({
-  type: z.literal("tool_use"),
-  /** Tool being invoked */
-  tool_name: z.string(),
-  /** Unique identifier for this tool call */
-  tool_use_id: z.string().optional(),
-  /** Tool input parameters */
-  input: z.unknown().optional(),
-});
-
-/**
- * Tool result message schema
- */
-export const ToolResultMessageSchema = JobOutputBaseSchema.extend({
-  type: z.literal("tool_result"),
-  /** ID of the tool call this is a result for */
-  tool_use_id: z.string().optional(),
-  /** Tool execution result */
-  result: z.unknown().optional(),
-  /** Whether the tool execution succeeded */
-  success: z.boolean().optional(),
-  /** Error message if tool failed */
-  error: z.string().optional(),
-});
-
-/**
- * Error message schema
- */
-export const ErrorMessageSchema = JobOutputBaseSchema.extend({
-  type: z.literal("error"),
-  /** Error message */
-  message: z.string(),
-  /** Error code if available */
-  code: z.string().optional(),
-  /** Stack trace if available */
-  stack: z.string().optional(),
-});
-
-// =============================================================================
-// Union Schema for All Message Types
-// =============================================================================
-
-/**
- * Schema that validates any job output message type
- */
-export const JobOutputMessageSchema = z.discriminatedUnion("type", [
-  SystemMessageSchema,
-  AssistantMessageSchema,
-  ToolUseMessageSchema,
-  ToolResultMessageSchema,
-  ErrorMessageSchema,
-]);
-
-// =============================================================================
-// Type Exports
-// =============================================================================
-
-export type JobOutputType = z.infer<typeof JobOutputTypeSchema>;
-export type JobOutputBase = z.infer<typeof JobOutputBaseSchema>;
-export type SystemMessage = z.infer<typeof SystemMessageSchema>;
-export type AssistantMessage = z.infer<typeof AssistantMessageSchema>;
-export type ToolUseMessage = z.infer<typeof ToolUseMessageSchema>;
-export type ToolResultMessage = z.infer<typeof ToolResultMessageSchema>;
-export type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
-export type JobOutputMessage = z.infer<typeof JobOutputMessageSchema>;
-
-// =============================================================================
-// Input Types (without timestamp - added automatically)
-// =============================================================================
-
-/**
- * Input type for appending messages (timestamp added automatically)
- */
-export type JobOutputInput =
-  | Omit<SystemMessage, "timestamp">
-  | Omit<AssistantMessage, "timestamp">
-  | Omit<ToolUseMessage, "timestamp">
-  | Omit<ToolResultMessage, "timestamp">
-  | Omit<ErrorMessage, "timestamp">;
-
-/**
- * Validate a job output message
- */
-export function validateJobOutputMessage(
-  message: unknown
-): JobOutputMessage | null {
-  const result = JobOutputMessageSchema.safeParse(message);
-  return result.success ? result.data : null;
-}
-
-/**
- * Check if a message has the minimum required fields
- */
-export function isValidJobOutputInput(input: unknown): input is JobOutputInput {
-  if (typeof input !== "object" || input === null) {
-    return false;
-  }
-  const obj = input as Record<string, unknown>;
-  return (
-    typeof obj.type === "string" &&
-    JobOutputTypeSchema.safeParse(obj.type).success
-  );
-}

package/src/state/schemas/session-info.ts

@@ -1,92 +0,0 @@
-/**
- * Zod schemas for session info (sessions/<agent-name>.json)
- *
- * Defines the schema for tracking Claude session information per agent,
- * enabling session resume and fork capabilities.
- */
-
-import { z } from "zod";
-
-// =============================================================================
-// Session Mode Schema
-// =============================================================================
-
-/**
- * The operational mode of the session
- */
-export const SessionModeSchema = z.enum([
-  "autonomous",
-  "interactive",
-  "review",
-]);
-
-// =============================================================================
-// Session Info Schema
-// =============================================================================
-
-/**
- * Session info schema for individual agent session files
- *
- * Each session is stored as .herdctl/sessions/<agent-name>.json
- */
-export const SessionInfoSchema = z.object({
-  /** Name of the agent this session belongs to */
-  agent_name: z.string().min(1, "Agent name cannot be empty"),
-
-  /** Claude session ID for resuming conversations */
-  session_id: z.string().min(1, "Session ID cannot be empty"),
-
-  /** ISO timestamp when the session was created */
-  created_at: z.string().datetime({ message: "created_at must be a valid ISO datetime string" }),
-
-  /** ISO timestamp when the session was last used */
-  last_used_at: z.string().datetime({ message: "last_used_at must be a valid ISO datetime string" }),
-
-  /** Number of jobs executed in this session */
-  job_count: z.number().int().nonnegative(),
-
-  /** Current operational mode of the session */
-  mode: SessionModeSchema,
-});
-
-// =============================================================================
-// Type Exports
-// =============================================================================
-
-export type SessionMode = z.infer<typeof SessionModeSchema>;
-export type SessionInfo = z.infer<typeof SessionInfoSchema>;
-
-// =============================================================================
-// Factory Functions
-// =============================================================================
-
-/**
- * Options for creating a new session
- */
-export interface CreateSessionOptions {
-  /** Name of the agent */
-  agent_name: string;
-  /** Claude session ID */
-  session_id: string;
-  /** Operational mode (defaults to 'autonomous') */
-  mode?: SessionMode;
-}
-
-/**
- * Create initial session info for a new session
- *
- * @param options - Session creation options
- * @returns A validated SessionInfo object
- */
-export function createSessionInfo(options: CreateSessionOptions): SessionInfo {
-  const now = new Date().toISOString();
-
-  return {
-    agent_name: options.agent_name,
-    session_id: options.session_id,
-    created_at: now,
-    last_used_at: now,
-    job_count: 0,
-    mode: options.mode ?? "autonomous",
-  };
-}