hankweave 0.5.7 → 0.6.2

package/dist/prompt-builder.d.ts

@@ -0,0 +1,75 @@
+import type { PromptFrontmatter } from "./prompt-frontmatter.js";
+import type { Codon } from "./types/types.js";
+import type { Logger } from "./utils.js";
+/**
+ * Handles all prompt-related functionality for process managers.
+ * Builds system prompts, user prompts, parses frontmatter, and applies template replacements.
+ */
+export declare class PromptBuilder {
+    private agentRootPath;
+    private logger;
+    private globalSystemPrompt?;
+    private lastFrontmatter?;
+    constructor(agentRootPath: string, logger: Logger, globalSystemPrompt?: string | null | undefined);
+    /**
+     * Build system prompt from global prompt and/or codon-specific prompt.
+     * Global prompt is prepended, then codon-specific prompt follows.
+     *
+     * @returns Combined system prompt with template replacements applied, or null if no prompts configured
+     */
+    buildSystemPrompt(codon: Codon): string | null;
+    /**
+     * Build prompt content from file or text.
+     * Parses and strips frontmatter from markdown files.
+     * Stores frontmatter metadata for later retrieval via getLastFrontmatter().
+     *
+     * @returns Prompt content with template replacements applied and optional frontmatter metadata
+     */
+    buildPromptContent(codon: Codon): {
+        content: string;
+        frontmatter?: PromptFrontmatter;
+    };
+    /**
+     * Get frontmatter metadata from the last built prompt.
+     * Returns undefined if no frontmatter was present or no prompt has been built yet.
+     */
+    getLastFrontmatter(): PromptFrontmatter | undefined;
+    /**
+     * Process prompt variables in a string (for exhaustion/extension prompts).
+     * Replaces template variables: <%PROJECT_DIR%>, <%EXECUTION_DIR%>, <%DATA_DIR%>
+     * Also strips HTML comments.
+     *
+     * @param prompt - Raw prompt text with template variables
+     * @returns Prompt with variables substituted and comments stripped
+     */
+    processPromptVariables(prompt: string): string;
+    /**
+     * Build prompt content for execution, handling both normal and exhaustion modes.
+     * This consolidates the prompt choosing logic used by both managers.
+     *
+     * @param codon - Codon configuration
+     * @param exhaustionPrompt - Optional exhaustion prompt (activates exhaustion mode)
+     * @returns Processed prompt content ready for execution
+     */
+    buildPromptForExecution(codon: Codon, exhaustionPrompt?: string): string;
+    /**
+     * Apply template variable replacements to content.
+     * All workspace variables resolve to agentRootPath (where agents work).
+     *
+     * Supports:
+     * - <%AGENT_ROOT%>    - Canonical variable for agent workspace (recommended)
+     * - <%PROJECT_DIR%>   - Silent alias for AGENT_ROOT
+     * - <%EXECUTION_DIR%> - Silent alias for AGENT_ROOT
+     * - <%DATA_DIR%>      - Data directory (agentRootPath/read_only_data_source)
+     */
+    private applyTemplateReplacements;
+    /**
+     * Strip HTML comments from content.
+     * HTML comments (<!-- ... -->) are removed before sending to the LLM.
+     * Also consumes a trailing newline to avoid blank lines accumulating.
+     *
+     * @param content - Content with potential HTML comments
+     * @returns Content with comments stripped
+     */
+    private stripHtmlComments;
+}

package/dist/prompt-frontmatter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Simple frontmatter parser for prompt markdown files.
+ *
+ * Frontmatter is ONLY for metadata/labeling (not configuration).
+ * Allowed fields: name, description, tags, version, author
+ *
+ * Example:
+ * ---
+ * name: Code Analyzer
+ * description: Analyzes code for patterns
+ * tags: [analysis, code-review]
+ * version: 1.0.0
+ * author: Team Name
+ * ---
+ */
+import { z } from "zod";
+/**
+ * Schema for allowed frontmatter fields.
+ * Strict validation - rejects unknown fields.
+ */
+export declare const promptFrontmatterSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    version: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    version?: string | undefined;
+    author?: string | undefined;
+}, {
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    version?: string | undefined;
+    author?: string | undefined;
+}>;
+export type PromptFrontmatter = z.infer<typeof promptFrontmatterSchema>;
+export interface ParsedPrompt {
+    /** The prompt content without frontmatter */
+    content: string;
+    /** Parsed frontmatter metadata (undefined if no frontmatter) */
+    frontmatter?: PromptFrontmatter;
+    /** Whether the file had frontmatter */
+    hasFrontmatter: boolean;
+}
+/**
+ * Parse frontmatter from markdown content.
+ * Returns the content without frontmatter and the parsed metadata.
+ *
+ * @param rawContent - Raw markdown content (may include frontmatter)
+ * @returns Parsed prompt with content and optional frontmatter
+ * @throws Error if frontmatter has invalid fields
+ */
+export declare function parsePromptFrontmatter(rawContent: string): ParsedPrompt;
+/**
+ * Format frontmatter metadata for display.
+ */
+export declare function formatFrontmatterForDisplay(frontmatter: PromptFrontmatter): string;

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

