hankweave 0.6.1 → 0.6.2

package/dist/base-process-manager.d.ts

@@ -0,0 +1,30 @@
+import type { ClaudeLogParser } from "./claude-log-parser.js";
+import { type ProcessEvents, TypedEventEmitter } from "./typed-event-emitter.js";
+import type { Logger } from "./utils.js";
+/**
+ * Base class for process managers that provides shared context-exceeded detection.
+ *
+ * All process managers (ClaudeAgentSDKManager, ShimProcessManager, ReplayProcessManager)
+ * need to detect context-exceeded conditions from parsed log messages before emitting
+ * the exit event. This base class centralizes that logic.
+ *
+ * Note: No abstract method signatures — the three managers have different spawn()
+ * signatures, and CodonRunner uses instanceof narrowing. The union type in CodonRunner
+ * remains unchanged.
+ */
+export declare class BaseProcessManager extends TypedEventEmitter<ProcessEvents> {
+    protected logger: Logger;
+    protected logParser: ClaudeLogParser;
+    constructor(logger: Logger, logParser: ClaudeLogParser);
+    /**
+     * Flush the log parser and scan all parsed messages for context-exceeded indicators.
+     * Detects both synthetic assistant messages (output token exceeded) and
+     * result messages with is_error.
+     */
+    protected detectContextExceeded(): boolean;
+    /**
+     * Emit the "exit" event with automatic context-exceeded detection.
+     * Ensures every exit path consistently detects context exhaustion.
+     */
+    protected emitExit(exitCode: number): void;
+}

