@herdctl/core 0.0.1

package/dist/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,aAAa,CAAC;AAG5B,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,SAAS,EACT,SAAS,EACT,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC"}

package/dist/state/index.js

@@ -0,0 +1,30 @@
+/**
+ * State management module
+ *
+ * Provides utilities for managing herdctl state files including:
+ * - State directory initialization and management
+ * - Atomic file writes to prevent corruption
+ * - YAML and JSONL file operations
+ * - Safe reads with validation
+ * - Fleet state (state.yaml) management
+ * - Job metadata (job-<id>.yaml) management
+ */
+// Re-export types
+export * from "./types.js";
+// Re-export errors
+export * from "./errors.js";
+// Re-export schemas
+export * from "./schemas/index.js";
+// Re-export directory functions
+export { initStateDirectory, getStateDirectory, validateStateDirectory, } from "./directory.js";
+// Re-export file utilities
+export * from "./utils/index.js";
+// Re-export fleet state functions
+export { readFleetState, writeFleetState, updateAgentState, initializeFleetState, removeAgentState, } from "./fleet-state.js";
+// Re-export job metadata functions
+export { createJob, updateJob, getJob, listJobs, deleteJob, } from "./job-metadata.js";
+// Re-export job output functions
+export { getJobOutputPath, appendJobOutput, appendJobOutputBatch, readJobOutput, readJobOutputAll, } from "./job-output.js";
+// Re-export session functions
+export { getSessionInfo, updateSessionInfo, clearSession, } from "./session.js";
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kBAAkB;AAClB,cAAc,YAAY,CAAC;AAE3B,mBAAmB;AACnB,cAAc,aAAa,CAAC;AAE5B,oBAAoB;AACpB,cAAc,oBAAoB,CAAC;AAEnC,gCAAgC;AAChC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,2BAA2B;AAC3B,cAAc,kBAAkB,CAAC;AAEjC,kCAAkC;AAClC,OAAO,EACL,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,GAKjB,MAAM,kBAAkB,CAAC;AAE1B,mCAAmC;AACnC,OAAO,EACL,SAAS,EACT,SAAS,EACT,MAAM,EACN,QAAQ,EACR,SAAS,GAMV,MAAM,mBAAmB,CAAC;AAE3B,iCAAiC;AACjC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,GAIjB,MAAM,iBAAiB,CAAC;AAEzB,8BAA8B;AAC9B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,GAIb,MAAM,cAAc,CAAC"}

