hankweave 0.6.1 → 0.6.2

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