package/dist/budget.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Unified budget module.
+ *
+ * Contains:
+ * - BudgetTracker: per-codon limit enforcement (cost, duration, output tokens)
+ * - resolveCodonBudget: allocation logic (shared, proportional, proportional-strict)
+ * - Budget: run-level facade that ties everything together
+ *
+ * Shared types (BudgetLimits, BudgetExceededInfo, etc.) live in types/budget-types.ts
+ * and are re-exported here for convenience.
+ */
+import type { CostTrackerEvents } from "./cost-tracker.js";
+import type { ExecutionCodonEntry } from "./execution-planner.js";
+import { TypedEventEmitter } from "./typed-event-emitter.js";
+import type { CodonId } from "./types/branded-types.js";
+import { type AllocationMode, type BudgetExceededInfo, BudgetLimits, type BudgetSummaryData, type OnExceededPolicy } from "./types/budget-types.js";
+import { type Run } from "./types/state-types.js";
+import type { Logger } from "./utils.js";
+export type { AllocationMode, BudgetCurrency, BudgetExceededData, BudgetExceededInfo, BudgetLimitsOptions, BudgetSummaryData, CodonBudgetSummaryRow, OnExceededPolicy, } from "./types/budget-types.js";
+export { BUDGET_CURRENCIES, BudgetLimits } from "./types/budget-types.js";
+export interface BudgetTrackerEvents extends Record<string, unknown[]> {
+    exceeded: [info: BudgetExceededInfo];
+}
+/**
+ * Pure logic class that tracks budget consumption against limits.
+ * Emits `exceeded` event (at most once) when any currency goes over its limit.
+ * No I/O, no runtime dependencies — designed for unit testing.
+ */
+export declare class BudgetTracker extends TypedEventEmitter<BudgetTrackerEvents> {
+    private readonly limits;
+    private costUsed;
+    private outputTokensUsed;
+    private contextTokensHighWaterMark;
+    private readonly startTime;
+    private exceededInfo;
+    constructor(limits: BudgetLimits);
+    /** Accumulate cost and check against limit. */
+    addCost(delta: number): void;
+    /** Accumulate output tokens and check against limit. */
+    addOutputTokens(delta: number): void;
+    /**
+     * Update the context token high-water mark and check against limit.
+     * Called with per-turn inputTokens + outputTokens (NOT cumulative sum).
+     * Tracks the peak context window fill level across all turns.
+     */
+    updateContextTokens(inputTokensThisTurn: number, outputTokensThisTurn: number): void;
+    /** Check elapsed wall-clock time against duration limit. */
+    checkTime(): void;
+    /** Has any budget limit been exceeded? */
+    isExceeded(): boolean;
+    /** Get info about which limit was exceeded, if any. */
+    getExceededInfo(): BudgetExceededInfo | undefined;
+    /** Remaining cost budget, or undefined if no cost limit. */
+    getRemainingCost(): number | undefined;
+    /** Current consumption state. */
+    getState(): {
+        costUsed: number;
+        outputTokensUsed: number;
+        contextTokensHighWaterMark: number;
+        elapsedSeconds: number;
+    };
+    /** Whether any limits are configured. */
+    hasLimits(): boolean;
+    private setExceeded;
+}
+export interface CodonBudgetConfig {
+    maxDollars?: number;
+    maxTimeSeconds?: number;
+    maxOutputTokens?: number;
+    maxContextTokens?: number;
+    onExceeded?: OnExceededPolicy;
+}
+export type RemainingCodonInfo = Pick<CodonBudgetConfig, "maxDollars"> & {
+    /** Config-level ID, used to look up in parent's shares map. */
+    codonConfigId?: string;
+};
+export interface ResolveCodonBudgetParams {
+    codon: CodonBudgetConfig;
+    /** Codons that haven't started yet (excluding the current codon). */
+    remainingCodons: RemainingCodonInfo[];
+    /** Effective global budget (min of runtime and hank maxDollars). */
+    globalMaxDollars?: number;
+    /** Total cost already spent across completed/failed codons. */
+    alreadySpent: number;
+    /** Allocation mode from the parent container's budget config. Default: "shared". */
+    allocationMode?: AllocationMode;
+    /** Share map from parent's budget config: child config ID → fraction (0-1). */
+    shares?: Record<string, number>;
+    /** The codon's config-level ID (used to look up in shares map). */
+    codonConfigId?: string;
+    /**
+     * For proportional-strict mode: the amount of budget "consumed" by completed codons
+     * using strict accounting (max of share amount and actual spend per codon).
+     * If undefined, falls back to alreadySpent.
+     */
+    strictAlreadyConsumed?: number;
+    /**
+     * Remaining wall-clock seconds from the hank-level time budget.
+     * When set, the codon's effective duration = min(codon.maxTimeSeconds, remainingTimeSeconds).
+     */
+    remainingTimeSeconds?: number;
+    /** Container-level (hank/loop) onExceeded default. Codon-level overrides this. */
+    containerOnExceeded?: OnExceededPolicy;
+}
+/**
+ * Resolves effective budget limits for a single codon execution.
+ * Pure function — no I/O, no side effects.
+ *
+ * When a global budget exists, every codon gets a cost limit.
+ * Allocation mode determines how the budget is distributed among children.
+ */
+export declare function resolveCodonBudget(params: ResolveCodonBudgetParams): BudgetLimits;
+/**
+ * Budget configuration from the hank-level budget config.
+ */
+export interface BudgetConfig {
+    maxDollars?: number;
+    maxTimeSeconds?: number;
+    allocationMode?: AllocationMode;
+    shares?: Record<string, number>;
+    onExceeded?: OnExceededPolicy;
+}
+/**
+ * Interface for reporting budget telemetry events.
+ * Implemented by TelemetryCollector; injected into Budget to keep it decoupled.
+ */
+export interface BudgetTelemetryReporter {
+    reportBudgetSet(data: {
+        codonId: string;
+        limits: BudgetLimits;
+    }): void;
+    reportBudgetExceeded(data: {
+        codonId: string;
+        info: BudgetExceededInfo;
+    }): void;
+}
+export interface BudgetParams {
+    config: BudgetConfig;
+    executionPlan: ExecutionCodonEntry[];
+    logger: Logger;
+    /** For continuation runs: prior runs to hydrate spending from. */
+    priorRuns?: {
+        runs: Run[];
+        currentRunId: string;
+    };
+    /** Optional telemetry reporter for budget events. */
+    telemetry?: BudgetTelemetryReporter;
+}
+export interface BudgetEvents extends Record<string, unknown[]> {
+    exceeded: [data: {
+        codonId: string;
+        info: BudgetExceededInfo;
+    }];
+}
+/**
+ * Run-level budget facade.
+ *
+ * Encapsulates allocation logic (resolveCodonBudget), per-codon limit
+ * enforcement (BudgetTracker), run-level spending tracking, and retry
+ * cost accumulation behind a single interface.
+ *
+ * Created once per run by HankweaveRuntime. Both the runtime and
+ * CodonRunner interact with this class for all budget concerns.
+ *
+ * CostTracker and StateManager remain in CodonRunner — this class
+ * subscribes to CostTracker events for automatic limit enforcement.
+ */
+export declare class Budget extends TypedEventEmitter<BudgetEvents> {
+    private readonly budgetConfig;
+    private readonly logger;
+    private readonly telemetry?;
+    private executionPlan;
+    private hankStartTime;
+    private activeTrackers;
+    private activeTimers;
+    private resolvedLimits;
+    private exceededSnapshots;
+    private completedSpending;
+    private retryAccumulated;
+    private loopEffectiveBudgets;
+    private loopStartTimes;
+    private priorCodonSnapshots?;
+    constructor(params: BudgetParams);
+    /**
+     * Log a human-readable budget summary at startup so the server log captures
+     * the effective ceiling, allocation mode, and spending state.
+     */
+    private logStartupSummary;
+    /**
+     * Hydrate spending from prior runs on resume.
+     * Called after construction when this Budget belongs to a continuation run,
+     * so that allocation calculations account for money already spent.
+     */
+    seedCompletedSpending(priorSpending: Map<string, number>): void;
+    /**
+     * Compute and hydrate prior spending from historical runs.
+     * Iterates over all runs except the current one, aggregates codon costs,
+     * and seeds the completed spending map.
+     */
+    hydrateFromPriorRuns(runs: Run[], currentRunId: string): void;
+    /**
+     * Compute elapsed wall-clock time from prior runs and offset hankStartTime
+     * so that time budgets account for time already consumed.
+     */
+    hydrateTimeFromPriorRuns(runs: Run[], currentRunId: string): void;
+    /**
+     * Initialize budget tracking for a codon. Resolves effective limits,
+     * creates a BudgetTracker, and subscribes to CostTracker events for
+     * automatic limit enforcement.
+     */
+    trackCodon(codonId: CodonId | string, codon: {
+        id: string;
+        budget?: {
+            maxDollars?: number;
+            maxTimeSeconds?: number;
+            maxOutputTokens?: number;
+            maxContextTokens?: number;
+            onExceeded?: OnExceededPolicy;
+        };
+    }, costTracker: TypedEventEmitter<CostTrackerEvents>): void;
+    /**
+     * Record that a codon completed successfully. Updates spending records
+     * for subsequent allocation calculations.
+     */
+    completeCodon(codonId: CodonId | string, finalCost: number): void;
+    /**
+     * Record that a codon failed. Updates spending records.
+     */
+    failCodon(codonId: CodonId | string, partialCost: number): void;
+    /**
+     * Record that a codon was skipped (0 cost).
+     */
+    skipCodon(codonId: CodonId | string): void;
+    private clearWatchdog;
+    /**
+     * Has this codon's budget been exceeded?
+     */
+    isExceeded(codonId: string): boolean;
+    /**
+     * Get details about the budget breach, if any.
+     */
+    getExceededInfo(codonId: string): BudgetExceededInfo | undefined;
+    /**
+     * Get the effective budget limits resolved for a codon.
+     */
+    getEffectiveLimits(codonId: string): BudgetLimits;
+    /**
+     * Total cost spent across all completed/failed codons in this run.
+     */
+    getTotalSpent(): number;
+    /**
+     * Get exceeded snapshots (read-only) for all codons that hit their budget.
+     */
+    getExceededSnapshots(): ReadonlyMap<string, BudgetExceededInfo>;
+    /**
+     * Build the end-of-run budget summary from internal state + run codons.
+     * Returns null if no budget limits were configured.
+     */
+    getBudgetSummary(currentRun: Run): BudgetSummaryData | null;
+    /**
+     * Update the execution plan (e.g., after loop expansion adds new entries).
+     * Must be called before trackCodon() for newly expanded codons.
+     */
+    updateExecutionPlan(plan: ExecutionCodonEntry[]): void;
+    /**
+     * Accumulate cost from a failed retry attempt.
+     */
+    accumulateRetryCost(codonId: string, cost: number): void;
+    /**
+     * Get accumulated retry cost and clear it. Returns 0 if none.
+     */
+    getAndClearRetryCost(codonId: string): number;
+    /**
+     * Check whether a loop's budget has been exhausted (cost or time).
+     */
+    isLoopBudgetExceeded(loopId: string): boolean;
+    /**
+     * Total cost spent across all completed/failed codons within a specific loop.
+     */
+    getLoopSpent(loopId: string): number;
+    /**
+     * Compute total elapsed wall-clock time for prior codons within a specific loop.
+     * Uses codon startTime/endTime from the execution plan's completed spending entries.
+     */
+    private computePriorLoopElapsedMs;
+    /**
+     * Find a codon by ID in the prior runs data stored during hydration.
+     * Returns undefined if not found or if no prior runs exist.
+     */
+    private findCodonInPriorRuns;
+    /**
+     * Resolve budget limits for a codon scoped to the hank level (no loop).
+     */
+    private resolveHankScopedLimits;
+    /**
+     * Resolve budget limits for a codon scoped to its parent loop's budget.
+     */
+    private resolveLoopScopedLimits;
+    /**
+     * Compute the loop's effective budget by capping it against the hank's allocation.
+     */
+    private resolveAndStoreLoopEffectiveBudget;
+    /**
+     * Compute how much the hank allocated to a specific loop, based on the hank's allocation mode.
+     */
+    private computeHankAllocationForLoop;
+    /**
+     * Compute strict consumed amount for proportional-strict mode (hank-level scope).
+     */
+    private computeStrictConsumed;
+    /**
+     * Compute strict consumed amount for proportional-strict mode within a loop.
+     */
+    private computeStrictConsumedInLoop;
+}

