whale-code 6.4.0

package/dist/cli/services/hooks.js

@@ -0,0 +1,258 @@
+/**
+ * Hooks System — shell commands that run before/after tool calls and at session lifecycle events.
+ *
+ * Hooks are configured in:
+ *   - Project: .whale/hooks.json (array of HookConfig)
+ *   - User: ~/.swagmanager/hooks.json (array of HookConfig)
+ *
+ * Both are loaded and merged (project hooks run first).
+ *
+ * Hook process receives JSON on stdin:
+ *   { event, tool_name?, tool_input?, tool_output?, tool_success?, session_id? }
+ *
+ * Hook process may output JSON on stdout:
+ *   { allow?: boolean, message?: string, modified_input?: object, modified_output?: string }
+ *
+ * If allow: false, the tool call is blocked and message is returned as the tool result.
+ * If hook exits non-zero, it is logged as a warning but does not crash the session.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+const DEFAULT_TIMEOUT_MS = 10_000;
+// ============================================================================
+// GLOB MATCHING
+// ============================================================================
+/**
+ * Match a tool name against a simple glob pattern.
+ * Supports * (any chars) and ? (single char).
+ */
+export function matchGlob(pattern, name) {
+    // Escape regex special chars except * and ?
+    const regex = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${regex}$`).test(name);
+}
+// ============================================================================
+// LOAD HOOKS
+// ============================================================================
+const VALID_EVENTS = [
+    "BeforeTool",
+    "AfterTool",
+    "SessionStart",
+    "SessionEnd",
+    "Notification",
+];
+/**
+ * Load hooks from project (.whale/hooks.json) and user (~/.swagmanager/hooks.json).
+ * Project hooks come first in the array, then user hooks.
+ * Invalid files are skipped with a warning.
+ */
+export function loadHooks(cwd) {
+    const hooks = [];
+    // Project hooks (higher priority, run first)
+    const projectPath = join(cwd, ".whale", "hooks.json");
+    const projectHooks = loadHooksFromFile(projectPath);
+    if (projectHooks)
+        hooks.push(...projectHooks);
+    // User hooks
+    const userPath = join(homedir(), ".swagmanager", "hooks.json");
+    const userHooks = loadHooksFromFile(userPath);
+    if (userHooks)
+        hooks.push(...userHooks);
+    return hooks;
+}
+function loadHooksFromFile(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            console.error(`[hooks] Warning: ${filePath} should be a JSON array, skipping`);
+            return null;
+        }
+        // Validate each hook config
+        return parsed.filter((h) => {
+            if (!h || typeof h !== "object")
+                return false;
+            const hook = h;
+            if (typeof hook.event !== "string" || typeof hook.command !== "string") {
+                console.error(`[hooks] Warning: Invalid hook in ${filePath}, missing event or command`);
+                return false;
+            }
+            if (!VALID_EVENTS.includes(hook.event)) {
+                console.error(`[hooks] Warning: Invalid event "${hook.event}" in ${filePath}`);
+                return false;
+            }
+            return true;
+        });
+    }
+    catch (err) {
+        console.error(`[hooks] Warning: Failed to parse ${filePath}: ${err instanceof Error ? err.message : err}`);
+        return null;
+    }
+}
+// ============================================================================
+// EXECUTE HOOK
+// ============================================================================
+/**
+ * Execute a hook command with JSON payload on stdin.
+ * Returns parsed JSON response from stdout, or null on error/timeout.
+ */
+export async function executeHook(hook, payload) {
+    const timeout = hook.timeout ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const child = spawn("/bin/sh", ["-c", hook.command], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env },
+        });
+        let timer;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        // Kill on timeout
+        timer = setTimeout(() => {
+            if (!settled) {
+                console.error(`[hooks] Warning: Hook "${hook.command}" timed out after ${timeout}ms, killing`);
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+                settle(null);
+            }
+        }, timeout);
+        child.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        child.on("error", (err) => {
+            console.error(`[hooks] Warning: Hook "${hook.command}" failed to start: ${err.message}`);
+            settle(null);
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                if (stderr) {
+                    console.error(`[hooks] Warning: Hook "${hook.command}" exited with code ${code}: ${stderr.trim()}`);
+                }
+                else {
+                    console.error(`[hooks] Warning: Hook "${hook.command}" exited with code ${code}`);
+                }
+                settle(null);
+                return;
+            }
+            // Parse stdout as JSON
+            const trimmed = stdout.trim();
+            if (!trimmed) {
+                settle(null);
+                return;
+            }
+            try {
+                settle(JSON.parse(trimmed));
+            }
+            catch {
+                // Non-JSON output is not an error, just no structured response
+                settle(null);
+            }
+        });
+        // Write payload to stdin
+        try {
+            child.stdin?.write(JSON.stringify(payload));
+            child.stdin?.end();
+        }
+        catch {
+            // stdin may already be closed — that is fine
+        }
+    });
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Run BeforeTool hooks for a given tool call.
+ * Returns whether the tool call should proceed and optionally modified input.
+ */
+export async function runBeforeToolHook(hooks, toolName, input) {
+    const matching = hooks.filter((h) => h.event === "BeforeTool" &&
+        (!h.pattern || matchGlob(h.pattern, toolName)));
+    if (matching.length === 0)
+        return { allow: true };
+    const payload = {
+        event: "BeforeTool",
+        tool_name: toolName,
+        tool_input: input,
+    };
+    for (const hook of matching) {
+        const response = await executeHook(hook, payload);
+        if (!response)
+            continue;
+        // If any hook blocks, stop immediately
+        if (response.allow === false) {
+            return {
+                allow: false,
+                message: response.message || `Blocked by hook: ${hook.command}`,
+            };
+        }
+        // If hook modifies input and is allowed to
+        if (hook.allowModify && response.modified_input) {
+            return { allow: true, modifiedInput: response.modified_input };
+        }
+    }
+    return { allow: true };
+}
+/**
+ * Run AfterTool hooks for a given tool result.
+ * Returns optionally modified output.
+ */
+export async function runAfterToolHook(hooks, toolName, output, success) {
+    const matching = hooks.filter((h) => h.event === "AfterTool" &&
+        (!h.pattern || matchGlob(h.pattern, toolName)));
+    if (matching.length === 0)
+        return {};
+    const payload = {
+        event: "AfterTool",
+        tool_name: toolName,
+        tool_output: output,
+        tool_success: success,
+    };
+    for (const hook of matching) {
+        const response = await executeHook(hook, payload);
+        if (!response)
+            continue;
+        // If hook modifies output and is allowed to
+        if (hook.allowModify && response.modified_output !== undefined) {
+            return { modifiedOutput: response.modified_output };
+        }
+    }
+    return {};
+}
+/**
+ * Run session lifecycle hooks (SessionStart, SessionEnd, Notification).
+ * Fire-and-forget — errors are logged but don't affect session.
+ */
+export async function runSessionHook(hooks, event, data) {
+    const matching = hooks.filter((h) => h.event === event);
+    if (matching.length === 0)
+        return;
+    const payload = {
+        event,
+        ...(data || {}),
+    };
+    // Run all session hooks concurrently — don't wait or fail
+    await Promise.allSettled(matching.map((hook) => executeHook(hook, payload)));
+}

package/dist/cli/services/interactive-tools.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Interactive Tools — user interaction during agent execution
+ *
+ * - AskUserQuestion: Multi-choice questions with optional custom input
+ * - Plan Mode: Structured planning workflow with user approval
+ */
+import { EventEmitter } from "events";
+export interface QuestionOption {
+    label: string;
+    description: string;
+}
+export interface Question {
+    question: string;
+    header: string;
+    options: QuestionOption[];
+    multiSelect: boolean;
+}
+export interface QuestionRequest {
+    id: string;
+    questions: Question[];
+    resolve: (answers: Record<string, string | string[]>) => void;
+    reject: (error: Error) => void;
+}
+export interface PlanModeState {
+    active: boolean;
+    planFile?: string;
+    planContent?: string;
+    startedAt?: Date;
+}
+export declare const interactiveEvents: EventEmitter<[never]>;
+export declare function createQuestionRequest(questions: Question[]): QuestionRequest;
+export declare function getPendingQuestion(): QuestionRequest | undefined;
+export declare function resolveQuestion(id: string, answers: Record<string, string | string[]>): boolean;
+export declare function rejectQuestion(id: string, error: Error): boolean;
+export declare function enterPlanMode(planFile?: string): {
+    success: boolean;
+    message: string;
+};
+export declare function exitPlanMode(): {
+    success: boolean;
+    message: string;
+};
+export declare function isPlanMode(): boolean;
+export declare function getPlanModeState(): PlanModeState;
+export declare const INTERACTIVE_TOOL_DEFINITIONS: ({
+    name: string;
+    description: string;
+    input_schema: {
+        type: string;
+        properties: {
+            questions: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        question: {
+                            type: string;
+                            description: string;
+                        };
+                        header: {
+                            type: string;
+                            description: string;
+                        };
+                        options: {
+                            type: string;
+                            description: string;
+                            items: {
+                                type: string;
+                                properties: {
+                                    label: {
+                                        type: string;
+                                        description: string;
+                                    };
+                                    description: {
+                                        type: string;
+                                        description: string;
+                                    };
+                                };
+                                required: string[];
+                            };
+                        };
+                        multiSelect: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+            plan_file?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    input_schema: {
+        type: string;
+        properties: {
+            plan_file: {
+                type: string;
+                description: string;
+            };
+            questions?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    input_schema: {
+        type: string;
+        properties: {
+            questions?: undefined;
+            plan_file?: undefined;
+        };
+        required: never[];
+    };
+})[];
+export declare function executeInteractiveTool(name: string, input: Record<string, unknown>): Promise<{
+    success: boolean;
+    output: string;
+    pendingQuestion?: QuestionRequest;
+}>;

package/dist/cli/services/interactive-tools.js

@@ -0,0 +1,260 @@
+/**
+ * Interactive Tools — user interaction during agent execution
+ *
+ * - AskUserQuestion: Multi-choice questions with optional custom input
+ * - Plan Mode: Structured planning workflow with user approval
+ */
+import { EventEmitter } from "events";
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+// ============================================================================
+// GLOBAL STATE
+// ============================================================================
+// Pending question requests (resolved by UI)
+const pendingQuestions = new Map();
+// Plan mode state
+let planModeState = { active: false };
+// Event emitter for UI coordination
+export const interactiveEvents = new EventEmitter();
+// ============================================================================
+// ASK USER QUESTION
+// ============================================================================
+export function createQuestionRequest(questions) {
+    const id = `question-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    return new Promise((resolve, reject) => {
+        const request = {
+            id,
+            questions,
+            resolve,
+            reject,
+        };
+        pendingQuestions.set(id, request);
+        // Emit event for UI to pick up
+        interactiveEvents.emit("question", request);
+    });
+}
+export function getPendingQuestion() {
+    // Return first pending question
+    return pendingQuestions.values().next().value;
+}
+export function resolveQuestion(id, answers) {
+    const request = pendingQuestions.get(id);
+    if (!request)
+        return false;
+    pendingQuestions.delete(id);
+    request.resolve(answers);
+    return true;
+}
+export function rejectQuestion(id, error) {
+    const request = pendingQuestions.get(id);
+    if (!request)
+        return false;
+    pendingQuestions.delete(id);
+    request.reject(error);
+    return true;
+}
+// ============================================================================
+// PLAN MODE
+// ============================================================================
+export function enterPlanMode(planFile) {
+    if (planModeState.active) {
+        return {
+            success: false,
+            message: "Already in plan mode. Use ExitPlanMode to finish planning.",
+        };
+    }
+    planModeState = {
+        active: true,
+        planFile: planFile || ".whale/plan.md",
+        startedAt: new Date(),
+    };
+    interactiveEvents.emit("planModeEntered", planModeState);
+    return {
+        success: true,
+        message: `Entered plan mode. Write your plan to ${planModeState.planFile}, then use ExitPlanMode when ready for approval.`,
+    };
+}
+export function exitPlanMode() {
+    if (!planModeState.active) {
+        return {
+            success: false,
+            message: "Not in plan mode. Use EnterPlanMode first.",
+        };
+    }
+    const planFile = planModeState.planFile || ".whale/plan.md";
+    planModeState = { active: false };
+    interactiveEvents.emit("planModeExited", { planFile });
+    // Read the plan file to display its content
+    const fullPath = resolve(process.cwd(), planFile);
+    let planContent = "";
+    if (existsSync(fullPath)) {
+        try {
+            planContent = readFileSync(fullPath, "utf-8").trim();
+        }
+        catch { /* ignore read errors */ }
+    }
+    if (planContent) {
+        return {
+            success: true,
+            message: planContent,
+        };
+    }
+    return {
+        success: true,
+        message: `Plan mode complete. Plan saved to ${planFile}.`,
+    };
+}
+export function isPlanMode() {
+    return planModeState.active;
+}
+export function getPlanModeState() {
+    return { ...planModeState };
+}
+// ============================================================================
+// TOOL DEFINITIONS
+// ============================================================================
+export const INTERACTIVE_TOOL_DEFINITIONS = [
+    {
+        name: "ask_user_question",
+        description: `Ask the user questions during execution. Use this to:
+- Gather user preferences or requirements
+- Clarify ambiguous instructions
+- Get decisions on implementation choices
+- Offer choices about direction
+
+Users can always select "Other" to provide custom input.`,
+        input_schema: {
+            type: "object",
+            properties: {
+                questions: {
+                    type: "array",
+                    description: "1-4 questions to ask the user",
+                    items: {
+                        type: "object",
+                        properties: {
+                            question: {
+                                type: "string",
+                                description: "The complete question to ask (ends with ?)",
+                            },
+                            header: {
+                                type: "string",
+                                description: "Short label (max 12 chars) like 'Auth method' or 'Library'",
+                            },
+                            options: {
+                                type: "array",
+                                description: "2-4 choices (Other is added automatically)",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        label: {
+                                            type: "string",
+                                            description: "Concise choice text (1-5 words)",
+                                        },
+                                        description: {
+                                            type: "string",
+                                            description: "Explanation of what this choice means",
+                                        },
+                                    },
+                                    required: ["label", "description"],
+                                },
+                            },
+                            multiSelect: {
+                                type: "boolean",
+                                description: "Allow selecting multiple options (default: false)",
+                            },
+                        },
+                        required: ["question", "header", "options"],
+                    },
+                },
+            },
+            required: ["questions"],
+        },
+    },
+    {
+        name: "enter_plan_mode",
+        description: `Enter plan mode for complex tasks requiring careful planning before implementation.
+
+Use this when:
+- Multiple valid approaches exist with trade-offs
+- Significant architectural decisions are needed
+- Large-scale changes touch many files
+- Requirements are unclear and need exploration
+- You need to ask clarifying questions before starting
+
+In plan mode, you explore the codebase and design an approach, then present it for user approval before implementing.`,
+        input_schema: {
+            type: "object",
+            properties: {
+                plan_file: {
+                    type: "string",
+                    description: "File to write the plan to (default: .whale/plan.md)",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "exit_plan_mode",
+        description: `Exit plan mode after writing your plan. The user will review and approve the plan before implementation begins.
+
+Only use this after you have:
+1. Thoroughly explored the codebase
+2. Written a clear plan to the plan file
+3. Resolved any ambiguities with the user`,
+        input_schema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+];
+// ============================================================================
+// EXECUTE INTERACTIVE TOOLS
+// ============================================================================
+export async function executeInteractiveTool(name, input) {
+    switch (name) {
+        case "ask_user_question": {
+            const questions = input.questions;
+            if (!Array.isArray(questions) || questions.length === 0) {
+                return { success: false, output: "questions array is required" };
+            }
+            if (questions.length > 4) {
+                return { success: false, output: "Maximum 4 questions allowed" };
+            }
+            // Create the request — UI will handle it
+            const id = `question-${Date.now()}`;
+            const request = {
+                id,
+                questions: questions.map((q) => ({
+                    question: q.question,
+                    header: q.header?.slice(0, 12) || "Question",
+                    options: (q.options || []).slice(0, 4).map((o) => ({
+                        label: o.label,
+                        description: o.description || "",
+                    })),
+                    multiSelect: q.multiSelect || false,
+                })),
+                resolve: () => { },
+                reject: () => { },
+            };
+            // Store for UI to pick up
+            pendingQuestions.set(id, request);
+            interactiveEvents.emit("question", request);
+            return {
+                success: true,
+                output: `Question pending: ${questions[0].question}`,
+                pendingQuestion: request,
+            };
+        }
+        case "enter_plan_mode": {
+            const result = enterPlanMode(input.plan_file);
+            return { success: result.success, output: result.message };
+        }
+        case "exit_plan_mode": {
+            const result = exitPlanMode();
+            return { success: result.success, output: result.message };
+        }
+        default:
+            return { success: false, output: `Unknown interactive tool: ${name}` };
+    }
+}

package/dist/cli/services/keybinding-manager.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Keybinding Manager — configurable keyboard shortcuts
+ *
+ * Loads overrides from ~/.swagmanager/keybindings.json.
+ * Only listed bindings are configurable; Enter, backspace, arrows stay hardcoded.
+ */
+export interface KeybindingConfig {
+    cancel_stream?: string;
+    toggle_expand?: string;
+    toggle_thinking?: string;
+    exit?: string;
+    clear_line?: string;
+    delete_word?: string;
+    home?: string;
+}
+export interface InkKey {
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    escape: boolean;
+    return: boolean;
+    tab: boolean;
+    backspace: boolean;
+    delete: boolean;
+    upArrow: boolean;
+    downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    pageUp: boolean;
+    pageDown: boolean;
+}
+export declare function loadKeybindings(): Required<KeybindingConfig>;
+/**
+ * Check if an Ink useInput event matches a binding string.
+ *
+ * Binding format: "ctrl+<key>", "escape", "meta+<key>", or single char.
+ * Examples: "ctrl+e", "escape", "ctrl+c", "ctrl+t"
+ */
+export declare function matchesBinding(binding: string, input: string, key: Partial<InkKey>): boolean;
+/**
+ * Convert a binding string to a raw control character for stdin matching.
+ * Returns the string as-is if not a ctrl+<key> binding.
+ *
+ * "ctrl+u" -> "\x15"
+ * "ctrl+w" -> "\x17"
+ * "escape" -> "\x1b"
+ */
+export declare function bindingToControlChar(binding: string): string;
+/**
+ * Reset cached keybindings (for testing or hot-reload).
+ */
+export declare function resetKeybindingCache(): void;