hankweave 0.5.7 → 0.6.2

package/dist/shims/pi/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pi-shim",
+  "version": "1.0.0",
+  "description": "Shim package for the embedded Pi coding agent SDK",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "pi-shim": "./index.js"
+  },
+  "main": "./index.js",
+  "files": [
+    "README.md",
+    "bun.lock",
+    "tsconfig.json",
+    "index.js",
+    "dist",
+    "src",
+    "common",
+    "docs",
+    "tests",
+    "rebuild.sh",
+    "VERSION",
+    "THIRDPARTY.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target node --bundle && node -e \"const fs=require('fs');const p='dist/index.js';let c=fs.readFileSync(p,'utf8');c=c.replace(/^#!.*\\n/,'');fs.writeFileSync(p,'#!/usr/bin/env node\\n'+c);fs.chmodSync(p,0o755);fs.copyFileSync(p,'index.js');fs.chmodSync('index.js',0o755);\"",
+    "dev": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "bun test",
+    "rebuild": "./rebuild.sh",
+    "self-test": "node index.js --self-test"
+  },
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.57.1",
+    "@shims/common": "file:./common"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "shim",
+    "pi",
+    "coding-agent",
+    "hankweave"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.1.0"
+  }
+}

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;

package/dist/telemetry/telemetry-types.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Telemetry Types and Schemas
+ *
+ * Privacy-preserving types for telemetry events.
+ * All types follow the principle: content → size, paths → counts, IDs → hashes.
+ */
+import { z } from "zod";
+export declare const TELEMETRY_SCHEMA_VERSION = 1;
+export interface PrivacyPreservingCodon {
+    type: "codon";
+    position: number;
+    id_hash: string;
+    prompt: {
+        source: "inline" | "file" | "files";
+        length_chars?: number;
+        file_count?: number;
+        total_size_bytes?: number;
+    };
+    system_prompt: {
+        source: "inline" | "file" | "files";
+        length_chars?: number;
+        file_count?: number;
+        total_size_bytes?: number;
+    } | null;
+    description: {
+        present: boolean;
+        length_chars: number;
+    } | null;
+    model: string;
+    continuation_mode: "fresh" | "continue-previous";
+    checkpointed_files: {
+        pattern_count: number;
+    } | null;
+    env_vars: {
+        count: number;
+    } | null;
+    rig_setup: {
+        operation_count: number;
+        operations: Array<{
+            type: "command" | "copy";
+        }>;
+    } | null;
+    sentinels: {
+        count: number;
+        sources: Array<"inline" | "file">;
+    } | null;
+    output_files: {
+        count: number;
+    } | null;
+}
+export interface PrivacyPreservingLoop {
+    type: "loop";
+    position: number;
+    id_hash: string;
+    description: {
+        present: boolean;
+        length_chars: number;
+    } | null;
+    termination: {
+        type: "iterationLimit" | "contextExceeded";
+        limit?: number;
+    };
+    codons: PrivacyPreservingCodon[];
+}
+export type PrivacyPreservingHankItem = PrivacyPreservingCodon | PrivacyPreservingLoop;
+export interface PrivacyPreservingHank {
+    hank_hash: string;
+    items: PrivacyPreservingHankItem[];
+    summary: {
+        total_items: number;
+        total_codons: number;
+        loop_count: number;
+        models_used: string[];
+        has_sentinels: boolean;
+        has_checkpointing: boolean;
+        has_rig_setup: boolean;
+        has_custom_env: boolean;
+        total_prompt_chars: number;
+        total_prompt_files: number;
+        total_prompt_file_bytes: number;
+    };
+}
+export interface PrivacyPreservingTokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+}
+export interface PrivacyPreservingCodonExecution {
+    position: number;
+    codon_id_hash: string;
+    loop_context: {
+        loop_id_hash: string;
+        iteration: number;
+        position_in_loop: number;
+    } | null;
+    status: string;
+    start_time: string;
+    end_time?: string;
+    duration_ms?: number;
+    failure?: {
+        failed_during: string;
+        failure_type: string;
+        retriable: boolean;
+        exit_code?: number;
+    };
+    skipped?: {
+        skipped_during: string;
+    };
+    tokens: PrivacyPreservingTokenUsage;
+    cost_usd: number;
+    assistant_message_count?: number;
+    sentinels: {
+        count: number;
+        total_cost_usd: number;
+        total_triggers: number;
+        total_llm_calls: number;
+        failed_llm_calls: number;
+        models_used: string[];
+    } | null;
+    has_rig_setup_checkpoint: boolean;
+    has_completion_checkpoint: boolean;
+    has_error_checkpoint: boolean;
+    has_skip_checkpoint: boolean;
+}
+export interface PrivacyPreservingRun {
+    run_id_hash: string;
+    start_time: string;
+    end_time?: string;
+    duration_ms?: number;
+    duration_bucket: "<1m" | "1-5m" | "5-15m" | "15m+";
+    status: "running" | "completed" | "failed" | "crashed";
+    starting_conditions: {
+        type: "fresh" | "continuation";
+        reason?: "retry" | "rollback" | "continue";
+    };
+    codons: PrivacyPreservingCodonExecution[];
+    metrics: {
+        total_codons: number;
+        codons_completed: number;
+        codons_failed: number;
+        codons_skipped: number;
+        total_cost_usd: number;
+        total_tokens: PrivacyPreservingTokenUsage;
+        total_checkpoints: number;
+        total_rollbacks: number;
+        total_sentinels_loaded: number;
+        total_sentinel_cost_usd: number;
+        total_sentinel_triggers: number;
+        total_sentinel_llm_calls: number;
+    };
+}
+export interface PrivacyPreservingProvider {
+    provider_id: string;
+    shim?: {
+        name: string;
+        version: string;
+    };
+    agent: {
+        name: string;
+        version: string;
+        found: boolean;
+    };
+    self_test?: {
+        passed: boolean;
+        check_count: number;
+        passed_count: number;
+    };
+}
+/** Common fields included in every event via PostHog $set */
+export interface TelemetryUserProperties {
+    hankweave_version: string;
+    os: string;
+    os_version: string;
+    arch: string;
+    node_version: string;
+    is_ci: boolean;
+    is_compiled: boolean;
+}
+/** All telemetry event names */
+export type TelemetryEventName = "cli_init" | "cli_validate" | "cli_cleanup" | "cli_run" | "cli_help" | "run_started" | "run_completed" | "run_failed" | "run_crashed" | "codon_started" | "codon_completed" | "codon_failed" | "codon_skipped" | "loop_iteration_started" | "loop_iteration_completed" | "rig_setup_completed" | "rig_setup_failed" | "checkpoint_created" | "rollback_completed" | "continuation_started" | "sentinel_triggered" | "budget_set" | "budget_exceeded" | "$ai_generation" | "$ai_trace" | "$ai_span";
+export declare const telemetryConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    debug?: boolean | undefined;
+    enabled?: boolean | undefined;
+    endpoint?: string | undefined;
+}, {
+    debug?: boolean | undefined;
+    enabled?: boolean | undefined;
+    endpoint?: string | undefined;
+}>;
+export type TelemetryConfig = z.infer<typeof telemetryConfigSchema>;
+export interface TelemetryIdentity {
+    clientId: string;
+    createdAt: string;
+    noticeShownAt?: string;
+    firstSuccessAt?: string;
+}
+export interface TelemetryEvent {
+    event: TelemetryEventName;
+    properties: Record<string, unknown>;
+    timestamp: string;
+}

