hankweave 0.5.7 → 0.6.2

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;
+}

package/dist/claude-runtime-extractor.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Claude Runtime Extractor
+ *
+ * This module handles the extraction of bundled Claude Agent SDK files
+ * at runtime for standalone executables. When compiled with Bun, the CLI
+ * files are embedded in the executable and need to be extracted to disk
+ * before they can be spawned as subprocesses.
+ *
+ * The extraction is done to a versioned directory to avoid re-extraction
+ * on every run and to handle SDK updates cleanly.
+ *
+ * Build Process:
+ * The build script (scripts/build-executable.ts) embeds the SDK files using:
+ *   bun build --compile --embed node_modules/@anthropic-ai/claude-agent-sdk/cli.js ...
+ *
+ * At runtime, these embedded files are accessible via Bun.file() using their
+ * original paths.
+ */
+export declare const CLAUDE_SDK_VERSION = "0.1.70";
+/**
+ * Get the extraction directory path.
+ * Uses ~/.hankweave/claude-sdk/<version>/ by default.
+ */
+export declare function getExtractionDir(): string;
+/**
+ * Get the path to the extracted cli.js file.
+ */
+export declare function getExtractedCliPath(): string;
+/**
+ * Check if embedded files are available (async check).
+ * This actually tries to access an embedded file to verify.
+ */
+export declare function hasEmbeddedFiles(): Promise<boolean>;
+/**
+ * Check if extraction is needed.
+ * Returns true if the files don't exist or are outdated.
+ */
+export declare function needsExtraction(): boolean;
+/**
+ * Extract embedded Claude SDK files to disk.
+ *
+ * This function reads files that were embedded during compilation using Bun's
+ * --embed flag, then extracts them to a versioned directory on first run.
+ *
+ * The embedded files are accessed using their original paths that were
+ * specified during build (e.g., "node_modules/@anthropic-ai/claude-agent-sdk/cli.js").
+ *
+ * Files extracted:
+ * - cli.js - The main Claude Code CLI
+ * - resvg.wasm - SVG rendering WASM module
+ * - tree-sitter.wasm - Syntax parsing WASM module
+ * - tree-sitter-bash.wasm - Bash syntax WASM module
+ * - vendor/ripgrep/<platform>/ - Platform-specific ripgrep binaries
+ */
+export declare function extractClaudeSdkFiles(): Promise<string>;
+/**
+ * Ensure Claude SDK files are available, extracting if necessary.
+ *
+ * @deprecated Use ClaudeAgentSDKManager.ensureSdkAvailable() instead.
+ * This function is kept for backward compatibility.
+ *
+ * @returns SDK info object with path, version, and cached status
+ * @throws Error if extraction fails or extracted file doesn't exist
+ */
+export declare function ensureClaudeSdkAvailable(): Promise<{
+    path: string | null;
+    version: string;
+    cached: boolean;
+}>;
+/**
+ * Validate the extracted cli.js works by running a simple command.
+ */
+export declare function validateExtractedCli(cliPath: string): Promise<boolean>;

