@herdctl/core 0.0.1 → 0.0.2

package/src/runner/message-processor.ts

@@ -1,355 +0,0 @@
-/**
- * Message processor for transforming SDK messages to job output format
- *
- * Handles all Claude SDK message types and converts them to the format
- * expected by the job output logging system. Includes robust handling
- * of malformed or unexpected SDK responses.
- */
-
-import type { SDKMessage, ProcessedMessage } from "./types.js";
-import type { JobOutputInput } from "../state/index.js";
-
-// =============================================================================
-// Validation Helpers
-// =============================================================================
-
-/**
- * Safely extract a string value from an unknown field
- */
-function safeString(value: unknown): string | undefined {
-  if (typeof value === "string") {
-    return value;
-  }
-  if (value === null || value === undefined) {
-    return undefined;
-  }
-  // Convert other types to string for safety
-  try {
-    return String(value);
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Safely extract a boolean value from an unknown field
- */
-function safeBoolean(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") {
-    return value;
-  }
-  return undefined;
-}
-
-/**
- * Check if a value is a valid SDK message type
- */
-function isValidMessageType(
-  type: unknown
-): type is "system" | "assistant" | "tool_use" | "tool_result" | "error" {
-  return (
-    type === "system" ||
-    type === "assistant" ||
-    type === "tool_use" ||
-    type === "tool_result" ||
-    type === "error"
-  );
-}
-
-// =============================================================================
-// Message Type Handlers
-// =============================================================================
-
-/**
- * Process a system message from the SDK
- *
- * Session ID is specifically extracted from messages with subtype "init",
- * as this is when the Claude SDK provides the session identifier.
- */
-function processSystemMessage(message: SDKMessage): ProcessedMessage {
-  const output: JobOutputInput = {
-    type: "system",
-  };
-
-  if (message.content) {
-    output.content = message.content;
-  }
-
-  if (message.subtype) {
-    output.subtype = message.subtype;
-  }
-
-  // Extract session ID specifically from init messages
-  // The Claude SDK provides session_id in the system message with subtype "init"
-  const sessionId =
-    message.subtype === "init" ? message.session_id : undefined;
-
-  return {
-    output,
-    sessionId,
-  };
-}
-
-/**
- * Process an assistant message from the SDK
- */
-function processAssistantMessage(message: SDKMessage): ProcessedMessage {
-  const output: JobOutputInput = {
-    type: "assistant",
-  };
-
-  if (message.content !== undefined) {
-    output.content = message.content;
-  }
-
-  if (message.partial !== undefined) {
-    output.partial = message.partial as boolean;
-  }
-
-  // Handle usage statistics
-  if (message.usage) {
-    const usage = message.usage as {
-      input_tokens?: number;
-      output_tokens?: number;
-    };
-    output.usage = {};
-    if (usage.input_tokens !== undefined) {
-      output.usage.input_tokens = usage.input_tokens;
-    }
-    if (usage.output_tokens !== undefined) {
-      output.usage.output_tokens = usage.output_tokens;
-    }
-  }
-
-  return { output };
-}
-
-/**
- * Process a tool use message from the SDK
- */
-function processToolUseMessage(message: SDKMessage): ProcessedMessage {
-  // Tool name is required - try multiple possible field names
-  const toolName = message.tool_name ?? message.name ?? "unknown";
-
-  const output: JobOutputInput = {
-    type: "tool_use",
-    tool_name: toolName as string,
-  };
-
-  if (message.tool_use_id) {
-    output.tool_use_id = message.tool_use_id;
-  }
-
-  if (message.input !== undefined) {
-    output.input = message.input;
-  }
-
-  return { output };
-}
-
-/**
- * Process a tool result message from the SDK
- */
-function processToolResultMessage(message: SDKMessage): ProcessedMessage {
-  const output: JobOutputInput = {
-    type: "tool_result",
-  };
-
-  if (message.tool_use_id) {
-    output.tool_use_id = message.tool_use_id;
-  }
-
-  if (message.result !== undefined) {
-    output.result = message.result;
-  }
-
-  if (message.success !== undefined) {
-    output.success = message.success as boolean;
-  }
-
-  if (message.error !== undefined) {
-    output.error = message.error as string;
-  }
-
-  return { output };
-}
-
-/**
- * Process an error message from the SDK
- */
-function processErrorMessage(message: SDKMessage): ProcessedMessage {
-  const output: JobOutputInput = {
-    type: "error",
-    message: (message.message as string) ?? "Unknown error",
-  };
-
-  if (message.code) {
-    output.code = message.code;
-  }
-
-  if (message.stack) {
-    output.stack = message.stack as string;
-  }
-
-  return {
-    output,
-    isFinal: true,
-  };
-}
-
-// =============================================================================
-// Main Processing Function
-// =============================================================================
-
-/**
- * Process an SDK message into job output format
- *
- * Takes a message from the Claude Agent SDK and transforms it into
- * the format expected by the job output logging system. This function
- * handles malformed responses gracefully without crashing.
- *
- * @param message - The SDK message to process
- * @returns Processed message with output and optional metadata
- *
- * @example
- * ```typescript
- * const sdkMessage = { type: "assistant", content: "Hello!" };
- * const { output, sessionId } = processSDKMessage(sdkMessage);
- * await appendJobOutput(jobsDir, jobId, output);
- * ```
- */
-export function processSDKMessage(message: SDKMessage): ProcessedMessage {
-  // Handle null/undefined messages - log as system warning, not error
-  // to avoid terminating execution due to malformed SDK responses
-  if (message === null || message === undefined) {
-    return {
-      output: {
-        type: "system",
-        content: "Received null or undefined SDK message",
-        subtype: "malformed_message",
-      },
-    };
-  }
-
-  // Handle non-object messages - log as system warning
-  if (typeof message !== "object") {
-    return {
-      output: {
-        type: "system",
-        content: `Expected object message, received ${typeof message}`,
-        subtype: "malformed_message",
-      },
-    };
-  }
-
-  // Validate message type
-  const messageType = message.type;
-
-  if (!isValidMessageType(messageType)) {
-    // Handle unknown or missing message types gracefully
-    const unknownType = safeString(messageType) ?? "undefined";
-    return {
-      output: {
-        type: "system",
-        content: `Unknown message type: ${unknownType}`,
-        subtype: "unknown_type",
-      },
-    };
-  }
-
-  // Process known message types
-  switch (messageType) {
-    case "system":
-      return processSystemMessage(message);
-
-    case "assistant":
-      return processAssistantMessage(message);
-
-    case "tool_use":
-      return processToolUseMessage(message);
-
-    case "tool_result":
-      return processToolResultMessage(message);
-
-    case "error":
-      return processErrorMessage(message);
-  }
-}
-
-/**
- * Check if a message indicates the end of execution
- *
- * @param message - The SDK message to check
- * @returns true if this is a terminal message
- */
-export function isTerminalMessage(message: SDKMessage): boolean {
-  // Handle null/undefined/non-object messages - these are not terminal
-  if (message === null || message === undefined || typeof message !== "object") {
-    return false;
-  }
-
-  // Error messages are terminal
-  if (message.type === "error") {
-    return true;
-  }
-
-  // System messages with certain subtypes indicate completion
-  if (message.type === "system") {
-    const subtype = message.subtype as string | undefined;
-    if (
-      subtype === "end" ||
-      subtype === "complete" ||
-      subtype === "session_end"
-    ) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/** Maximum summary length in characters */
-const MAX_SUMMARY_LENGTH = 500;
-
-/**
- * Truncate a string to maximum length, adding ellipsis if truncated
- */
-function truncateSummary(text: string): string {
-  if (text.length <= MAX_SUMMARY_LENGTH) {
-    return text;
-  }
-  return text.slice(0, MAX_SUMMARY_LENGTH - 3) + "...";
-}
-
-/**
- * Extract the final summary from a message if present
- *
- * Looks for summaries in the following order:
- * 1. Explicit `summary` field on the message (truncated to 500 chars)
- * 2. Short assistant message content (≤500 chars, non-partial)
- *
- * @param message - The SDK message to extract summary from
- * @returns Summary string if present, undefined otherwise
- */
-export function extractSummary(message: SDKMessage): string | undefined {
-  // Handle null/undefined/non-object messages
-  if (message === null || message === undefined || typeof message !== "object") {
-    return undefined;
-  }
-
-  // Check for explicit summary field (truncate if too long)
-  if (message.summary) {
-    const summaryStr = String(message.summary);
-    return truncateSummary(summaryStr);
-  }
-
-  // For assistant messages, use content as potential summary
-  if (message.type === "assistant" && message.content && !message.partial) {
-    // Only use if it looks like a conclusion (short enough)
-    if (message.content.length <= MAX_SUMMARY_LENGTH) {
-      return message.content;
-    }
-  }
-
-  return undefined;
-}

package/src/runner/sdk-adapter.ts

@@ -1,191 +0,0 @@
-/**
- * SDK Adapter for transforming agent configuration to SDK options
- *
- * Transforms ResolvedAgent configuration to the format expected by
- * the Claude Agent SDK's query function.
- */
-
-import type { ResolvedAgent, McpServer } from "../config/index.js";
-import type {
-  SDKQueryOptions,
-  SDKMcpServerConfig,
-  SDKSystemPrompt,
-} from "./types.js";
-
-// =============================================================================
-// Constants
-// =============================================================================
-
-/**
- * Default permission mode when not specified in agent config
- */
-const DEFAULT_PERMISSION_MODE = "acceptEdits" as const;
-
-/**
- * Default setting sources for SDK initialization
- */
-const DEFAULT_SETTING_SOURCES = ["project", "local"] as const;
-
-/**
- * Default preset when no system prompt is specified
- */
-const DEFAULT_PRESET = "claude_code";
-
-// =============================================================================
-// MCP Server Transformation
-// =============================================================================
-
-/**
- * Transform a single MCP server configuration to SDK format
- *
- * @param server - MCP server configuration from agent config
- * @returns SDK-formatted MCP server configuration
- */
-export function transformMcpServer(server: McpServer): SDKMcpServerConfig {
-  const result: SDKMcpServerConfig = {};
-
-  // HTTP-based MCP server
-  if (server.url) {
-    result.type = "http";
-    result.url = server.url;
-  }
-
-  // Process-based MCP server
-  if (server.command) {
-    result.command = server.command;
-  }
-
-  if (server.args && server.args.length > 0) {
-    result.args = server.args;
-  }
-
-  if (server.env && Object.keys(server.env).length > 0) {
-    result.env = server.env;
-  }
-
-  return result;
-}
-
-/**
- * Transform MCP servers configuration to SDK format
- *
- * @param mcpServers - MCP servers configuration from agent config
- * @returns SDK-formatted MCP servers map (empty object if no servers configured)
- */
-export function transformMcpServers(
-  mcpServers: Record<string, McpServer> | undefined
-): Record<string, SDKMcpServerConfig> {
-  const result: Record<string, SDKMcpServerConfig> = {};
-
-  if (!mcpServers) {
-    return result;
-  }
-
-  for (const [name, server] of Object.entries(mcpServers)) {
-    result[name] = transformMcpServer(server);
-  }
-
-  return result;
-}
-
-// =============================================================================
-// System Prompt Transformation
-// =============================================================================
-
-/**
- * Build the system prompt configuration for SDK
- *
- * @param agent - Resolved agent configuration
- * @returns System prompt configuration for SDK
- */
-export function buildSystemPrompt(agent: ResolvedAgent): SDKSystemPrompt {
-  // If agent has a custom system prompt, use it
-  if (agent.system_prompt) {
-    return {
-      type: "custom",
-      content: agent.system_prompt,
-    };
-  }
-
-  // Default to claude_code preset
-  return {
-    type: "preset",
-    preset: DEFAULT_PRESET,
-  };
-}
-
-// =============================================================================
-// Main Transformation Function
-// =============================================================================
-
-/**
- * Options for SDK transformation
- */
-export interface ToSDKOptionsParams {
-  /** Session ID to resume */
-  resume?: string;
-  /** Whether to fork the session */
-  fork?: boolean;
-}
-
-/**
- * Transform agent configuration to SDK query options
- *
- * This function converts a ResolvedAgent configuration to the format
- * expected by the Claude Agent SDK's query function.
- *
- * @param agent - Fully resolved agent configuration
- * @param options - Additional options for resume/fork
- * @returns SDK query options ready for use with the SDK
- *
- * @example
- * ```typescript
- * const agent = await loadConfig().then(c => c.agents[0]);
- * const sdkOptions = toSDKOptions(agent);
- *
- * for await (const message of query({ prompt, options: sdkOptions })) {
- *   console.log(message);
- * }
- * ```
- */
-export function toSDKOptions(
-  agent: ResolvedAgent,
-  options: ToSDKOptionsParams = {}
-): SDKQueryOptions {
-  const result: SDKQueryOptions = {};
-
-  // Permission mode (defaults to acceptEdits)
-  result.permissionMode =
-    agent.permissions?.mode ??
-    agent.permission_mode ??
-    DEFAULT_PERMISSION_MODE;
-
-  // Allowed and denied tools
-  if (agent.permissions?.allowed_tools?.length) {
-    result.allowedTools = agent.permissions.allowed_tools;
-  }
-
-  if (agent.permissions?.denied_tools?.length) {
-    result.deniedTools = agent.permissions.denied_tools;
-  }
-
-  // System prompt
-  result.systemPrompt = buildSystemPrompt(agent);
-
-  // Setting sources for proper settings discovery
-  result.settingSources = [...DEFAULT_SETTING_SOURCES];
-
-  // MCP servers (always include, even if empty)
-  result.mcpServers = transformMcpServers(agent.mcp_servers);
-
-  // Session resume/fork
-  if (options.resume) {
-    result.resume = options.resume;
-  }
-
-  if (options.fork) {
-    result.forkSession = true;
-  }
-
-  return result;
-}

package/src/runner/types.ts

@@ -1,158 +0,0 @@
-/**
- * Type definitions for the agent runner module
- *
- * Defines options, results, and SDK-related types for agent execution
- */
-
-import type { ResolvedAgent } from "../config/index.js";
-import type { TriggerType, JobOutputInput } from "../state/index.js";
-
-// =============================================================================
-// Runner Options Types
-// =============================================================================
-
-/**
- * Options for running an agent
- */
-export interface RunnerOptions {
-  /** Fully resolved agent configuration */
-  agent: ResolvedAgent;
-  /** The prompt to send to the agent */
-  prompt: string;
-  /** Path to the .herdctl directory */
-  stateDir: string;
-  /** How this run was triggered */
-  triggerType?: TriggerType;
-  /** Schedule name (if triggered by schedule) */
-  schedule?: string;
-  /** Session ID to resume (mutually exclusive with fork) */
-  resume?: string;
-  /** Fork from this session ID */
-  fork?: string;
-  /** Parent job ID when forking (used with fork option) */
-  forkedFrom?: string;
-}
-
-/**
- * SDK message types (as received from Claude Agent SDK)
- */
-export interface SDKMessage {
-  type: "system" | "assistant" | "tool_use" | "tool_result" | "error";
-  subtype?: string;
-  content?: string;
-  session_id?: string;
-  name?: string;
-  input?: unknown;
-  tool_use_id?: string;
-  message?: string;
-  code?: string;
-  // Allow additional SDK-specific fields
-  [key: string]: unknown;
-}
-
-/**
- * Callback for receiving messages during execution
- */
-export type MessageCallback = (message: SDKMessage) => void | Promise<void>;
-
-/**
- * Extended options including callbacks
- */
-export interface RunnerOptionsWithCallbacks extends RunnerOptions {
-  /** Called for each message from the SDK */
-  onMessage?: MessageCallback;
-}
-
-// =============================================================================
-// Runner Result Types
-// =============================================================================
-
-/**
- * Detailed error information for failed runs
- */
-export interface RunnerErrorDetails {
-  /** The error message */
-  message: string;
-  /** Error code if available (e.g., ETIMEDOUT, ECONNREFUSED) */
-  code?: string;
-  /** The type of error (for categorization) */
-  type?: "initialization" | "streaming" | "malformed_response" | "unknown";
-  /** Whether this error is potentially recoverable (e.g., rate limit, network) */
-  recoverable?: boolean;
-  /** Number of messages received before error (for streaming errors) */
-  messagesReceived?: number;
-  /** Stack trace if available */
-  stack?: string;
-}
-
-/**
- * Result of running an agent
- */
-export interface RunnerResult {
-  /** Whether the run completed successfully */
-  success: boolean;
-  /** The job ID for this run */
-  jobId: string;
-  /** The session ID (for resume/fork) */
-  sessionId?: string;
-  /** Brief summary of what was accomplished */
-  summary?: string;
-  /** Error if the run failed */
-  error?: Error;
-  /** Detailed error information for programmatic access */
-  errorDetails?: RunnerErrorDetails;
-  /** Duration in seconds */
-  durationSeconds?: number;
-}
-
-// =============================================================================
-// SDK Option Types
-// =============================================================================
-
-/**
- * MCP server configuration for SDK
- */
-export interface SDKMcpServerConfig {
-  type?: "http";
-  url?: string;
-  command?: string;
-  args?: string[];
-  env?: Record<string, string>;
-}
-
-/**
- * System prompt configuration for SDK
- */
-export type SDKSystemPrompt =
-  | { type: "preset"; preset: string }
-  | { type: "custom"; content: string };
-
-/**
- * SDK query options (matching Claude Agent SDK types)
- */
-export interface SDKQueryOptions {
-  allowedTools?: string[];
-  deniedTools?: string[];
-  permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan";
-  systemPrompt?: SDKSystemPrompt;
-  settingSources?: string[];
-  mcpServers?: Record<string, SDKMcpServerConfig>;
-  resume?: string;
-  forkSession?: boolean;
-}
-
-// =============================================================================
-// Message Processing Types
-// =============================================================================
-
-/**
- * Result of processing an SDK message
- */
-export interface ProcessedMessage {
-  /** The message transformed for job output */
-  output: JobOutputInput;
-  /** Session ID if this was an init message */
-  sessionId?: string;
-  /** Whether this is the final message */
-  isFinal?: boolean;
-}