hankweave 0.5.7 → 0.6.2

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

@@ -0,0 +1,86 @@
+/**
+ * Strongly typed tool input definitions for Claude tools.
+ * These match the expected input schemas for each tool.
+ *
+ * NOTE: This is not an exhaustive list. Claude may use additional tools
+ * that are not defined here. The server handles unknown tools gracefully
+ * by passing them through in events without type validation.
+ */
+export interface WriteToolInput {
+    file_path: string;
+    content: string;
+}
+export interface ReadToolInput {
+    file_path: string;
+}
+export interface EditToolInput {
+    file_path: string;
+    old_str: string;
+    new_str: string;
+    view_range?: [number, number];
+}
+export interface MultiEditToolInput {
+    file_path: string;
+    edits: Array<{
+        old_str: string;
+        new_str: string;
+        view_range?: [number, number];
+    }>;
+}
+export interface LSToolInput {
+    path: string;
+}
+export interface GlobToolInput {
+    pattern: string;
+}
+export interface GrepToolInput {
+    pattern: string;
+    path?: string;
+}
+export interface BashToolInput {
+    command: string;
+    description?: string;
+}
+export interface TaskToolInput {
+    title: string;
+    description?: string;
+}
+export interface NotebookReadToolInput {
+    path: string;
+}
+export interface NotebookEditToolInput {
+    path: string;
+    cell_index: number;
+    new_content: string;
+}
+export interface WebFetchToolInput {
+    url: string;
+}
+export interface WebSearchToolInput {
+    query: string;
+}
+export interface TodoWriteToolInput {
+    content: string;
+}
+export type ToolInputMap = {
+    Write: WriteToolInput;
+    Read: ReadToolInput;
+    Edit: EditToolInput;
+    MultiEdit: MultiEditToolInput;
+    LS: LSToolInput;
+    Glob: GlobToolInput;
+    Grep: GrepToolInput;
+    Bash: BashToolInput;
+    Task: TaskToolInput;
+    NotebookRead: NotebookReadToolInput;
+    NotebookEdit: NotebookEditToolInput;
+    WebFetch: WebFetchToolInput;
+    WebSearch: WebSearchToolInput;
+    TodoWrite: TodoWriteToolInput;
+    exit_plan_mode: Record<string, never>;
+};
+export type ToolName = keyof ToolInputMap;
+/**
+ * Type guard to check if a tool name is valid
+ */
+export declare function isValidToolName(name: string): name is ToolName;

package/dist/types/types.d.ts