@@ -0,0 +1,82 @@
+import { BaseProcessManager } from "./base-process-manager.js";
+import type { ClaudeLogParser } from "./claude-log-parser.js";
+import type { Codon } from "./types/types.js";
+import type { Logger } from "./utils.js";
+/**
+ * ReplayProcessManager replays a previously recorded JSONL log file
+ * instead of making real LLM API calls.
+ *
+ * It implements the same interface as ClaudeAgentSDKManager and ShimProcessManager,
+ * writing source JSONL lines progressively to the target log file so that
+ * ClaudeLogParser can pick them up via its normal polling mechanism.
+ *
+ * For extensions (context exhaustion), tracks position across multiple spawn() calls,
+ * writing lines from after the previous result message to the next result message.
+ */
+export declare class ReplayProcessManager extends BaseProcessManager {
+    private executionPath;
+    private sourceLogPath;
+    private replaySpeed;
+    private logStream;
+    private syntheticPid;
+    private running;
+    private finished;
+    private replayTimer;
+    private sourceLines;
+    private currentLineIndex;
+    constructor(executionPath: string, logger: Logger, logParser: ClaudeLogParser, sourceLogPath: string, replaySpeed?: number);
+    /** Replay doesn't use prompt frontmatter */
+    get promptFrontmatter(): undefined;
+    /**
+     * Spawn a replay session for the given codon.
+     * Reads from the source JSONL log and writes lines progressively to the target log file.
+     *
+     * Matches the ClaudeAgentSDKManager.spawn() signature.
+     */
+    spawn(codon: Codon, _sessionToResume: string | null, options?: {
+        logPath?: string;
+        exhaustionPrompt?: string;
+    }): Promise<string>;
+    /**
+     * Write lines one at a time with delays between them.
+     * Uses timestamps from log entries for realistic timing when available,
+     * falling back to fixed replaySpeed for old logs without timestamps.
+     * Stops at result messages and emits exit.
+     */
+    private writeNextLine;
+    /**
+     * Peek at the timestamp of the next unwritten line without advancing the index.
+     */
+    private peekNextTimestamp;
+    /**
+     * Calculate the delay before writing the next line.
+     * Uses timestamps for realistic timing when available,
+     * falls back to fixed replaySpeed for old logs without timestamps.
+     * Caps maximum delay to avoid long waits from tool executions.
+     */
+    private calculateDelay;
+    /**
+     * Finish a replay session: flush log parser, clean up, emit exit.
+     */
+    private finishReplay;
+    /**
+     * Kill the replay session.
+     */
+    kill(_signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Force-kill the replay session.
+     */
+    forceKill(): Promise<void>;
+    /**
+     * Check if replay is in progress.
+     */
+    isRunning(): boolean;
+    /**
+     * Get synthetic PID.
+     */
+    getPid(): number | undefined;
+    /**
+     * Close log stream explicitly.
+     */
+    closeLogStream(): Promise<void>;
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Runtime Extractor Base
+ *
+ * Shared utilities for extracting embedded runtime files (binaries, SDKs, shims)
+ * from compiled executables. This module provides common functionality used by:
+ * - codex-runtime-extractor.ts (Codex binary extraction)
+ * - claude-runtime-extractor.ts (Claude SDK files extraction)
+ * - shim-runtime-extractor.ts (Shim files extraction)
+ *
+ * Key Concepts:
+ * - Embedded files: Files bundled into the executable using Bun's --embed flag
+ * - Extraction: Writing embedded files to disk for use as subprocesses
+ * - Versioned cache: Extracted files stored in versioned directories (e.g., ~/.hankweave/component/version/)
+ * - Marker files: Indicate successful extraction and version tracking
+ */
+/**
+ * Configuration for a single file to extract
+ */
+export interface FileToExtract {
+    /** Path to the embedded file (e.g., "node_modules/package/file.js") */
+    embeddedPath: string;
+    /** Path where the file should be extracted (relative to extraction directory) */
+    outputPath: string;
+    /** Whether extraction should fail if this file is missing */
+    required: boolean;
+    /** Whether to make the file executable (Unix only) */
+    makeExecutable?: boolean;
+}
+/**
+ * Configuration for extracting a component's files
+ */
+export interface ExtractionConfig {
+    /** Human-readable component name (e.g., "Codex", "Claude SDK") */
+    componentName: string;
+    /** Version string for cache directory naming */
+    version: string;
+    /** Optional base path prefix for embedded files */
+    embeddedBasePath?: string;
+    /** List of files to extract */
+    filesToExtract: FileToExtract[];
+    /** Custom marker file name (defaults to ".extraction-complete") */
+    markerFileName?: string;
+    /** Optional function to validate extraction was successful */
+    validateExtraction?: (extractionDir: string) => boolean;
+}
+/**
+ * Result of an extraction operation
+ */
+export interface ExtractionResult {
+    /** Directory where files were extracted */
+    extractionDir: string;
+    /** Paths of successfully extracted files */
+    extractedFiles: string[];
+    /** Files that failed to extract (with error messages) */
+    failedFiles: Array<{
+        path: string;
+        error: string;
+    }>;
+    /** Whether cached files were used (no extraction needed) */
+    usedCache: boolean;
+}
+/**
+ * Get the Bun virtual filesystem prefix for the current platform.
+ * - Unix: /$bunfs/root
+ * - Windows: X:/~BUN/root (where X is the drive letter from process.argv[1])
+ */
+export declare function getBunVfsPrefix(): string;
+/**
+ * Read an embedded file from Bun.embeddedFiles.
+ *
+ * First tries to find the file in Bun.embeddedFiles (the recommended way),
+ * then falls back to Bun.file() with various path formats.
+ *
+ * Throws if the file doesn't exist or can't be read.
+ */
+export declare function readEmbeddedFile(embeddedPath: string): Promise<ArrayBuffer>;
+/**
+ * Compute a hash of file content for verification.
+ * Returns first 12 characters of MD5 hash for compact display.
+ */
+export declare function computeFileHash(content: Buffer | string): string;
+/**
+ * Get the base extraction directory (usually ~/.hankweave/).
+ * Respects HANKWEAVE_CACHE_DIR environment variable.
+ */
+export declare function getExtractionBaseDir(): string;
+/**
+ * Get the extraction directory for a specific component and version.
+ *
+ * @param componentName - Component identifier (e.g., "codex-sdk", "claude-sdk", "shims")
+ * @param version - Version string for directory naming
+ * @returns Full path to extraction directory (e.g., ~/.hankweave/codex-sdk/0.87.0/)
+ */
+export declare function getComponentExtractionDir(componentName: string, version: string): string;
+/**
+ * Check if extraction is needed based on marker file and version.
+ *
+ * @param extractionDir - Directory where files would be extracted
+ * @param expectedVersion - Version string to compare against marker
+ * @param markerFileName - Name of marker file (defaults to ".extraction-complete")
+ * @param requiredFiles - Optional list of files that must exist
+ * @returns true if extraction is needed, false if cache is valid
+ */
+export declare function needsExtraction(extractionDir: string, expectedVersion: string, markerFileName?: string, requiredFiles?: string[]): boolean;
+/**
+ * Extract embedded files to disk based on configuration.
+ *
+ * This is the main extraction engine that:
+ * 1. Creates extraction directory
+ * 2. Optionally lists all embedded files for debugging
+ * 3. Extracts each configured file
+ * 4. Sets executable permissions where needed
+ * 5. Writes version marker file
+ *
+ * @param config - Extraction configuration
+ * @param debugListFiles - Whether to log all embedded files (default: true)
+ * @returns Extraction result with paths and status
+ * @throws Error if required files fail to extract
+ */
+export declare function extractFiles(config: ExtractionConfig, debugListFiles?: boolean): Promise<ExtractionResult>;