package/dist/state/job-metadata.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Job metadata persistence operations
+ *
+ * Provides CRUD operations for job metadata files stored at
+ * .herdctl/jobs/job-<id>.yaml
+ */
+import { type JobMetadata, type JobStatus, type CreateJobOptions } from "./schemas/job-metadata.js";
+/**
+ * Options for reading/writing job metadata
+ */
+export interface JobMetadataOptions {
+    /** Logger for warnings */
+    logger?: JobLogger;
+}
+/**
+ * Logger interface for job operations
+ */
+export interface JobLogger {
+    warn: (message: string) => void;
+}
+/**
+ * Partial updates for job metadata
+ */
+export type JobMetadataUpdates = Partial<Omit<JobMetadata, "id" | "agent" | "trigger_type" | "started_at">>;
+/**
+ * Filter options for listing jobs
+ */
+export interface ListJobsFilter {
+    /** Filter by agent name */
+    agent?: string;
+    /** Filter by job status */
+    status?: JobStatus;
+    /** Filter jobs started on or after this date (ISO string or Date) */
+    startedAfter?: string | Date;
+    /** Filter jobs started on or before this date (ISO string or Date) */
+    startedBefore?: string | Date;
+}
+/**
+ * Result of listing jobs
+ */
+export interface ListJobsResult {
+    /** Array of job metadata */
+    jobs: JobMetadata[];
+    /** Number of jobs that failed to parse */
+    errors: number;
+}
+/**
+ * Create a new job and persist it to disk
+ *
+ * Creates a job metadata file at .herdctl/jobs/job-<id>.yaml
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param options - Job creation options
+ * @returns The created job metadata
+ * @throws StateFileError if the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * const job = await createJob('/path/to/.herdctl/jobs', {
+ *   agent: 'my-agent',
+ *   trigger_type: 'manual',
+ *   prompt: 'Fix the bug in auth.ts'
+ * });
+ * console.log(job.id); // 'job-2024-01-15-abc123'
+ * ```
+ */
+export declare function createJob(jobsDir: string, options: CreateJobOptions): Promise<JobMetadata>;
+/**
+ * Update an existing job's metadata
+ *
+ * Uses atomic writes to prevent corruption. Automatically calculates
+ * duration_seconds when finished_at is set.
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - The job ID to update
+ * @param updates - Partial updates to apply
+ * @returns The updated job metadata
+ * @throws StateFileError if the file cannot be read or written
+ *
+ * @example
+ * ```typescript
+ * const job = await updateJob('/path/to/.herdctl/jobs', 'job-2024-01-15-abc123', {
+ *   status: 'completed',
+ *   exit_reason: 'success',
+ *   finished_at: new Date().toISOString(),
+ *   summary: 'Fixed the auth bug'
+ * });
+ * ```
+ */
+export declare function updateJob(jobsDir: string, jobId: string, updates: JobMetadataUpdates): Promise<JobMetadata>;
+/**
+ * Get a job by its ID
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - The job ID to retrieve
+ * @returns The job metadata, or null if not found
+ * @throws StateFileError if the file exists but cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const job = await getJob('/path/to/.herdctl/jobs', 'job-2024-01-15-abc123');
+ * if (job) {
+ *   console.log(job.status); // 'running'
+ * }
+ * ```
+ */
+export declare function getJob(jobsDir: string, jobId: string, options?: JobMetadataOptions): Promise<JobMetadata | null>;
+/**
+ * List all jobs, optionally filtered
+ *
+ * Supports filtering by agent, status, and date range. Returns jobs
+ * sorted by started_at in descending order (most recent first).
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param filter - Optional filter criteria
+ * @param options - Optional operation options
+ * @returns List of matching jobs and count of parse errors
+ *
+ * @example
+ * ```typescript
+ * // List all jobs for an agent
+ * const { jobs } = await listJobs('/path/to/.herdctl/jobs', {
+ *   agent: 'my-agent'
+ * });
+ *
+ * // List failed jobs from the last 24 hours
+ * const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
+ * const { jobs } = await listJobs('/path/to/.herdctl/jobs', {
+ *   status: 'failed',
+ *   startedAfter: yesterday
+ * });
+ * ```
+ */
+export declare function listJobs(jobsDir: string, filter?: ListJobsFilter, options?: JobMetadataOptions): Promise<ListJobsResult>;
+/**
+ * Delete a job's metadata file
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - The job ID to delete
+ * @returns true if deleted, false if not found
+ *
+ * @example
+ * ```typescript
+ * const deleted = await deleteJob('/path/to/.herdctl/jobs', 'job-2024-01-15-abc123');
+ * if (deleted) {
+ *   console.log('Job deleted');
+ * }
+ * ```
+ */
+export declare function deleteJob(jobsDir: string, jobId: string): Promise<boolean>;
+//# sourceMappingURL=job-metadata.d.ts.map

package/dist/state/job-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-metadata.d.ts","sourceRoot":"","sources":["../../src/state/job-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAOnC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,OAAO,GAAG,cAAc,GAAG,YAAY,CAAC,CAClE,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAiCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAyDtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA8B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,cAAmB,EAC3B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,cAAc,CAAC,CA4FzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAkBlB"}

package/dist/state/job-metadata.js

