hankweave 0.6.1 → 0.6.2

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

@@ -0,0 +1,98 @@
+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";
+/**
+ * Manages shim subprocess lifecycle, including spawning, monitoring, and cleanup.
+ * Handles log stream creation and process argument building.
+ * Works with any shim that supports the standardized argument interface.
+ */
+export declare class ShimProcessManager extends BaseProcessManager {
+    private executionPath;
+    private agentRootPath;
+    private anthropicBaseUrl?;
+    private globalSystemPrompt?;
+    private defaultShimIdleTimeout?;
+    private process;
+    private logStream;
+    private stdoutReader;
+    private killed;
+    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;
+    /**
+     * Spawn a shim process for the given codon configuration.
+     * Sets up logging, environment, and process monitoring.
+     *
+     * This unified method handles both normal codon execution and exhaustion extensions.
+     * From the shim's perspective, both are identical: resume a session with a new prompt.
+     * The difference is only where the prompt comes from.
+     *
+     * @param command - Command to execute (e.g., ["claude"] or ["bun", "run", "shims/gemini/dist/index.mjs"])
+     * @param codon - Codon configuration (not Loop - loops must be expanded first)
+     * @param sessionToResume - Session ID to resume (if any)
+     * @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.
+     */
+    spawn(command: string[], codon: Codon, sessionToResume: string | null, options?: {
+        logPath?: string;
+        exhaustionPrompt?: string;
+    }): Promise<string>;
+    /**
+     * Build environment variables for the shim process.
+     */
+    private buildEnvironment;
+    /**
+     * Build command line arguments for shim.
+     * Only includes arguments supported by all shims.
+     *
+     * @param codon - Codon configuration
+     * @param previousSessionId - Session ID to resume (if any)
+     * @param isExhaustionMode - True if this is an extension (exhaustion mode)
+     */
+    private buildShimArgs;
+    /**
+     * Set up process event handlers.
+     */
+    private setupProcessHandlers;
+    /**
+     * Kill the shim process gracefully.
+     * Sends SIGTERM and waits up to PROCESS_KILL_GRACE_MS for the process to exit.
+     * If the process doesn't exit in time, escalates to SIGKILL.
+     */
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Force-kill the shim process immediately with SIGKILL.
+     * Used by forceShutdown() when the user presses q/Ctrl+C a second time.
+     */
+    forceKill(): Promise<void>;
+    /**
+     * Clean up resources.
+     */
+    private cleanup;
+    /**
+     * Check if process is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get process PID.
+     */
+    getPid(): number | undefined;
+    /**
+     * Close log stream explicitly (for external cleanup).
+     */
+    closeLogStream(): Promise<void>;
+    /**
+     * Run the shim's self-test to verify environment setup.
+     * Executes the shim with --self-test flag and returns the results.
+     *
+     * @param command - Command to execute shim (e.g., ["bun", "shims/gemini/index.js"])
+     * @param providerId - Optional provider ID (e.g., "openai", "google") to set up provider-specific requirements
+     * @returns Promise resolving to self-test results
+     * @throws Error if self-test execution fails or returns invalid JSON
+     */
+    runSelfTest(command: string[], providerId?: string): Promise<ShimSelfTestResult>;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Shim Runtime Extractor
+ *
+ * This module handles the extraction of bundled shim files at runtime for
+ * standalone executables. When compiled with Bun, shim 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 version updates cleanly.
+ *
+ * Build Process:
+ * The build script (scripts/build-executable.ts) embeds shim files using:
+ *   bun build --compile --embed shims/gemini/index.js ...
+ *
+ * Note: We use .js extension instead of .mjs for better embedding compatibility.
+ *
+ * At runtime, these embedded files are accessible via Bun.file() using their
+ * original paths.
+ */
+declare const SHIM_NAMES: readonly ["gemini", "codex", "pi", "opencode"];
+type ShimName = (typeof SHIM_NAMES)[number];
+/**
+ * Get the extraction directory path for shims.
+ * Uses ~/.hankweave/shims/<version>/ by default.
+ */
+export declare function getShimExtractionDir(): string;
+/**
+ * Get the path to an extracted shim file.
+ * Note: We use .js extension for embedding compatibility, even though the
+ * source file is .mjs. The file works the same regardless of extension.
+ */
+export declare function getExtractedShimPath(shimName: ShimName): string;
+/**
+ * Check if extraction is needed for a specific shim.
+ * Returns true if the file doesn't exist or is outdated.
+ */
+export declare function needsShimExtraction(shimName: ShimName): boolean;
+/**
+ * Extract embedded shim files to the cache directory.
+ * This should be called when running from a compiled executable.
+ *
+ * Shims are embedded as .bundle (not .js) because Bun's --embed flag
+ * rebundles .js files instead of preserving raw bytes, which truncates
+ * large bundles like the Pi shim (10 MB → 28 KB). The .bundle extension
+ * bypasses this behaviour. We write them back out as .js on extraction.
+ *
+ * @returns Path to the extracted gemini shim (for backward compatibility)
+ */
+export declare function extractShimFiles(): Promise<string>;
+export {};

package/dist/shims/codex/index.js

@@ -2,7 +2,8 @@
 
 // src/shim.ts
 import { spawn as spawn2 } from "child_process";
-import fs5 from "fs";
+import fs4 from "fs";
+import os2 from "os";
 import path6 from "path";
 
 // node_modules/@openai/codex-sdk/dist/index.js
@@ -753,8 +754,6 @@ var DebugRecorder = class {
 
 // src/utils.ts
 import { randomBytes, randomUUID as randomUUID2 } from "crypto";
-import fs4 from "fs";
-import os2 from "os";
 import path5 from "path";
 var NIL_UUID = "00000000-0000-0000-0000-000000000000";
 var SESSION_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -804,22 +803,6 @@ function mapSandbox(level) {
       return "danger-full-access";
   }
 }
-function detectApiKeySource() {
-  if (process.env.OPENAI_API_KEY) {
-    return "OPENAI_API_KEY";
-  }
-  if (process.env.CODEX_API_KEY) {
-    return "CODEX_API_KEY";
-  }
-  const authPath = path5.join(os2.homedir(), ".codex", "auth.json");
-  if (fs4.existsSync(authPath)) {
-    return "~/.codex/auth.json";
-  }
-  return "none";
-}
-function hasAnyAuthConfigured() {
-  return detectApiKeySource() !== "none";
-}
 function getCodexPathOverride() {
   const value = process.env.CODEX_PATH_OVERRIDE?.trim();
   return value ? value : void 0;
@@ -1243,7 +1226,7 @@ function usageToTokenUsage(usage) {
     cache_read_input_tokens: usage.cached_input_tokens
   };
 }
-function createSystemMessage(cwd, sessionId, model) {
+function createSystemMessage(cwd, sessionId, model, apiKeySource) {
   return {
     type: "system",
     subtype: "init",
@@ -1252,7 +1235,7 @@ function createSystemMessage(cwd, sessionId, model) {
     tools: DEFAULT_TOOLS,
     model,
     permissionMode: "bypassPermissions",
-    apiKeySource: detectApiKeySource(),
+    apiKeySource,
     mcp_servers: []
   };
 }
@@ -1346,17 +1329,17 @@ function findVendoredCodexExe(npmPrefix) {
     path6.join(npmPrefix, "node_modules", "@openai", "codex", "node_modules", tail)
   ];
   for (const candidate of candidates) {
-    if (fs5.existsSync(candidate)) return candidate;
+    if (fs4.existsSync(candidate)) return candidate;
   }
   return null;
 }
 async function resolveCodexPath(command) {
   const isWindows = process.platform === "win32";
   if (path6.isAbsolute(command) || command.includes(path6.sep)) {
-    if (fs5.existsSync(command)) return command;
+    if (fs4.existsSync(command)) return command;
     if (isWindows) {
       for (const ext of [".cmd", ".exe"]) {
-        if (fs5.existsSync(command + ext)) return command + ext;
+        if (fs4.existsSync(command + ext)) return command + ext;
       }
     }
     return null;
@@ -1415,43 +1398,6 @@ async function resolveAgentVersion(codexPath) {
     });
   });
 }