package/dist/checkpoint-git.d.ts

@@ -0,0 +1,98 @@
+import { type Logger } from "./utils.js";
+/**
+ * Git operations for the checkpoint system.
+ * Handles the shadow git repository in .hankweave/checkpoints.
+ */
+export declare class CheckpointGit {
+    private executionPath;
+    private agentRootPath;
+    private checkpointPath;
+    private git;
+    private logger;
+    private trackedPatterns;
+    constructor(executionPath: string, agentRootPath: string, logger: Logger);
+    /**
+     * Migrate backup directories from legacy .git to .hankweavecheckpoints.
+     * Called conditionally when the main checkpoint needed migration.
+     */
+    private migrateBackupDirectories;
+    /**
+     * Initialize the shadow git repository
+     * @returns The initial commit SHA (either from new repo creation or existing repo HEAD)
+     */
+    initialize(): Promise<string | undefined>;
+    /**
+     * Check if repository is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the current branch name
+     * @returns The current branch name or undefined if not initialized
+     */
+    getCurrentBranch(): Promise<string | undefined>;
+    /**
+     * Add patterns to track
+     */
+    addPatterns(patterns: string[]): Promise<void>;
+    /**
+     * Clear all tracked patterns
+     */
+    clearPatterns(): void;
+    /**
+     * Get resolved files for all tracked patterns
+     */
+    private getCheckpointedFiles;
+    /**
+     * Create a checkpoint commit. If branch is specified, switch to that branch for the commit and then switch back to the original branch.
+     * @param message Commit message for the checkpoint
+     * @param options Optional parameters, including branch name
+     * @returns The commit SHA of the new checkpoint or null if commit failed
+     */
+    commit(message: string, options?: {
+        branch?: string;
+    }): Promise<string | null>;
+    /**
+     * Get the checkpoint repository path
+     */
+    getPath(): string;
+    /**
+     * Switch to a specific branch, creating it if it doesn't exist
+     */
+    switchToBranch(branchName: string): Promise<void>;
+    /**
+     * Create a new branch from a specific SHA and switch to it.
+     * This preserves the old branch's history (unlike git reset --hard).
+     * @param branchName Name for the new branch
+     * @param sha The commit SHA to start the branch from
+     */
+    createBranchFromSha(branchName: string, sha: string): Promise<void>;
+    /**
+     * Get all checkpoint SHAs from the repository
+     * @returns Set of all commit SHAs in the repository
+     */
+    getAllCheckpointShas(): Promise<Set<string>>;
+    /**
+     * Check if a specific commit SHA exists in the repository
+     * @param sha Full or partial SHA to check
+     * @returns true if the commit exists, false otherwise
+     */
+    commitExists(sha: string): Promise<boolean>;
+    /**
+     * Get all checkpoints with detailed information, ordered by time (newest first)
+     * @returns Array of checkpoint information ordered by timestamp
+     */
+    getAllCheckpoints(): Promise<Array<{
+        sha: string;
+        message: string;
+        timestamp: string;
+        branch: string;
+    }>>;
+    /**
+     * Reset to a specific checkpoint.
+     *
+     * IMPORTANT: This uses `git checkout` to a detached HEAD state instead of
+     * `git reset --hard`. This preserves the old branch's history so you can
+     * still access old checkpoints from previous timelines.
+     */
+    resetToCheckpoint(sha: string): Promise<void>;
+}