@@ -0,0 +1,287 @@
+/**
+ * Job metadata persistence operations
+ *
+ * Provides CRUD operations for job metadata files stored at
+ * .herdctl/jobs/job-<id>.yaml
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteYaml } from "./utils/atomic.js";
+import { safeReadYaml } from "./utils/reads.js";
+import { JobMetadataSchema, createJobMetadata, generateJobId, } from "./schemas/job-metadata.js";
+import { StateFileError } from "./errors.js";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get the file path for a job
+ */
+function getJobFilePath(jobsDir, jobId) {
+    return join(jobsDir, `${jobId}.yaml`);
+}
+/**
+ * Parse an ISO date string or Date to a Date object
+ */
+function toDate(value) {
+    return value instanceof Date ? value : new Date(value);
+}
+/**
+ * Calculate duration in seconds between two ISO timestamps
+ */
+function calculateDuration(startedAt, finishedAt) {
+    const start = new Date(startedAt).getTime();
+    const end = new Date(finishedAt).getTime();
+    return Math.round((end - start) / 1000);
+}
+// =============================================================================
+// CRUD Operations
+// =============================================================================
+/**
+ * Create a new job and persist it to disk
+ *
+ * Creates a job metadata file at .herdctl/jobs/job-<id>.yaml
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param options - Job creation options
+ * @returns The created job metadata
+ * @throws StateFileError if the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * const job = await createJob('/path/to/.herdctl/jobs', {
+ *   agent: 'my-agent',
+ *   trigger_type: 'manual',
+ *   prompt: 'Fix the bug in auth.ts'
+ * });
+ * console.log(job.id); // 'job-2024-01-15-abc123'
+ * ```
+ */
+export async function createJob(jobsDir, options) {
+    const job = createJobMetadata(options, generateJobId);
+    // Validate the generated job metadata
+    const validated = JobMetadataSchema.parse(job);
+    const filePath = getJobFilePath(jobsDir, validated.id);
+    try {
+        await atomicWriteYaml(filePath, validated);
+    }
+    catch (error) {
+        throw new StateFileError(`Failed to create job file: ${error.message}`, filePath, "write", error);
+    }
+    return validated;
+}
+/**
+ * Update an existing job's metadata
+ *
+ * Uses atomic writes to prevent corruption. Automatically calculates
+ * duration_seconds when finished_at is set.
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - The job ID to update
+ * @param updates - Partial updates to apply
+ * @returns The updated job metadata
+ * @throws StateFileError if the file cannot be read or written
+ *
+ * @example
+ * ```typescript
+ * const job = await updateJob('/path/to/.herdctl/jobs', 'job-2024-01-15-abc123', {
+ *   status: 'completed',
+ *   exit_reason: 'success',
+ *   finished_at: new Date().toISOString(),
+ *   summary: 'Fixed the auth bug'
+ * });
+ * ```
+ */
+export async function updateJob(jobsDir, jobId, updates) {
+    const filePath = getJobFilePath(jobsDir, jobId);
+    // Read existing job
+    const result = await safeReadYaml(filePath);
+    if (!result.success) {
+        throw new StateFileError(`Failed to read job file for update: ${result.error.message}`, filePath, "read", result.error);
+    }
+    // Parse and validate existing job
+    const parseResult = JobMetadataSchema.safeParse(result.data);
+    if (!parseResult.success) {
+        throw new StateFileError(`Job file is corrupted: ${parseResult.error.message}`, filePath, "read");
+    }
+    const existingJob = parseResult.data;
+    // Apply updates
+    const updatedJob = {
+        ...existingJob,
+        ...updates,
+    };
+    // Auto-calculate duration if finished_at is being set
+    if (updates.finished_at && !updates.duration_seconds) {
+        updatedJob.duration_seconds = calculateDuration(existingJob.started_at, updates.finished_at);
+    }
+    // Validate the updated job
+    const validated = JobMetadataSchema.parse(updatedJob);
+    // Write atomically
+    try {
+        await atomicWriteYaml(filePath, validated);
+    }
+    catch (error) {
+        throw new StateFileError(`Failed to update job file: ${error.message}`, filePath, "write", error);
+    }
+    return validated;
+}
+/**
+ * Get a job by its ID
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - The job ID to retrieve
+ * @returns The job metadata, or null if not found
+ * @throws StateFileError if the file exists but cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const job = await getJob('/path/to/.herdctl/jobs', 'job-2024-01-15-abc123');
+ * if (job) {
+ *   console.log(job.status); // 'running'
+ * }
+ * ```
+ */
+export async function getJob(jobsDir, jobId, options = {}) {
+    const { logger = console } = options;
+    const filePath = getJobFilePath(jobsDir, jobId);
+    const result = await safeReadYaml(filePath);
+    if (!result.success) {
+        // File not found is not an error - return null
+        if (result.error.code === "ENOENT") {
+            return null;
+        }
+        throw new StateFileError(`Failed to read job file: ${result.error.message}`, filePath, "read", result.error);
+    }
+    // Parse and validate
+    const parseResult = JobMetadataSchema.safeParse(result.data);
+    if (!parseResult.success) {
+        logger.warn(`Corrupted job file ${filePath}: ${parseResult.error.message}. Skipping.`);
+        return null;
+    }
+    return parseResult.data;
+}
+/**
+ * List all jobs, optionally filtered
+ *
+ * Supports filtering by agent, status, and date range. Returns jobs
+ * sorted by started_at in descending order (most recent first).
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param filter - Optional filter criteria
+ * @param options - Optional operation options
+ * @returns List of matching jobs and count of parse errors
+ *
+ * @example
+ * ```typescript
+ * // List all jobs for an agent
+ * const { jobs } = await listJobs('/path/to/.herdctl/jobs', {
+ *   agent: 'my-agent'
+ * });
+ *
+ * // List failed jobs from the last 24 hours
+ * const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
+ * const { jobs } = await listJobs('/path/to/.herdctl/jobs', {
+ *   status: 'failed',
+ *   startedAfter: yesterday
+ * });
+ * ```
+ */
+export async function listJobs(jobsDir, filter = {}, options = {}) {
+    const { logger = console } = options;
+    // Read directory
+    let files;
+    try {
+        files = await readdir(jobsDir);
+    }
+    catch (error) {
+        // Directory doesn't exist - return empty list
+        if (error.code === "ENOENT") {
+            return { jobs: [], errors: 0 };
+        }
+        throw new StateFileError(`Failed to read jobs directory: ${error.message}`, jobsDir, "read", error);
+    }
+    // Filter to job YAML files
+    const jobFiles = files.filter((f) => f.startsWith("job-") && f.endsWith(".yaml"));
+    const jobs = [];
+    let errors = 0;
+    // Parse date filters once
+    const startedAfter = filter.startedAfter
+        ? toDate(filter.startedAfter)
+        : undefined;
+    const startedBefore = filter.startedBefore
+        ? toDate(filter.startedBefore)
+        : undefined;
+    // Read and filter each job
+    for (const file of jobFiles) {
+        const filePath = join(jobsDir, file);
+        const result = await safeReadYaml(filePath);
+        if (!result.success) {
+            logger.warn(`Failed to read job file ${filePath}: ${result.error.message}`);
+            errors++;
+            continue;
+        }
+        const parseResult = JobMetadataSchema.safeParse(result.data);
+        if (!parseResult.success) {
+            logger.warn(`Corrupted job file ${filePath}: ${parseResult.error.message}`);
+            errors++;
+            continue;
+        }
+        const job = parseResult.data;
+        // Apply filters
+        if (filter.agent && job.agent !== filter.agent) {
+            continue;
+        }
+        if (filter.status && job.status !== filter.status) {
+            continue;
+        }
+        if (startedAfter) {
+            const jobDate = new Date(job.started_at);
+            if (jobDate < startedAfter) {
+                continue;
+            }
+        }
+        if (startedBefore) {
+            const jobDate = new Date(job.started_at);
+            if (jobDate > startedBefore) {
+                continue;
+            }
+        }
+        jobs.push(job);
+    }
+    // Sort by started_at descending (most recent first)
+    jobs.sort((a, b) => {
+        const dateA = new Date(a.started_at).getTime();
+        const dateB = new Date(b.started_at).getTime();
+        return dateB - dateA;
+    });
+    return { jobs, errors };
+}
+/**
+ * Delete a job's metadata file
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - The job ID to delete
+ * @returns true if deleted, false if not found
+ *
+ * @example
+ * ```typescript
+ * const deleted = await deleteJob('/path/to/.herdctl/jobs', 'job-2024-01-15-abc123');
+ * if (deleted) {
+ *   console.log('Job deleted');
+ * }
+ * ```
+ */
+export async function deleteJob(jobsDir, jobId) {
+    const { unlink } = await import("node:fs/promises");
+    const filePath = getJobFilePath(jobsDir, jobId);
+    try {
+        await unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw new StateFileError(`Failed to delete job file: ${error.message}`, filePath, "write", error);
+    }
+}
+//# sourceMappingURL=job-metadata.js.map