package/dist/typed-event-emitter.d.ts

@@ -0,0 +1,57 @@
+import type { CodonId, RunId } from "./types/branded-types.js";
+import type { CodonStatus, StateTransition } from "./types/state-types.js";
+import type { ServerEvent } from "./types/types.js";
+/**
+ * Type-safe wrapper around Node's EventEmitter.
+ * Ensures event names and argument types are consistent at compile time.
+ */
+export declare class TypedEventEmitter<T extends Record<string, unknown[]>> {
+    private emitter;
+    on<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+    off<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+    emit<K extends keyof T>(event: K, ...args: T[K]): boolean;
+    once<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+    removeAllListeners<K extends keyof T>(event?: K): this;
+    addListener<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+    removeListener<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+    setMaxListeners(n: number): this;
+    getMaxListeners(): number;
+    listeners(event: keyof T): Function[];
+    rawListeners(event: keyof T): Function[];
+    eventNames(): (string | symbol)[];
+    listenerCount(event: keyof T): number;
+    prependListener<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+    prependOnceListener<K extends keyof T>(event: K, listener: (...args: T[K]) => void): this;
+}
+export interface ServerInternalEvents {
+    event: [ServerEvent];
+    exit: [code: number];
+    error: [error: Error];
+    stdout: [data: string];
+    stderr: [data: string];
+    [key: string]: unknown[];
+}
+export interface ProcessEvents {
+    exit: [code: number, isContextExceeded: boolean];
+    error: [error: Error];
+    stdout: [data: string];
+    stderr: [data: string];
+    [key: string]: unknown[];
+}
+export interface StateManagerEvents {
+    stateChanged: [StateTransition];
+    codonRunning: [
+        {
+            runId: RunId;
+            codonId: CodonId;
+            from: CodonStatus;
+            to: "running";
+            metadata?: Record<string, unknown>;
+        }
+    ];
+    transitionError: [{
+        event: StateTransition;
+        error: Error;
+    }];
+    [key: string]: unknown[];
+}

