@herdctl/core 0.0.1

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

@@ -0,0 +1,120 @@
+/**
+ * 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

@@ -0,0 +1,67 @@
+/**
+ * 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

@@ -0,0 +1,181 @@
+/**
+ * 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

@@ -0,0 +1,177 @@
+/**
+ * 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

@@ -0,0 +1,92 @@
+/**
+ * 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",
+  };
+}