package/dist/codex-runtime-extractor.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Codex Runtime Extractor
+ *
+ * This module handles the detection and extraction of Codex binaries
+ * for different execution contexts. The @openai/codex-sdk package ships
+ * with platform-specific binaries in its vendor directory.
+ *
+ * Execution contexts:
+ * 1. Source/NPM mode: Use binary from node_modules/@openai/codex-sdk/vendor/
+ * 2. Compiled executable: Extract embedded binary to ~/.hankweave/codex-sdk/
+ *
+ * The extraction is done to a versioned directory to avoid re-extraction
+ * on every run and to handle SDK updates cleanly.
+ */
+export declare const CODEX_SDK_VERSION = "0.104.0";
+/**
+ * Platform identifier matching @openai/codex-sdk vendor directory structure
+ */
+type CodexPlatform = "aarch64-apple-darwin" | "x86_64-apple-darwin" | "aarch64-unknown-linux-musl" | "x86_64-unknown-linux-musl" | "aarch64-pc-windows-msvc" | "x86_64-pc-windows-msvc";
+/**
+ * Determine platform identifier matching codex-sdk structure.
+ *
+ * @param target - Optional build target string (e.g., "linux-x64", "darwin-arm64").
+ *                 If not provided, uses current platform.
+ * @throws Error if platform is unsupported
+ */
+export declare function getCodexPlatform(target?: string): CodexPlatform;
+/**
+ * Get the codex binary filename for the current platform.
+ */
+export declare function getCodexBinaryName(): string;
+/**
+ * Get the extraction directory path for codex binaries.
+ * Uses ~/.hankweave/codex-sdk/<version>/ by default.
+ */
+export declare function getCodexExtractionDir(): string;
+/**
+ * Get the path to the extracted codex binary.
+ */
+export declare function getExtractedCodexPath(): string;
+/**
+ * Ensure a binary file has execute permissions on Unix.
+ * No-op on Windows. Deno's npm cache may not preserve +x bits.
+ */
+export declare function ensureExecutable(binaryPath: string): void;
+/**
+ * Locate codex binary using import.meta.resolve.
+ *
+ * This is a universal fallback that works across all runtimes (Deno, Node.js 20.6+, Bun).
+ * It asks the runtime's own module resolver where @openai/codex-sdk (or the platform-specific
+ * package) lives, then navigates from the resolved entry point to the vendor binary.
+ *
+ * This is critical for Deno, which stores npm packages in a global cache rather than
+ * in a project-local node_modules/ directory.
+ *
+ * @returns Path to codex binary, or null if not found
+ */
+export declare function locateCodexViaImportResolve(): string | null;
+/**
+ * Locate codex binary in node_modules (npm/npx mode).
+ * Searches up the directory tree from the module's location to find node_modules/@openai/codex-sdk.
+ *
+ * This works in both normal installs and npx scenarios:
+ * - Normal install: module is in project/node_modules/@southbridgeai/hankweave
+ * - NPX: module is in ~/.npm/_npx/.../node_modules/@southbridgeai/hankweave
+ * In both cases, @openai/codex-sdk will be found by walking up from the module location.
+ *
+ * @returns Path to codex binary, or null if not found
+ */
+export declare function locateCodexInNodeModules(): string | null;
+/**
+ * Check if extraction is needed.
+ * Returns true if the binary doesn't exist or is outdated.
+ */
+export declare function needsCodexExtraction(): boolean;
+/**
+ * Extract embedded codex binary to disk.
+ *
+ * This function reads the binary that was embedded during compilation using Bun's
+ * --embed flag, then extracts it to a versioned directory on first run.
+ *
+ * @returns Path to extracted codex binary
+ * @throws Error if extraction fails
+ */
+export declare function extractCodexBinary(): Promise<string>;
+/**
+ * Ensure codex binary is available, extracting if necessary.
+ *
+ * This is the main entry point for getting a codex binary path.
+ * Handles both npm/npx mode (use node_modules) and binary mode (extract embedded).
+ *
+ * @returns Path to codex binary
+ * @throws Error if binary cannot be found or extracted
+ */
+export declare function ensureCodexAvailable(): Promise<{
+    path: string;
+    version: string;
+    cached: boolean;
+}>;
+/**
+ * Validate that the codex binary exists and is executable.
+ *
+ * @param codexPath - Path to codex binary to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function validateCodexBinary(codexPath: string): boolean;
+export {};

package/dist/codon-runner.d.ts

@@ -0,0 +1,278 @@
+import type { Budget } from "./budget.js";
+import type { LlmProviderRegistry } from "./llm/llm-provider-registry.js";
+import type { ModelInfo } from "./llm/models-dev-schema.js";
+import type { StateManager } from "./state-manager.js";
+import { TypedEventEmitter } from "./typed-event-emitter.js";
+import type { CodonId, RunId, SessionId } from "./types/branded-types.js";
+import type { AssistantMessage, ResultMessage, SystemMessage, UserMessage } from "./types/claude-session-schema.js";
+import type { Codon, ShimSelfTestResult, TokenUsage } from "./types/types.js";
+import { type Logger } from "./utils.js";
+/**
+ * Information about an extension, passed to the onExtension callback
+ */
+export interface ExtensionInfo {
+    extensionNumber: number;
+    sessionId: SessionId;
+    previousExitCode: number;
+    wasContextExceeded: boolean;
+    /** The prompt being used for this extension */
+    exhaustWithPrompt: string;
+}
+/**
+ * Events emitted by CodonRunner during execution
+ */
+export interface CodonRunnerEvents extends Record<string, unknown[]> {
+    exit: [code: number, contextExceeded: boolean, extensionCount: number];
+    error: [error: Error];
+    systemMessage: [msg: SystemMessage];
+    assistantMessage: [msg: AssistantMessage];
+    userMessage: [msg: UserMessage];
+    resultMessage: [msg: ResultMessage];
+    costIncremented: [
+        data: {
+            codonId: string;
+            tokens: TokenUsage;
+            totalCost: number;
+            modelId?: string;
+        }
+    ];
+    finalCostSet: [
+        data: {
+            codonId: string;
+            tokens: TokenUsage;
+            totalCost: number;
+            modelUsage?: unknown;
+            modelId?: string;
+        }
+    ];
+    stdout: [data: string];
+    stderr: [data: string];
+}
+/**
+ * Extension configuration for codons that support context exhaustion
+ */
+export interface ExtensionConfig {
+    /** Prompt to send for each extension */
+    exhaustWithPrompt: string;
+    /** Maximum number of extensions before forcing completion (default: 100) */
+    maxExtensions: number;
+}
+/**
+ * Base configuration shared by all CodonRunner instances
+ */
+interface BaseCodonRunnerConfig {
+    codon: Codon;
+    codonId: CodonId;
+    runId: RunId;
+    stateManager: StateManager;
+    executionPath: string;
+    agentRootPath: string;
+    logger: Logger;
+    llmRegistry: LlmProviderRegistry;
+    logParsingInterval?: number;
+    anthropicBaseUrl?: string;
+    logPath: string;
+    globalSystemPrompt?: string | null;
+    shimIdleTimeout?: number;
+    budget: Budget;
+    /** If provided, use ReplayProcessManager instead of real process managers */
+    replayConfig?: {
+        /** Absolute path to the source JSONL log file to replay */
+        sourceLogPath: string;
+        /** Delay in ms between writing lines (default: 5) */
+        replaySpeed?: number;
+    };
+}
+/**
+ * Configuration for a CodonRunner without extension support
+ */
+interface CodonRunnerConfigWithoutExtension extends BaseCodonRunnerConfig {
+    extensionConfig?: undefined;
+    shouldInterrupt?: undefined;
+    onExtension?: undefined;
+}
+/**
+ * Configuration for a CodonRunner with extension support.
+ * When extensions are enabled, interrupt check and event callbacks are required.
+ */
+interface CodonRunnerConfigWithExtension extends BaseCodonRunnerConfig {
+    /** Extension configuration - enables automatic re-running until context exhaustion */
+    extensionConfig: ExtensionConfig;
+    /** Required: Check if user requested skip/force-stop */
+    shouldInterrupt: () => boolean;
+    /** Required: Called on each extension to emit events and update state */
+    onExtension: (info: ExtensionInfo) => void;
+}
+/**
+ * Configuration for creating a CodonRunner.
+ *
+ * Uses discriminated union: when extensionConfig is provided,
+ * shouldInterrupt and onExtension become required.
+ */
+export type CodonRunnerConfig = CodonRunnerConfigWithoutExtension | CodonRunnerConfigWithExtension;
+/**
+ * CodonRunner encapsulates all logic needed to execute a single codon.
+ *
+ * Responsibilities:
+ * - Create and manage ClaudeLogParser for this codon
+ * - Create and manage ShimProcessManager for this codon
+ * - Forward events from parser and process manager
+ * - Provide clean lifecycle: construct → run → cleanup
+ *
+ * The runner owns both the LogParser and ProcessManager instances,
+ * ensuring they are created together, used together, and cleaned up together.
+ */
+/**
+ * Failure reasons that prevent extension
+ */
+type FailureReason = {
+    type: "timeout";
+    retriable: boolean;
+} | {
+    type: "rate-limit";
+    retriable: boolean;
+} | {
+    type: "api-error";
+    retriable: boolean;
+} | {
+    type: "unknown";
+    retriable: boolean;
+};
+/**
+ * Determines whether a codon should extend based on exit conditions.
+ * Pure function for unit testing.
+ *
+ * Extension triggers when ALL conditions are met:
+ * - Extension config provided
+ * - Not interrupted (skip/force-stop)
+ * - Under max extensions
+ * - Exit code 0
+ * - Result message received
+ * - No failure reason
+ * - Context not yet exceeded
+ */
+export declare function shouldExtendCodon(params: {
+    exitCode: number;
+    resultMessageReceived: boolean;
+    isContextExceeded: boolean;
+    extensionConfig: ExtensionConfig | undefined;
+    extensionCount: number;
+    isInterrupted: boolean;
+    failureReason: FailureReason | undefined;
+    isBudgetExceeded?: boolean;
+}): boolean;
+export declare class CodonRunner extends TypedEventEmitter<CodonRunnerEvents> {
+    private readonly config;
+    private readonly logParser;
+    private readonly costTracker;
+    private processManager;
+    private readonly logPath;
+    private readonly budgetExceededListener;
+    private isCleanedUp;
+    private successResultReceived;
+    private extensionCount;
+    private resultMessageReceived;
+    private failureReason;
+    private currentSessionId;
+    constructor(config: CodonRunnerConfig);
+    /**
+     * Check if a model can be run by CodonRunner.
+     *
+     * CodonRunner supports:
+     * - Anthropic models via ClaudeAgentSDKManager
+     * - Google models via ShimProcessManager (gemini shim)
+     * - OpenAI models via ShimProcessManager (codex shim)
+     *
+     * @param model - The ModelInfo to check
+     * @returns true if the model can be executed, false otherwise
+     */
+    static canRun(model: ModelInfo): boolean;
+    /**
+     * Run self-test for a model without creating a full CodonRunner instance.
+     * Useful for validation and testing where you only have model info.
+     *
+     * @param modelInfo - The model to test
+     * @param executionPath - Temporary execution path for the test
+     * @param logger - Logger instance for recording test progress
+     * @param anthropicBaseUrl - Optional custom Anthropic API base URL
+     * @returns Promise resolving to self-test results
+     */
+    static runSelfTestForModel(modelInfo: ModelInfo, executionPath: string, logger: Logger, anthropicBaseUrl?: string): Promise<ShimSelfTestResult>;
+    /**
+     * Create ClaudeLogParser for this codon with event forwarding
+     */
+    private createLogParser;
+    /**
+     * Create process manager (SDK, Shim, or Replay) based on model type with event forwarding
+     */
+    private createProcessManager;
+    /**
+     * Handle process exit - implements internal extension loop.
+     *
+     * When the process exits, this checks if we should extend:
+     * - If yes: calls onExtension callback, resets state, and re-runs
+     * - If no: emits final "exit" event with extensionCount
+     */
+    private handleProcessExit;
+    /**
+     * Perform an extension: notify callback, reset state, re-run with prompt override.
+     *
+     * Parameters are passed explicitly to avoid type narrowing issues with class properties.
+     */
+    private performExtension;
+    /**
+     * Spawn the underlying process manager using a unified adapter.
+     * ShimProcessManager requires a runtime command array; SDK/Replay do not.
+     */
+    private spawnCodonProcess;
+    /**
+     * Internal method to run an extension (resume session with exhaustion prompt).
+     *
+     * Uses the same spawn() method as initial run, but with exhaustionPrompt option.
+     * This activates exhaustion mode: appends to log, forces resume.
+     */
+    private runExtension;
+    /**
+     * Start executing the codon.
+     *
+     * If extensionConfig is provided, the runner will automatically extend
+     * until context is exhausted or maxExtensions is reached.
+     *
+     * @param previousSessionId - Optional session ID to continue from
+     */
+    run(previousSessionId?: SessionId): Promise<void>;
+    /**
+     * Get the current extension count.
+     * Returns 0 if no extensions have occurred.
+     */
+    getExtensionCount(): number;
+    /**
+     * Kill the running process gracefully (SIGTERM with wait and SIGKILL escalation).
+     */
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Force-kill the running process immediately (SIGKILL for shims, abort for SDK).
+     * Used by forceShutdown() when the user presses q/Ctrl+C a second time.
+     */
+    forceKill(): Promise<void>;
+    /**
+     * Check if the process is currently running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the process ID (if running)
+     */
+    getPid(): number | undefined;
+    /**
+     * Get the prompt frontmatter (if any was parsed from the prompt file)
+     */
+    getPromptFrontmatter(): import("./prompt-frontmatter.js").PromptFrontmatter | undefined;
+    /**
+     * Clean up all resources owned by this runner
+     *
+     * This should be called when the codon execution is complete
+     * (whether successful, failed, or skipped)
+     */
+    cleanup(): Promise<void>;
+}
+export {};

package/dist/config-validation/model-validator.d.ts

@@ -0,0 +1,16 @@
+import type { LlmProviderRegistry } from "../llm/llm-provider-registry.js";
+import type { ModelInfo } from "../llm/models-dev-schema.js";
+/**
+ * Result of model validation
+ */
+export interface ModelValidationResult {
+    /** Whether the model is valid and can be used */
+    valid: boolean;
+    /** The resolved ModelInfo if validation succeeded */
+    modelInfo?: ModelInfo;
+    /** Human-readable reason if validation failed */
+    reason?: string;
+    /** Type of match that was found (if any) */
+    matchType?: "exact" | "exact-with-inferred-provider" | "fuzzy";
+}
+export declare function validateModel(model: string, registry: LlmProviderRegistry, providerId?: string): ModelValidationResult;