hankweave 0.5.7 → 0.6.2

package/README.md

@@ -34,7 +34,8 @@ Hankweave takes care of long-running executions, while:
 - **Preflight checks** catch as many problems as possible before the first token is cast - API keys, model availability, file paths, rig configs, sentinel schemas.
 - **Sentinels** monitor the event stream in real time to catch drift, laziness, and convention violations - functioning as error detectors, narrators, and real-time evals while keeping the core agent focused.
 - **Looping** sequences repeat complex tasks, trading compute for reliability using Agentic Dynamic Programming.
-- **Harness abstraction** lets hanks run on Claude Code, Codex, Gemini CLI, or any agent that exposes the right capabilities. Test in your preferred coding agent, then freeze and ship. Swap harnesses seamlessly, or build new ones using [Clausetta](./learning/examples/clausetta/), our hank for auto-generating shims.
+- **Budgets** let hank authors and operators independently express cost, time, and token limits. The runtime resolves competing preferences, distributes budgets across codons and loops, and enforces them in real time — including budget-driven variable loop termination.
+- **Harness abstraction** lets hanks run on Claude Code, Codex, Gemini CLI, Pi, OpenCode, or any agent that exposes the right capabilities. Test in your preferred coding agent, then freeze and ship. Swap harnesses seamlessly, or build new ones using [Clausetta](./learning/examples/clausetta/), our hank for auto-generating shims.
 - **Rigs** provide deterministic code loading and workspace setup, so the same codon runs the same way every time.
 - **Checkpointing and rollbacks** create git snapshots at every codon boundary. When something fails, roll back to any point and try a different approach.
 - **Structured event journal** traces every tool call and decision back to its source, making it possible to pinpoint where a 20-hour run went wrong.
@@ -61,7 +62,7 @@ Today, Hankweave is responsible for executing all reliable AI work at Southbridg
 
 ## How Hankweave Works
 
-The Hankweave runtime is a **server** that orchestrates agent harnesses - Claude Code, Gemini CLI, and others - to execute hanks reliably. Written entirely in Typescript, Hankweave is designed to be a configurable bottom-of-the-stack runtime that can run almost anywhere. Here's the full picture:
+The Hankweave runtime is a **server** that orchestrates agent harnesses - Claude Code, Codex, Gemini CLI, Pi, OpenCode, and others - to execute hanks reliably. Written entirely in Typescript, Hankweave is designed to be a configurable bottom-of-the-stack runtime that can run almost anywhere. Here's the full picture:
 
 ```
         ┌─────────────────────────────────┐
@@ -83,12 +84,12 @@ The Hankweave runtime is a **server** that orchestrates agent harnesses - Claude
    EVENTS (WebSocket)                                                     ORCHESTRATES
           │                                                                       │
           ▼                                                                       ▼
-┌─────────────────────────┐             ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
-│       CONSUMERS         │             │ Claude  │ │ Gemini  │ │  Codex  │ │  Cline  │
-│                         │             │ Code    │ │ CLI     │ │         │ │         │
-│  Basic CLI (included)   │             └────┬────┘ └────┬────┘ └────┬────┘ └─────┬───┘
-│  Data pipelines         │                  │           │           │            │
-│  CI systems             │                  └───────────┴───────────┴────────────┘
+┌─────────────────────────┐             ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐
+│       CONSUMERS         │             │ Claude │ │ Gemini │ │ Codex  │ │   Pi   │ │ OpenCode │
+│                         │             │ Code   │ │ CLI    │ │        │ │        │ │          │
+│  Basic CLI (included)   │             └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └────┬─────┘
+│  Data pipelines         │                 │          │          │          │           │
+│  CI systems             │                 └──────────┴──────────┴──────────┴───────────┘
 │  Custom UIs             │                                    │
 │                         │                                    ▼
 └─────────────────────────┘             ┌─────────────────────────────────────────────┐
@@ -250,16 +251,16 @@ Files. One codon writes to the filesystem, the next reads from it. There's no im
 
 It depends on the hank and the models you choose. A complex planning hank might cost $10-15 per run on frontier models. Simpler hanks can cost pennies.
 
-The key insight is that as hanks mature, you can move to faster and cheaper models. Early iteration needs the best model you can get; once the prompts, rigs, and sentinels are dialed in, the structure does the heavy lifting and cheaper models perform well. Try running any hank with `-m haiku` to quickly prototype.
+The key insight is that as hanks mature, you can move to faster and cheaper models. Early iteration needs the best model you can get; once the prompts, rigs, and sentinels are dialed in, the structure does the heavy lifting and cheaper models perform well. Try running any hank with `-m haiku` to quickly prototype, or use `--max-cost 0.50 -m haiku` for a budget-capped pilot run.
 
-Hankweave includes per-codon [cost and token tracking](https://hankweave.southbridge.ai/reference/performance/) so you can see exactly where spend is going and optimize accordingly.
+Hankweave includes per-codon [cost and token tracking](https://hankweave.southbridge.ai/reference/performance/) and a [budget system](https://hankweave.southbridge.ai/concepts/budgets/) that lets authors allocate budgets across codons and loops, and operators cap runs with `--max-cost` and `--max-time`.
 
 </details>
 
 <details>
 <summary><strong>What models and harnesses are supported?</strong></summary>
 
-Claude Agent SDK is packaged in by default. Using the polymorphic connector pattern with shims, we support several other agents (Gemini CLI, etc.). But the real answer is: you can build new ones easily. If an agent exposes the required capabilities, you can run the polymorphic hank, plug in information about the agent you want supported, and Hankweave - using a hank - will build a shim to connect it. Hankweave building its own harness adapters is one of our favorite examples of hanks in action.
+Five agent harnesses ship with Hankweave: **Claude Code** (via the Agents SDK, in-process), **Gemini CLI**, **Codex**, **Pi** (embedded — no external CLI install needed), and **OpenCode** (all via shims). You can mix harnesses in the same hank — use Claude for targeted coding, Gemini for writing, Codex for planning. And you can build new ones: if an agent exposes the required capabilities, you can run the polymorphic hank, plug in information about the agent you want supported, and Hankweave - using a hank - will build a shim to connect it.
 
 </details>
 

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