package/dist/state/job-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-metadata.js","sourceRoot":"","sources":["../../src/state/job-metadata.ts"],"names":[],"mappings":"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"}

package/dist/state/job-output.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Job output logging operations
+ *
+ * Provides functions for streaming job output to JSONL files.
+ * Supports real-time monitoring with immediate writes (no buffering).
+ *
+ * Output files are stored at: .herdctl/jobs/job-<id>.jsonl
+ */
+import { type JobOutputMessage, type JobOutputInput } from "./schemas/job-output.js";
+/**
+ * Logger interface for job output operations
+ */
+export interface JobOutputLogger {
+    warn: (message: string) => void;
+}
+/**
+ * Options for job output operations
+ */
+export interface JobOutputOptions {
+    /** Logger for warnings and errors */
+    logger?: JobOutputLogger;
+}
+/**
+ * Options for reading job output
+ */
+export interface ReadJobOutputOptions extends JobOutputOptions {
+    /** Whether to skip invalid lines instead of failing */
+    skipInvalidLines?: boolean;
+}
+/**
+ * Get the path to a job's output file
+ *
+ * @param jobsDir - Path to the jobs directory (.herdctl/jobs)
+ * @param jobId - Job ID (e.g., job-2024-01-15-abc123)
+ * @returns Path to the JSONL output file
+ */
+export declare function getJobOutputPath(jobsDir: string, jobId: string): string;
+/**
+ * Append a single message to a job's output log
+ *
+ * Writes immediately to disk for real-time monitoring (no buffering).
+ * Uses append mode which is safe for concurrent appends.
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - Job ID
+ * @param message - Message to append (timestamp added automatically)
+ * @throws StateFileError if write fails or message is invalid
+ *
+ * @example
+ * ```typescript
+ * await appendJobOutput(jobsDir, jobId, {
+ *   type: "assistant",
+ *   content: "Hello, world!"
+ * });
+ * ```
+ */
+export declare function appendJobOutput(jobsDir: string, jobId: string, message: JobOutputInput): Promise<void>;
+/**
+ * Append multiple messages to a job's output log
+ *
+ * Writes all messages immediately in sequence.
+ * Each message is validated before writing begins.
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - Job ID
+ * @param messages - Messages to append (timestamps added automatically)
+ * @throws StateFileError if write fails or any message is invalid
+ *
+ * @example
+ * ```typescript
+ * await appendJobOutputBatch(jobsDir, jobId, [
+ *   { type: "tool_use", tool_name: "read_file", input: { path: "/etc/hosts" } },
+ *   { type: "tool_result", result: "127.0.0.1 localhost", success: true }
+ * ]);
+ * ```
+ */
+export declare function appendJobOutputBatch(jobsDir: string, jobId: string, messages: JobOutputInput[]): Promise<void>;
+/**
+ * Read job output as an async generator for streaming reads
+ *
+ * Yields messages one at a time, allowing for memory-efficient
+ * processing of large output files.
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - Job ID
+ * @param options - Read options
+ * @yields JobOutputMessage objects
+ * @throws StateFileError if file cannot be read (except ENOENT which yields nothing)
+ *
+ * @example
+ * ```typescript
+ * for await (const message of readJobOutput(jobsDir, jobId)) {
+ *   console.log(`[${message.type}] ${message.timestamp}`);
+ * }
+ * ```
+ */
+export declare function readJobOutput(jobsDir: string, jobId: string, options?: ReadJobOutputOptions): AsyncGenerator<JobOutputMessage, void, undefined>;
+/**
+ * Read all job output messages into an array
+ *
+ * Convenience function that collects all messages from readJobOutput.
+ * For large files, prefer using readJobOutput directly as a generator.
+ *
+ * @param jobsDir - Path to the jobs directory
+ * @param jobId - Job ID
+ * @param options - Read options
+ * @returns Array of all job output messages
+ *
+ * @example
+ * ```typescript
+ * const messages = await readJobOutputAll(jobsDir, jobId);
+ * console.log(`Total messages: ${messages.length}`);
+ * ```
+ */
+export declare function readJobOutputAll(jobsDir: string, jobId: string, options?: ReadJobOutputOptions): Promise<JobOutputMessage[]>;
+//# sourceMappingURL=job-output.d.ts.map

package/dist/state/job-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-output.d.ts","sourceRoot":"","sources":["../../src/state/job-output.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAGpB,MAAM,yBAAyB,CAAC;AAMjC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvE;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,cAAc,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuB,aAAa,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,cAAc,CAAC,gBAAgB,EAAE,IAAI,EAAE,SAAS,CAAC,CAgFnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAM7B"}