package/dist/claude-agent-sdk-manager.d.ts

@@ -0,0 +1,144 @@
+import { BaseProcessManager } from "./base-process-manager.js";
+import type { ClaudeLogParser } from "./claude-log-parser.js";
+import type { Codon, ShimSelfTestResult } from "./types/types.js";
+import type { Logger } from "./utils.js";
+/**
+ * Error thrown when Claude executable cannot be found.
+ * This allows callers to handle this specific case.
+ */
+export declare class ClaudeExecutableNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * Detect an installed Claude executable.
+ * Checks common installation locations and falls back to `which claude`.
+ *
+ * @returns Path to Claude executable, or null if not found
+ */
+export declare function detectClaudeExecutable(): string | null;
+/**
+ * Manages Claude Agent SDK lifecycle, mimicking the ClaudeProcessManager API.
+ * Handles log stream creation and converts SDK messages to JSONL format.
+ */
+export declare class ClaudeAgentSDKManager extends BaseProcessManager {
+    private executionPath;
+    private agentRootPath;
+    private anthropicBaseUrl?;
+    private globalSystemPrompt?;
+    private defaultShimIdleTimeout?;
+    private abortController;
+    private logStream;
+    private killed;
+    private sessionId;
+    private syntheticPid;
+    private queryPromise;
+    private promptBuilder;
+    constructor(executionPath: string, agentRootPath: string, logger: Logger, logParser: ClaudeLogParser, anthropicBaseUrl?: string | undefined, globalSystemPrompt?: string | null | undefined, defaultShimIdleTimeout?: number | undefined);
+    /** Frontmatter metadata from the prompt file (if any) */
+    get promptFrontmatter(): import("./prompt-frontmatter.js").PromptFrontmatter | undefined;
+    /**
+     * Ensure Claude SDK files are available, extracting if necessary.
+     *
+     * This static method should be called at application startup before creating
+     * any ClaudeAgentSDKManager instances. It handles:
+     * - Detecting if running from compiled executable or source
+     * - Extracting embedded SDK files for compiled mode
+     * - Verifying extracted files exist
+     * - Setting CLAUDE_PATH_TO_CLAUDE_EXECUTABLE environment variable
+     *
+     * @returns Path to cli.js if compiled (and sets env var), or null if running from source
+     * @throws Error if extraction fails or extracted file doesn't exist
+     */
+    static ensureSdkAvailable(): Promise<{
+        path: string | null;
+        version: string;
+        cached: boolean;
+    }>;
+    /**
+     * Spawn a Claude Agent SDK session for the given codon configuration.
+     * Sets up logging, environment, and message handling.
+     *
+     * This unified method handles both normal codon execution and exhaustion extensions.
+     * From Claude's perspective, both are identical: resume a session with a new prompt.
+     * The difference is only where the prompt comes from.
+     *
+     * @param codon - Codon configuration (not Loop - loops must be expanded first)
+     * @param sessionToResume - Session ID to resume (if any). When provided with exhaustionPrompt,
+     *                          always resumes regardless of codon.continuationMode.
+     * @param options - Optional spawn configuration
+     * @param options.logPath - Custom log file path (defaults to .hankweave/logs/)
+     * @param options.exhaustionPrompt - If provided, activates exhaustion mode: uses this prompt
+     *                                   instead of codon config, appends to log, forces resume.
+     */
+    spawn(codon: Codon, sessionToResume: string | null, options?: {
+        logPath?: string;
+        exhaustionPrompt?: string;
+    }): Promise<string>;
+    /**
+     * Build SDK options from codon configuration.
+     */
+    private buildSDKOptions;
+    /**
+     * Run the query and process messages.
+     */
+    private runQuery;
+    /**
+     * Extract detailed error information from the error and log file.
+     */
+    private extractErrorDetails;
+    /**
+     * Convert SDK message to JSONL format matching claude-session-schema.
+     * SDK messages already have the correct structure, so we mostly just filter out
+     * unwanted message types and handle edge cases.
+     */
+    private convertSDKMessageToJSONL;
+    /**
+     * Write a message to the log file.
+     */
+    private writeToLog;
+    /**
+     * Kill the Claude Agent SDK session gracefully.
+     * Aborts the query (which triggers SIGTERM on the child via the SDK's abort handler),
+     * then waits up to PROCESS_KILL_GRACE_MS for the query to actually complete.
+     */
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Force-kill the Claude Agent SDK session immediately.
+     * Sends abort (SIGTERM via SDK) without waiting for the child to exit.
+     * Used by forceShutdown() when the user presses q/Ctrl+C a second time.
+     *
+     * Note: We cannot send SIGKILL to the SDK's child process because the SDK
+     * does not expose the child PID. The abort sends SIGTERM; when our process
+     * exits immediately after, the SDK's process.on("exit") handler fires another
+     * SIGTERM as a belt-and-suspenders measure.
+     */
+    forceKill(): Promise<void>;
+    /**
+     * Clean up resources.
+     */
+    private cleanup;
+    /**
+     * Check if session is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get session ID.
+     */
+    getSessionId(): string | undefined;
+    /**
+     * Get synthetic PID (for compatibility with ClaudeProcessManager API).
+     * Note: This is not a real process ID since SDK runs in-process.
+     */
+    getPid(): number | undefined;
+    /**
+     * Close log stream explicitly (for external cleanup).
+     */
+    closeLogStream(): Promise<void>;
+    /**
+     * Run self-test to verify Claude Agent SDK environment setup.
+     * Checks for API authentication (API key or OAuth token) and SDK availability.
+     *
+     * @returns Promise resolving to self-test results
+     */
+    runSelfTest(): Promise<ShimSelfTestResult>;
+}

