hankweave 0.5.7 → 0.6.2

package/dist/cost-tracker.d.ts

@@ -0,0 +1,72 @@
+import type { LlmProviderRegistry } from "./llm/llm-provider-registry.js";
+import { TypedEventEmitter } from "./typed-event-emitter.js";
+import type { TokenUsage } from "./types/types.js";
+import type { Logger } from "./utils.js";
+/**
+ * Raw API usage fields from assistant messages.
+ */
+export interface RawApiUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/**
+ * Raw fields from a result message relevant to cost tracking.
+ */
+export interface RawResultUsage {
+    usage?: RawApiUsage;
+    total_cost_usd?: number;
+    modelUsage?: unknown;
+}
+/**
+ * Events emitted by CostTracker.
+ */
+export interface CostTrackerEvents extends Record<string, unknown[]> {
+    /** Incremental cost from an assistant message */
+    costIncremented: [delta: {
+        cost: number;
+        tokens: TokenUsage;
+    }];
+    /** Authoritative final cost from result message */
+    finalCostSet: [
+        final: {
+            cost: number;
+            tokens: TokenUsage;
+            modelUsage?: unknown;
+            modelId?: string;
+        }
+    ];
+}
+/**
+ * Encapsulates cost computation and accumulation for a single codon execution.
+ *
+ * Receives raw API messages, calculates costs via LlmProviderRegistry, maintains
+ * running totals, and emits typed events for external consumers (state transitions,
+ * event broadcasting).
+ *
+ * Owned by CodonRunner. The runtime subscribes to its events.
+ */
+export declare class CostTracker extends TypedEventEmitter<CostTrackerEvents> {
+    private readonly modelId;
+    private readonly llmRegistry;
+    private readonly logger;
+    private runningCost;
+    private runningTokens;
+    constructor(modelId: string | undefined, llmRegistry: LlmProviderRegistry, logger: Logger);
+    /**
+     * Process usage from an assistant message. Calculates incremental cost,
+     * accumulates running totals, and emits costIncremented.
+     */
+    handleAssistantUsage(usage: RawApiUsage): void;
+    /**
+     * Process usage from a result message. Resolves authoritative final cost
+     * using priority chain (CLI-provided > registry calc > accumulated fallback),
+     * logs discrepancies, and emits finalCostSet.
+     */
+    handleResultUsage(msg: RawResultUsage): void;
+    /** Current accumulated cost (for logging/fallback). */
+    getRunningCost(): number;
+    /** Current accumulated token usage. */
+    getRunningTokens(): TokenUsage;
+}

package/dist/execution-planner.d.ts

@@ -0,0 +1,62 @@
+import { CodonId } from "./types/branded-types.js";
+import type { AllocationMode } from "./types/budget-types.js";
+import type { Codon, CodonConfig } from "./types/types.js";
+/**
+ * Represents a flattened codon in the execution plan.
+ * Each entry is a concrete codon that will be executed.
+ */
+export interface ExecutionCodonEntry {
+    codon: Codon;
+    codonId: CodonId;
+    loopContext?: {
+        loopId: CodonId;
+        iteration: number;
+        codonIndexInLoop: number;
+        loopBudget?: {
+            maxDollars?: number;
+            maxTimeSeconds?: number;
+            allocation?: AllocationMode;
+            shares?: Record<string, number>;
+            onExceeded?: "complete" | "fail";
+        };
+    };
+}
+/**
+ * Handles all execution planning logic.
+ * Pure functions - no side effects, just config → plan transformations.
+ */
+export declare class ExecutionPlanner {
+    private codonConfigs;
+    constructor(codonConfigs: CodonConfig[]);
+    /**
+     * Build initial execution plan for fresh start.
+     * Expands only the first iteration of each loop.
+     */
+    buildInitialPlan(): ExecutionCodonEntry[];
+    /**
+     * Expand next iteration after codon completion.
+     * Returns new plan with next iteration injected (if termination not met).
+     * Pure function - doesn't mutate input plan.
+     */
+    expandNextIteration(params: {
+        currentPlan: ExecutionCodonEntry[];
+        completedCodonId: CodonId;
+        contextExceeded?: boolean;
+        budgetExceeded?: boolean;
+    }): ExecutionCodonEntry[];
+    /**
+     * Validate the execution plan for consistency.
+     * Catches configuration errors before execution.
+     */
+    validatePlan(plan: ExecutionCodonEntry[]): void;
+    /**
+     * Create execution plan for a specific iteration of a loop.
+     */
+    private createIterationPlan;
+    /**
+     * Generate a unique codon ID for a loop iteration.
+     * Format: "originalId#iteration" where iteration is 0-indexed
+     * Examples: "review#0", "review#1", "review#2"
+     */
+    private generateIterationCodonId;
+}

package/dist/execution-thread.d.ts