package/dist/types/branded-types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Branded types for type safety and clarity
+ */
+type Branded<T, Brand> = T & {
+    __brand: Brand;
+};
+export type CodonId = Branded<string, "CodonId">;
+export declare const CodonId: (id: string) => CodonId;
+export type SessionId = Branded<string, "SessionId">;
+export declare const SessionId: (id: string) => SessionId;
+export type RunId = Branded<string, "RunId">;
+export declare const RunId: (id: string) => RunId;
+export type EventId = Branded<string, "EventId">;
+export declare const EventId: (id: string) => EventId;
+export {};

package/dist/types/budget-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared budget types used across the codebase.
+ *
+ * These types are consumed by state management, event schemas, CodonRunner,
+ * and the budget module itself.
+ */
+/** What happens when a budget limit is exceeded. */
+export type OnExceededPolicy = "complete" | "fail";
+/** Options for constructing a BudgetLimits instance. */
+export interface BudgetLimitsOptions {
+    maxDollars?: number;
+    maxTimeSeconds?: number;
+    maxOutputTokens?: number;
+    maxContextTokens?: number;
+    onExceeded?: OnExceededPolicy;
+    /** Human-readable description of where the cost limit came from. */
+    costSource?: string;
+}
+/**
+ * Resolved budget limits for a single codon execution.
+ */
+export declare class BudgetLimits {
+    readonly maxDollars?: number;
+    readonly maxTimeSeconds?: number;
+    readonly maxOutputTokens?: number;
+    readonly maxContextTokens?: number;
+    readonly onExceeded?: OnExceededPolicy;
+    /** Human-readable description of where the cost limit came from. */
+    readonly costSource?: string;
+    constructor(opts?: BudgetLimitsOptions);
+    /** Whether any numeric limits are configured. */
+    hasLimits(): boolean;
+}
+/** The budget currencies tracked by the system. */
+export declare const BUDGET_CURRENCIES: readonly ["cost", "duration", "outputTokens", "contextTokens"];
+export type BudgetCurrency = (typeof BUDGET_CURRENCIES)[number];
+/** Snapshot of a budget limit breach — which currency, what limit, how much was used. */
+export interface BudgetExceededData {
+    currency: BudgetCurrency;
+    limit: number;
+    used: number;
+}
+/** Full info about a budget breach, including a human-readable message. */
+export interface BudgetExceededInfo extends BudgetExceededData {
+    message: string;
+}
+/** How budget is distributed among codons in a container. */
+export type AllocationMode = "shared" | "proportional" | "proportional-strict";
+/** Per-codon row in the end-of-run budget summary table. */
+export interface CodonBudgetSummaryRow {
+    codonId: string;
+    loopContext?: {
+        loopId: string;
+        iteration: number;
+        codonIndexInLoop: number;
+    };
+    status: "completed" | "failed" | "skipped" | "exceeded" | "running";
+    budget: {
+        maxDollars?: number;
+        maxTimeSeconds?: number;
+        maxOutputTokens?: number;
+    };
+    actual: {
+        dollars: number;
+        timeSeconds: number;
+        outputTokens: number;
+    };
+}
+/** Full payload for the budget.summary event emitted at end of run. */
+export interface BudgetSummaryData {
+    ceiling: {
+        maxDollars?: number;
+        maxTimeSeconds?: number;
+    };
+    allocation: AllocationMode;
+    rows: CodonBudgetSummaryRow[];
+    totals: {
+        budgetDollars?: number;
+        actualDollars: number;
+        actualTimeSeconds: number;
+    };
+}