package/dist/claude-log-parser.d.ts

@@ -0,0 +1,63 @@
+import { type AssistantMessage, type ResultMessage, type SystemMessage, type UserMessage } from "./types/claude-session-schema.js";
+import type { Logger } from "./utils.js";
+/**
+ * Configuration options for Claude log parser.
+ */
+export interface ClaudeLogParserOptions {
+    /** Path to the Claude JSONL log file to parse */
+    logPath: string;
+    /** ID of the codon being parsed (for context) */
+    codonId: string;
+    /** Callback for system messages (init, info) */
+    onSystemMessage?: (msg: SystemMessage) => void;
+    /** Callback for assistant messages (Claude's responses) */
+    onAssistantMessage?: (msg: AssistantMessage) => void;
+    /** Callback for user messages (tool results) */
+    onUserMessage?: (msg: UserMessage) => void;
+    /** Callback for result messages (success/error) */
+    onResultMessage?: (msg: ResultMessage) => void;
+    /** How often to check for new log entries (milliseconds) */
+    parsingInterval: number;
+    /** Optional logger for diagnostic output */
+    logger?: Logger;
+}
+/**
+ * Real-time parser for Claude's JSON log output.
+ *
+ * Watches a log file and parses new lines as they're written,
+ * validating them against the Claude session schema and calling
+ * appropriate callbacks for each message type.
+ *
+ * Uses both file watching and periodic polling to ensure no
+ * messages are missed.
+ */
+export declare class ClaudeLogParser {
+    private options;
+    private buffer;
+    private lastPosition;
+    private logTimer?;
+    private isFirstParse;
+    constructor(options: ClaudeLogParserOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * Get all parsed messages from the log file.
+     * Re-parses the entire log file to collect all messages.
+     * Useful for analyzing the entire conversation at process completion.
+     */
+    getAllMessages(): Array<SystemMessage | AssistantMessage | UserMessage | ResultMessage>;
+    /**
+     * Force an immediate parse of the log file.
+     * Useful when we need to ensure all messages are processed before process termination.
+     */
+    parseNow(): void;
+    /**
+     * Parse the log file and return all parsed messages.
+     * Supports both incremental parsing (with buffer management) and full file parsing.
+     *
+     * @param options.noEmit - If true, don't fire callbacks (default: false)
+     * @param options.fullParse - If true, parse entire file from scratch (default: false)
+     */
+    private parseLogFile;
+    private parseLogLine;
+}