@@ -0,0 +1,71 @@
+import { type CodonExecution, type CodonId, type HankweaveState, type RunId, type SessionId } from "./types/state-types.js";
+import type { Logger } from "./utils.js";
+/**
+ * Complete checkpoint information including git metadata
+ */
+export interface CheckpointInfo {
+    type: "rig-setup" | "completed" | "error" | "skipped";
+    sha: string;
+    message: string;
+    timestamp: string;
+    branch: string;
+}
+/**
+ * A codon with its complete context
+ */
+export interface ThreadCodon {
+    codon: CodonExecution;
+    runId: RunId;
+    runStatus: "running" | "completed" | "failed" | "crashed";
+    runStartTime: string;
+    runEndTime: string | null;
+    gitBranch: string;
+    globalIndex: number;
+    runIndex: number;
+    codonIndexInRun: number;
+    validatedCheckpoints: CheckpointInfo[];
+    continuationSessionId: SessionId | null;
+}
+/**
+ * Complete execution thread
+ */
+export declare class ExecutionThread {
+    codons: ThreadCodon[];
+    totalRuns: number;
+    hasRunningCodon: boolean;
+    nextCodonId: CodonId | null;
+    constructor(codons?: ThreadCodon[], totalRuns?: number, hasRunningCodon?: boolean, nextCodonId?: CodonId | null);
+    /**
+     * Check if the execution thread is in a failed state.
+     *
+     * The thread is considered failed only if:
+     * 1. The most recent codon explicitly has status "failed"
+     * 2. OR the run crashed/failed while a codon was still running (non-terminal state)
+     *
+     * Historical runs being marked as "failed" (e.g., due to server shutdown after
+     * successful codon completion) should NOT cause the thread to be considered failed.
+     */
+    get failed(): boolean;
+}
+/**
+ * Analyze execution history to build a unified thread with all metadata.
+ *
+ * @param state - The complete Hankweave state (including executionPlan)
+ * @param checkpointData - Map of SHA to git checkpoint data (optional)
+ * @param targetRunId - Specific run to analyze (defaults to latest)
+ * @param logger - Optional logger for debugging
+ * @returns Complete execution thread with all metadata preserved
+ */
+export declare function analyzeExecutionThread(state: HankweaveState, checkpointData?: Map<string, {
+    message: string;
+    timestamp: string;
+    branch: string;
+}>, targetRunId?: RunId, logger?: Logger): Promise<ExecutionThread>;
+/**
+ * Get the next codon to execute from a thread
+ */
+export declare function getNextCodonId(thread: ExecutionThread): CodonId | null;
+/**
+ * Find session ID for continuing a specific codon
+ */
+export declare function findContinuationSessionId(thread: ExecutionThread, codonId: CodonId, state: HankweaveState): SessionId | null;

package/dist/exports/schemas.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public schema exports for external consumers (e.g., hw-tracing).
+ *
+ * Exports Zod schemas and inferred TypeScript types for:
+ * - Server events (events.jsonl)
+ * - Per-codon log messages (claude session JSONL)
+ */
+export { type AssistantActionEvent, assistantActionEventDataSchema, assistantActionEventSchema, type BudgetSummaryEvent, budgetSummaryEventSchema, type CodonCompletedEvent, type CodonExtendedEvent, type CodonStartedEvent, codonCompletedEventDataSchema, codonCompletedEventSchema, codonExtendedEventSchema, codonStartedEventDataSchema, codonStartedEventSchema, type ErrorEvent, errorEventSchema, type FileUpdatedEvent, fileUpdatedEventSchema, type InfoEvent, infoEventSchema, isAgenticBackboneEvent, isConnectionStateEvent, isSentinelEvent, isServerStateEvent, type LoopIterationCompletedEvent, loopIterationCompletedEventDataSchema, loopIterationCompletedEventSchema, type RigOutputEvent, type RigSetupCompletedEvent, type RigSetupFailedEvent, rigOutputEventSchema, rigSetupCompletedEventDataSchema, rigSetupCompletedEventSchema, rigSetupFailedEventDataSchema, rigSetupFailedEventSchema, type SentinelErrorEvent, type SentinelLoadedEvent, type SentinelOutputEvent, type SentinelTriggeredEvent, type SentinelUnloadedEvent, type ServerEvent, type ServerReadyEvent, sentinelErrorEventSchema, sentinelLoadedEventDataSchema, sentinelLoadedEventSchema, sentinelOutputEventDataSchema, sentinelOutputEventSchema, sentinelTriggeredEventSchema, sentinelUnloadedEventDataSchema, sentinelUnloadedEventSchema, serverEventSchema, serverReadyEventSchema, type TokenUsageEvent, type ToolResultEvent, tokenUsageEventDataSchema, tokenUsageEventSchema, toolResultEventDataSchema, toolResultEventSchema, } from "../schemas/event-schemas.js";
+export { type AssistantMessage, assistantMessageSchema, type LogMessage, logMessageSchema, messageContentSchema, type ResultMessage, resultMessageSchema, type SystemMessage, systemMessageSchema, type TextContent, type ThinkingContent, type ToolResultContent, type ToolUseContent, textContentSchema, thinkingContentSchema, toolResultContentSchema, toolUseContentSchema, type UserMessage, userMessageSchema, } from "../types/claude-session-schema.js";