@@ -0,0 +1,367 @@
+import type { z } from "zod";
+import type { ServerEvent } from "../schemas/event-schemas.js";
+import type { CodonId } from "./branded-types.js";
+import type { logMessageSchema } from "./claude-session-schema.js";
+import type { SentinelConfig } from "./sentinel-types.js";
+export type { Codon, CodonConfig, HankFile, HankMeta, HankOverrides, HankweaveConfig, Loop, LoopTermination, RigSetupItem, RigShellCommand, RuntimeConfig, ShellCommand, } from "../config.js";
+export type ModelName = "sonnet" | "opus" | (string & {});
+export type ContinuationMode = "fresh" | "continue-previous";
+/**
+ * Client access modes for different capabilities
+ */
+export declare enum ClientMode {
+    READONLY = "readonly",
+    READANDWRITE = "readandwrite"
+}
+/**
+ * Cursor for paginating through event history
+ */
+export interface EventCursor {
+    timestamp: string;
+    eventId: string;
+}
+/**
+ * Direction for pagination through event history
+ */
+export type PaginationDirection = "forward" | "backward";
+/**
+ * Handshake request sent by client to establish connection mode
+ */
+export interface HandshakeRequest {
+    type: "handshake";
+    data: {
+        mode: ClientMode;
+        sendPreviousEvents?: boolean;
+    };
+}
+/**
+ * Handshake response sent by server after processing request
+ */
+export interface HandshakeResponse {
+    type: "handshake.response";
+    data: {
+        clientId: string;
+        mode: ClientMode;
+        eventHistory: ServerEvent[];
+        totalEvents: number;
+    };
+}
+/**
+ * Client metadata stored with each WebSocket connection.
+ * Provides connection tracking and activity monitoring.
+ */
+export type ClientData = {
+    id: string;
+    connectionTime: Date;
+    lastActivity: Date;
+    handshakeComplete: false;
+} | {
+    id: string;
+    connectionTime: Date;
+    lastActivity: Date;
+    mode: ClientMode;
+    handshakeComplete: true;
+};
+export type ClaudeMessageId = `msg_${string}`;
+export type UUIDMessageId = string;
+export type MessageId = ClaudeMessageId | UUIDMessageId;
+export declare const CHECKPOINT_STATUS: {
+    readonly RIG_SETUP: "rig-setup";
+    readonly COMPLETED: "completed";
+    readonly ERROR: "error";
+    readonly EXIT: "exit";
+    readonly SKIPPED: "skipped";
+};
+export type CheckpointStatus = (typeof CHECKPOINT_STATUS)[keyof typeof CHECKPOINT_STATUS];
+/**
+ * Single codon configuration - represents one executable codon.
+ * Codon-level sentinel entry.
+ * Wraps sentinel config with codon-specific settings.
+ *
+ * This separation keeps sentinel configs reusable across codons
+ * while allowing codon-specific configuration.
+ */
+export interface CodonSentinelEntry {
+    /**
+     * Sentinel configuration.
+     * Can be:
+     * - File path (string): "./sentinels/narrator.json"
+     * - Inline config (object): Full SentinelConfig
+     */
+    sentinelConfig: string | SentinelConfig;
+    /**
+     * Codon-specific settings for this sentinel.
+     */
+    settings?: {
+        /**
+         * Fail the codon if this sentinel fails to load.
+         *
+         * IMPORTANT: This only affects LOAD-TIME failures (config errors, file not found, etc).
+         * Does NOT fail the codon if:
+         * - Sentinel needs to be unloaded mid-execution (due to errors)
+         * - Sentinel LLM calls fail (those are handled by error thresholds)
+         * - Sentinel queue overflows
+         *
+         * Use for mission-critical sentinels where codon cannot proceed without them.
+         * Default: false (sentinels are optional)
+         */
+        failCodonIfNotLoaded?: boolean;
+        /**
+         * Output file paths for this sentinel in this codon.
+         * If omitted, sentinel auto-generates paths in .hankweave/sentinel-outputs/
+         * You can use filenames to join together logs from different sentinels.
+         * Path convention:
+         * - Filename only (no '/'): .hankweave/sentinel-outputs/{id}/{filename}
+         * - Path with '/': {executionPath}/{path}
+         */
+        outputPaths?: {
+            logFile?: string;
+            lastValueFile?: string;
+        };
+        /**
+         * Override sentinel's reportToWebsocket settings for this codon.
+         * Codon-level settings take precedence over sentinel-level settings.
+         *
+         * Controls which sentinel events are emitted to the WebSocket stream:
+         * - lifecycle: sentinel.loaded, sentinel.unloaded (default: true)
+         * - errors: sentinel.error events (default: true)
+         * - outputs: sentinel.output events with full content (default: true)
+         * - triggers: sentinel.triggered events (default: false - verbose)
+         *
+         * Example: Disable verbose output events for this codon only:
+         * ```json
+         * "reportToWebsocket": { "outputs": false, "triggers": false }
+         * ```
+         */
+        reportToWebsocket?: {
+            lifecycle?: boolean;
+            errors?: boolean;
+            outputs?: boolean;
+            triggers?: boolean;
+        };
+    };
+}
+/**
+ * Information for creating a checkpoint commit in the shadow git repository.
+ *
+ * The checkpoint system creates a shadow git repo in `.hankweave/checkpoints/` that tracks
+ * files matching the `checkpointAndWatch` patterns. Each checkpoint creates a commit
+ * with detailed metadata about the codon state.
+ */
+export interface CheckpointInfo {
+    /** The type of checkpoint being created */
+    status: CheckpointStatus;
+    /** Unique identifier of the codon (e.g., "codon-1") */
+    codonId: CodonId;
+    /** Human-readable name of the codon */
+    codonName: string;
+    /** Unique identifier for this Hankweave runtime run */
+    runId: string;
+    /** ISO timestamp when the checkpoint was created */
+    timestamp: string;
+    /** Duration in milliseconds (only for completed/error/skipped codons) */
+    duration?: number;
+}
+/**
+ * Token usage tracking for Claude API calls.
+ * Used to calculate costs and monitor usage across codons.
+ */
+export interface TokenUsage {
+    /** Standard input tokens processed */
+    inputTokens: number;
+    /** Generated output tokens */
+    outputTokens: number;
+    /** Tokens used to create prompt cache */
+    cacheCreationTokens: number;
+    /** Tokens read from existing cache */
+    cacheReadTokens: number;
+}
+/**
+ * Individual check result from a shim's self-test.
+ * Each check verifies a specific aspect of the environment setup.
+ */
+export interface ShimSelfTestCheck {
+    /** Name of the check (e.g., "gemini_cli_found", "api_key") */
+    name: string;
+    /** Whether this check passed */
+    passed: boolean;
+    /** Human-readable message describing the check result */
+    message: string;
+}
+/**
+ * Complete self-test result from a shim.
+ * Shims use --self-test flag to verify their environment is properly configured.
+ */
+export interface ShimSelfTestResult {
+    /** Information about the shim itself */
+    shim: {
+        /** Name of the shim (e.g., "gemini-cli-shim") */
+        name: string;
+        /** Version of the shim */
+        version: string;
+    };
+    /** Information about the underlying agent/CLI */
+    agent: {
+        /** Name of the agent (e.g., "gemini-cli") */
+        name: string;
+        /** Version of the agent (or "unknown" if not found) */
+        version: string;
+        /** Whether the agent was found in the system */
+        found: boolean;
+    };
+    /** Array of individual check results */
+    checks: ShimSelfTestCheck[];
+    /** Overall test result */
+    overall: {
+        /** Whether all checks passed */
+        passed: boolean;
+        /** Overall status message */
+        message: string;
+    };
+}
+/**
+ * Synthetic timeout message structure.
+ * Claude sends these special messages when API requests time out.
+ * They have a specific structure that needs special handling.
+ */
+export interface SyntheticTimeoutMessage {
+    type: "assistant";
+    message: {
+        id: string;
+        type: "message";
+        role: "assistant";
+        model: "<synthetic>";
+        content: "API Error: Request timed out.";
+        usage?: never;
+        stop_reason: null;
+        stop_sequence: null;
+    };
+}
+/**
+ * Type guard to check if an assistant message is a synthetic timeout.
+ * These messages need special handling as they indicate API failures.
+ */
+export declare function isSyntheticTimeout(msg: ClaudeLogMessage): msg is SyntheticTimeoutMessage;
+/**
+ * Type guard to check if a log message indicates a context exceeded error.
+ * Detects two patterns:
+ * - Pattern 1: Synthetic assistant message with "API Error: terminated" or output token maximum exceeded
+ * - Pattern 2: Result message with "exceeded the...output token maximum"
+ */
+export declare function isContextExceeded(msg: ClaudeLogMessage): boolean;
+export type ClaudeLogMessage = z.infer<typeof logMessageSchema>;
+export type { AssistantActionEvent, BudgetSummaryEvent, CheckpointListEvent, CheckpointQueryInfo, CodonCompletedEvent, CodonExecution, CodonStartedEvent, ErrorEvent, FailureReason, FileNode, FileTreeUpdatedEvent, FileUpdatedEvent, HistoryBatchEvent, IncompleteCodonEvent, InfoEvent, ProcessExit, RollbackCodonCheckpointEvent, RollbackCompletedEvent, RollbackProgressEvent, RollbackRigCleanupEvent, RollbackStartedEvent, ServerEvent, ServerIdleEvent, ServerReadyEvent, StateSnapshotEvent, TokenUsageEvent, ToolResultEvent, } from "../schemas/event-schemas.js";
+/**
+ * Start a specific codon by ID.
+ * Can optionally skip pre-start commands for retry scenarios.
+ */
+export interface StartCodonCommand {
+    /** Unique ID for this command (for request/response correlation) */
+    id: string;
+    type: "codon.start";
+    data: {
+        /** ID of the codon to start */
+        codonId: string;
+        /** If true, skip the codon's preStart command */
+        skipPreCommands?: boolean;
+    };
+}
+/**
+ * Start the next codon in sequence.
+ * Determines next codon based on completion history.
+ */
+export interface NextCodonCommand {
+    id: string;
+    type: "codon.next";
+}
+/**
+ * Skip the currently running codon.
+ * Terminates the Claude process and marks codon as skipped.
+ */
+export interface SkipCodonCommand {
+    id: string;
+    type: "codon.skip";
+}
+/**
+ * Re-run the last completed codon.
+ * Useful for retrying failed codons or regenerating outputs.
+ */
+export interface RedoCodonCommand {
+    id: string;
+    type: "codon.redo";
+}
+/**
+ * Gracefully shutdown the server.
+ * Cleans up all resources and removes lock file.
+ */
+export interface ShutdownCommand {
+    id: string;
+    type: "server.shutdown";
+}
+/**
+ * Force stop the current running codon.
+ */
+export interface ForceStopCommand {
+    id: string;
+    type: "codon.forceStop";
+    data?: {
+        /** Optional reason for force stopping */
+        reason?: string;
+    };
+}
+/**
+ * List available checkpoints.
+ */
+export interface ListCheckpointsCommand {
+    id: string;
+    type: "checkpoint.list";
+    data?: {
+        /** Optional run ID to list checkpoints for */
+        runId?: string;
+    };
+}
+/**
+ * Rollback to a specific checkpoint.
+ */
+export interface RollbackToCheckpointCommand {
+    id: string;
+    type: "rollback.toCheckpoint";
+    data: {
+        /** Checkpoint SHA (can be partial) */
+        checkpointSha: string;
+        /** Whether to auto-restart after rollback */
+        autoRestart?: boolean;
+    };
+}
+/**
+ * Rollback to a codon with specific checkpoint type.
+ */
+export interface RollbackToCodonCommand {
+    id: string;
+    type: "rollback.toCodon";
+    data: {
+        /** Codon ID to rollback to */
+        codonId: string;
+        /** Checkpoint type within that codon */
+        checkpointType: "start" | "end" | "rig-setup" | "completed" | "error" | "skipped";
+        /** Whether to auto-restart after rollback */
+        autoRestart?: boolean;
+    };
+}
+/**
+ * Rollback to last successful codon.
+ */
+export interface RollbackToLastSuccessCommand {
+    id: string;
+    type: "rollback.toLastSuccess";
+    data?: {
+        /** Whether to auto-restart after rollback */
+        autoRestart?: boolean;
+    };
+}
+/**
+ * Discriminated union of all client-to-server command types.
+ * Use this instead of generic command interfaces for better type safety.
+ * TypeScript will automatically narrow the type based on the `type` field.
+ */
+export type ClientCommand = StartCodonCommand | NextCodonCommand | SkipCodonCommand | RedoCodonCommand | ShutdownCommand | ForceStopCommand | ListCheckpointsCommand | RollbackToCheckpointCommand | RollbackToCodonCommand | RollbackToLastSuccessCommand;

package/dist/types/websocket-log-types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @deprecated This file is deprecated. Use server/schemas/websocket-log-schemas.ts instead.
+ *
+ * Re-exports from the new Zod-based schema file for backward compatibility.
+ */
+export type { ClientCommand, ServerEvent } from "../schemas/event-schemas.js";
+export { extractMessageContext, getMessageType, isClientCommand, isServerEvent, parseWebSocketLogEntry, safeParseWebSocketLogEntry, type WebSocketLogEntry, webSocketLogEntrySchema, } from "../schemas/websocket-log-schemas.js";