-async function runSelfTest() {
-  const apiKeySource = detectApiKeySource();
-  const override = getCodexPathOverride() || "codex";
-  const resolvedPath = await resolveCodexPath(override);
-  const agentFound = resolvedPath !== null;
-  const agentVersion = resolvedPath ? await resolveAgentVersion(resolvedPath) : "unknown";
-  const checks = [
-    {
-      name: "agent_found",
-      passed: agentFound,
-      message: agentFound ? `Found codex at ${resolvedPath}` : `Could not find codex via ${override}`
-    },
-    {
-      name: "api_key",
-      passed: apiKeySource !== "none",
-      message: apiKeySource !== "none" ? `Authentication source available: ${apiKeySource}` : "No OPENAI_API_KEY, CODEX_API_KEY, or ~/.codex/auth.json found"
-    }
-  ];
-  const overallPassed = checks.every((check) => check.passed);
-  process.stdout.write(
-    `${JSON.stringify(
-      {
-        shim: { name: "codex-shim", version: package_default.version },
-        agent: { name: "codex", version: agentVersion, found: agentFound },
-        checks,
-        overall: {
-          passed: overallPassed,
-          message: overallPassed ? "All checks passed" : "One or more checks failed"
-        }
-      },
-      null,
-      2
-    )}
-`
-  );
-  return overallPassed ? 0 : 1;
-}
 var CodexShim = class {
   args;
   prompt;
@@ -1477,16 +1423,64 @@ var CodexShim = class {
     this.sessionManager = new SessionManager({ debugDir: args.debugDir });
     this.sessionId = args.resume || generateSessionId();
   }
+  get resolvedApiKey() {
+    return process.env.OPENAI_API_KEY || process.env.CODEX_API_KEY || void 0;
+  }
+  get apiKeySource() {
+    if (process.env.OPENAI_API_KEY) return "OPENAI_API_KEY";
+    if (process.env.CODEX_API_KEY) return "CODEX_API_KEY";
+    if (fs4.existsSync(path6.join(os2.homedir(), ".codex", "auth.json"))) return "~/.codex/auth.json";
+    return "none";
+  }
+  get isAuthConfigured() {
+    return this.apiKeySource !== "none";
+  }
+  async runSelfTest() {
+    const override = getCodexPathOverride() || "codex";
+    const resolvedPath = await resolveCodexPath(override);
+    const agentFound = resolvedPath !== null;
+    const agentVersion = resolvedPath ? await resolveAgentVersion(resolvedPath) : "unknown";
+    const checks = [
+      {
+        name: "agent_found",
+        passed: agentFound,
+        message: agentFound ? `Found codex at ${resolvedPath}` : `Could not find codex via ${override}`
+      },
+      {
+        name: "api_key",
+        passed: this.isAuthConfigured,
+        message: this.isAuthConfigured ? `Authentication source available: ${this.apiKeySource}` : "No OPENAI_API_KEY, CODEX_API_KEY, or ~/.codex/auth.json found"
+      }
+    ];
+    const overallPassed = checks.every((check) => check.passed);
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          shim: { name: "codex-shim", version: package_default.version },
+          agent: { name: "codex", version: agentVersion, found: agentFound },
+          checks,
+          overall: {
+            passed: overallPassed,
+            message: overallPassed ? "All checks passed" : "One or more checks failed"
+          }
+        },
+        null,
+        2
+      )}
+`
+    );
+    return overallPassed ? 0 : 1;
+  }
   async run() {
     const codexPath = await resolveCodexPath(getCodexPathOverride() || "codex");
     if (!codexPath) {
       writeStartupError("Agent not found: could not locate codex via CODEX_PATH_OVERRIDE or PATH", this.args.debugDir);
     }
-    if (!hasAnyAuthConfigured()) {
+    if (!this.isAuthConfigured) {
       writeStartupError("Missing API key: set OPENAI_API_KEY, CODEX_API_KEY, or ~/.codex/auth.json", this.args.debugDir);
     }
     this.codex = new Codex({
-      apiKey: process.env.OPENAI_API_KEY || process.env.CODEX_API_KEY,
+      apiKey: this.resolvedApiKey,
       codexPathOverride: codexPath,
       env: Object.fromEntries(
         Object.entries(process.env).filter((entry) => entry[1] !== void 0)
@@ -1509,7 +1503,7 @@ var CodexShim = class {
     } else {
       thread = this.codex.startThread(this.getThreadOptions());
     }
-    const systemMessage = createSystemMessage(this.cwd, this.sessionId, this.model.publicModel);
+    const systemMessage = createSystemMessage(this.cwd, this.sessionId, this.model.publicModel, this.apiKeySource);
     emit(systemMessage);
     this.debug.setSession(this.sessionId, { cwd: this.cwd, model: this.model.publicModel });
     const startedAt = Date.now();
@@ -1624,11 +1618,15 @@ var CodexShim = class {
         throw new Error(event.message);
       }
       case "item.started": {
-        await this.emitToolUseIfNeeded(event.item);
+        if (event.item.type !== "web_search") {
+          await this.emitToolUseIfNeeded(event.item);
+        }
         break;
       }
       case "item.updated": {
-        await this.emitToolUseIfNeeded(event.item);
+        if (event.item.type !== "web_search") {
+          await this.emitToolUseIfNeeded(event.item);
+        }
         break;
       }
       case "item.completed": {
@@ -1664,7 +1662,8 @@ var CodexShim = class {
       return;
     }
     if (item.type === "error") {
-      throw new Error(item.message);
+      this.logVerbose(`Codex non-fatal error item: ${item.message}`);
+      return;
     }
     if (shouldTreatAsToolItem(item)) {
       const toolId = await this.emitToolUseIfNeeded(item);
@@ -1741,7 +1740,7 @@ async function main(argv = process.argv.slice(2)) {
     return 0;
   }
   if (args.selfTest) {
-    return await runSelfTest();
+    return await new CodexShim(args, "").runSelfTest();
   }
   const prompt = await readStdin();
   if (!prompt) {

package/dist/state-manager.d.ts

@@ -0,0 +1,161 @@
+import type { CheckpointGit } from "./checkpoint-git.js";
+import { type ExecutionCodonEntry } from "./execution-planner.js";
+import { type ExecutionThread } from "./execution-thread.js";
+import { type StateManagerEvents, TypedEventEmitter } from "./typed-event-emitter.js";
+import { type CodonId, type RunId } from "./types/branded-types.js";
+import type * as ST from "./types/state-types.js";
+import type { CodonConfig } from "./types/types.js";
+import { type Logger } from "./utils.js";
+export declare class InvalidTransitionError extends Error {
+    constructor(from: ST.CodonStatus, to: ST.CodonStatus);
+}
+export declare class PersistenceError extends Error {
+    constructor(operation: string, cause: Error);
+}
+/**
+ * Result of expanding the next iteration of a loop.
+ * If a loop terminated, includes the loop ID and its archiveOnSuccess paths.
+ */
+export interface ExpandIterationResult {
+    loopTerminated?: {
+        loopId: string;
+        archiveOnSuccess?: string[];
+        completedIterations: number;
+    };
+}
+export declare class StateManager extends TypedEventEmitter<StateManagerEvents> implements ST.StateManager {
+    private readonly hankweaveDir;
+    private readonly codonConfigs?;
+    private state;
+    private readonly statePath;
+    private readonly stateBackupPath;
+    private readonly logger;
+    private transitionQueue;
+    private isProcessing;
+    private readonly planner;
+    private costCache;
+    constructor(hankweaveDir: string, logger: Logger, codonConfigs?: CodonConfig[] | undefined);
+    initialize(): Promise<void>;
+    /**
+     * Load and validate a state file from disk.
+     * @throws Error if file is corrupted or cannot be read
+     */
+    private loadAndValidateStateFile;
+    /**
+     * Restore state from a parsed and validated state object.
+     */
+    private restoreStateFromParsed;
+    /**
+     * Attempt to restore state from backup file.
+     */
+    private tryRestoreFromBackup;
+    getState(): Readonly<ST.HankweaveState>;
+    /**
+     * Get codon entry from execution plan by codon ID.
+     * This handles generated IDs like "review#0", "review#1" from loop expansion.
+     *
+     * @param codonId - The codon ID to look up
+     * @returns The execution codon entry, or null if not found
+     */
+    getCodonById(codonId: CodonId): ExecutionCodonEntry | null;
+    /**
+     * Build initial execution plan for a fresh start.
+     * Expands only the first iteration of each loop.
+     * Automatically validates and stores the plan.
+     * Called automatically when RunStarted transition occurs (unless continuation mode).
+     */
+    private buildInitialPlan;
+    /**
+     * Expand next iteration of a loop after codon completion.
+     * Checks if this completed codon is part of a loop and expands the next iteration if needed.
+     * Automatically validates and stores the updated plan.
+     *
+     * @returns Information about loop termination if a loop ended
+     */
+    expandNextIterationForCodon(params: {
+        codonId: CodonId;
+        contextExceeded?: boolean;
+        budgetExceeded?: boolean;
+    }): Promise<ExpandIterationResult>;
+    /**
+     * Checks if context exceeded is an acceptable termination condition for the given codon.
+     *
+     * Returns true only if:
+     * - Codon is part of a loop (has loopContext)
+     * - That loop terminates on contextExceeded
+     *
+     * This is a pure query method with no side effects.
+     *
+     * @param codonId - The codon to check
+     * @returns true if context exceeded is acceptable, false otherwise
+     */
+    isContextExceededAcceptable(codonId: CodonId): boolean;
+    transition(event: ST.StateTransition): void;
+    private processQueue;
+    private updateCostCache;
+    private updateExecutionPlan;
+    private rebuildCostCache;
+    validate(state: unknown): ST.StateValidation;
+    private isValidStateStructure;
+    getCurrentRunCost(): number;
+    getTotalCost(): number;
+    getCurrentRun(): ST.Run | null;
+    getCurrentlyRunningCodon(): ST.CodonExecution | null;
+    getCodonInCurrentRun(codonId: CodonId): ST.CodonExecution | null;
+    /**
+     * Get the next codon that should be executed based on current state.
+     * Uses the execution thread to determine where we are in the workflow.
+     *
+     * @returns CodonId of next codon to execute, or null if all codons are complete
+     */
+    getNextCodonToExecute(): Promise<CodonId | null>;
+    getRun(runId: RunId): ST.Run | null;
+    getCodonHistory(codonId: CodonId): Promise<Array<{
+        run: ST.Run;
+        codon: ST.CodonExecution;
+    }>>;
+    getCostSince(runId: RunId): number;
+    canContinueFrom(runId: RunId, afterCodon: CodonId | null): boolean;
+    getCheckpointForContinuation(runId: RunId, afterCodon: CodonId | null): string | null;
+    getRunById(runId: RunId): ST.Run | null;
+    private checkpointGit?;
+    /**
+     * Set the checkpoint git instance for git operations.
+     * Called by HankweaveRuntime after initializing CheckpointGit.
+     */
+    setCheckpointGit(checkpointGit: CheckpointGit): void;
+    /**
+     * Get the execution thread for the current state.
+     * This provides a unified view of codon execution across all runs.
+     *
+     * @param targetRunId - Optional run ID to start from (defaults to latest)
+     * @param includeCheckpointValidation - Whether to validate checkpoints against git
+     * @returns Complete execution thread with all metadata
+     *
+     * NOTE: The codonConfigs fallback exists for initialization timing issues where the plan
+     * hasn't been built yet (e.g., during HankweaveRuntime.start() before startNewRun()).
+     */
+    getExecutionThread(targetRunId?: RunId, includeCheckpointValidation?: boolean): Promise<ExecutionThread>;
+    /**
+     * Helper to convert checkpoint array to map for execution thread
+     */
+    private getCheckpointDataMap;
+    /**
+     * Get all checkpoints with detailed information, ordered by time.
+     * This exposes the checkpoint history for advanced use cases.
+     *
+     * @returns Array of checkpoint information ordered by timestamp (newest first), or null if git unavailable
+     */
+    getAllCheckpoints(): Promise<Array<{
+        sha: string;
+        message: string;
+        timestamp: string;
+        branch: string;
+    }> | null>;
+    private validateTransition;
+    private applyTransition;
+    save(): Promise<void>;
+    detectCrashedRuns(): Promise<void>;
+    recover(): Promise<ST.RecoveryResult>;
+    waitForPendingTransitions(): Promise<void>;
+}

package/dist/state-transition-guards.d.ts

@@ -0,0 +1,37 @@
+import type { SessionId } from "./types/branded-types.js";
+import type { BudgetExceededData } from "./types/budget-types.js";
+import type { CodonStatus } from "./types/state-types.js";
+import type { FailureReason } from "./types/types.js";
+export interface InitializingMetadata {
+    claudePid: number;
+    claudeLogPath: string;
+}
+export interface RunningMetadata {
+    claudeSessionId: SessionId;
+}
+export interface CompletedMetadata {
+    checkpointSha: string;
+    resultMessageReceived?: boolean;
+    budgetExceeded?: BudgetExceededData;
+}
+export interface FailedMetadata {
+    exitCode: number;
+    failureReason: FailureReason;
+    failedDuring: CodonStatus;
+    checkpointSha?: string;
+}
+export interface SkippedMetadata {
+    skippedDuring: CodonStatus;
+    checkpointSha?: string;
+}
+export declare function hasInitializingMetadata(metadata: unknown): metadata is InitializingMetadata;
+export declare function hasRunningMetadata(metadata: unknown): metadata is RunningMetadata;
+export declare function hasCompletedMetadata(metadata: unknown): metadata is CompletedMetadata;
+export declare function hasFailedMetadata(metadata: unknown): metadata is FailedMetadata;
+export declare function hasSkippedMetadata(metadata: unknown): metadata is SkippedMetadata;
+export declare class MetadataValidationError extends Error {
+    readonly transitionTo: CodonStatus;
+    readonly missingFields: string[];
+    constructor(transitionTo: CodonStatus, missingFields: string[]);
+}
+export declare function validateTransitionMetadata(to: CodonStatus, metadata: unknown): void;