@n-dx/core 0.1.0

package/packages/hench/dist/agent/analysis/review.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Review mode — shows proposed changes and prompts for approval
+ * before committing task completion.
+ *
+ * The review gate sits between completion validation (changes exist,
+ * tests pass) and status updates (marking the task complete). When
+ * `--review` is active, the user sees a full diff and can approve
+ * or reject the agent's work.
+ */
+export interface ReviewResult {
+    approved: boolean;
+    /** Reason for rejection, if rejected. */
+    reason?: string;
+}
+export interface ReviewDiff {
+    /** Full diff output (git diff HEAD). */
+    diff: string;
+    /** Summary stat line (git diff --stat HEAD). */
+    stat: string;
+}
+/**
+ * Collect the current diff for review.
+ */
+export declare function collectReviewDiff(projectDir: string, timeout?: number): Promise<ReviewDiff>;
+/**
+ * Display the review UI and prompt for approval.
+ *
+ * Shows:
+ * 1. Diff stat summary
+ * 2. Full diff
+ * 3. Approve/reject prompt
+ *
+ * The `promptFn` parameter allows injection for testing.
+ */
+export declare function promptReview(reviewDiff: ReviewDiff, promptFn?: (question: string) => Promise<string>): Promise<ReviewResult>;
+/**
+ * Revert all uncommitted changes in the working tree.
+ * Used when the reviewer rejects the agent's work.
+ */
+export declare function revertChanges(projectDir: string, timeout?: number): Promise<void>;

package/packages/hench/dist/agent/analysis/review.js

@@ -0,0 +1,66 @@
+import { createInterface } from "node:readline";
+import { execStdout } from "../../process/index.js";
+import { section, subsection, info } from "../../types/output.js";
+const DEFAULT_TIMEOUT = 30_000;
+/**
+ * Collect the current diff for review.
+ */
+export async function collectReviewDiff(projectDir, timeout = DEFAULT_TIMEOUT) {
+    const [diff, stat] = await Promise.all([
+        execStdout("git", ["diff", "HEAD"], { cwd: projectDir, timeout }),
+        execStdout("git", ["diff", "--stat", "HEAD"], { cwd: projectDir, timeout }),
+    ]);
+    return {
+        diff: diff.trim(),
+        stat: stat.trim(),
+    };
+}
+/**
+ * Display the review UI and prompt for approval.
+ *
+ * Shows:
+ * 1. Diff stat summary
+ * 2. Full diff
+ * 3. Approve/reject prompt
+ *
+ * The `promptFn` parameter allows injection for testing.
+ */
+export async function promptReview(reviewDiff, promptFn) {
+    section("Review");
+    subsection("Changes");
+    info(reviewDiff.stat);
+    subsection("Diff");
+    info(reviewDiff.diff);
+    info("");
+    const askUser = promptFn ?? defaultPrompt;
+    const answer = await askUser("Approve these changes? [Y/n] ");
+    const normalized = answer.trim().toLowerCase();
+    // Empty string or "y"/"yes" → approve; anything else → reject
+    if (normalized === "" || normalized === "y" || normalized === "yes") {
+        return { approved: true };
+    }
+    return {
+        approved: false,
+        reason: "Changes rejected by reviewer",
+    };
+}
+function defaultPrompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Revert all uncommitted changes in the working tree.
+ * Used when the reviewer rejects the agent's work.
+ */
+export async function revertChanges(projectDir, timeout = DEFAULT_TIMEOUT) {
+    // Unstage everything, then discard working tree changes + untracked files
+    await execStdout("git", ["reset", "HEAD", "."], { cwd: projectDir, timeout });
+    await execStdout("git", ["checkout", "."], { cwd: projectDir, timeout });
+    await execStdout("git", ["clean", "-fd"], { cwd: projectDir, timeout });
+}
+//# sourceMappingURL=review.js.map

package/packages/hench/dist/agent/analysis/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../../src/agent/analysis/review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAyBlE,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,UAAkB,EAClB,OAAO,GAAG,eAAe;IAEzB,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACrC,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;QACjE,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;KAC5E,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;KAClB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAsB,EACtB,QAAgD;IAEhD,OAAO,CAAC,QAAQ,CAAC,CAAC;IAElB,UAAU,CAAC,SAAS,CAAC,CAAC;IACtB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAEtB,UAAU,CAAC,MAAM,CAAC,CAAC;IACnB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAEtB,IAAI,CAAC,EAAE,CAAC,CAAC;IAET,MAAM,OAAO,GAAG,QAAQ,IAAI,aAAa,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAE9D,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE/C,8DAA8D;IAC9D,IAAI,UAAU,KAAK,EAAE,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACpE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,8BAA8B;KACvC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE;YAC/B,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAkB,EAClB,OAAO,GAAG,eAAe;IAEzB,0EAA0E;IAC1E,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9E,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IACzE,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;AAC1E,CAAC"}

package/packages/hench/dist/agent/analysis/spin.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Spin detection for agent loops.
+ *
+ * Detects when an agent is producing text-only responses without making
+ * any tool calls — burning tokens while making no progress. This typically
+ * happens when the model hits max_tokens repeatedly and keeps generating
+ * text without ever dispatching a tool.
+ *
+ * Pure functions, no side effects — mirrors the stuck.ts pattern.
+ *
+ * @module agent/analysis/spin
+ */
+/** Consecutive empty turns (no tool calls) before the agent is aborted. */
+export declare const DEFAULT_SPIN_THRESHOLD = 5;
+/**
+ * Update the consecutive empty-turn counter.
+ *
+ * Resets to 0 when the turn included tool calls; increments otherwise.
+ */
+export declare function updateEmptyTurnCount(current: number, hadToolCalls: boolean): number;
+/**
+ * Check whether a completed run looks like a spin (many turns, zero tool calls).
+ *
+ * Used by the CLI loop for post-run spin detection, since the CLI provider
+ * doesn't have per-turn visibility during execution.
+ */
+export declare function isSpinningRun(turns: number, toolCallCount: number, threshold?: number): boolean;

package/packages/hench/dist/agent/analysis/spin.js

@@ -0,0 +1,32 @@
+/**
+ * Spin detection for agent loops.
+ *
+ * Detects when an agent is producing text-only responses without making
+ * any tool calls — burning tokens while making no progress. This typically
+ * happens when the model hits max_tokens repeatedly and keeps generating
+ * text without ever dispatching a tool.
+ *
+ * Pure functions, no side effects — mirrors the stuck.ts pattern.
+ *
+ * @module agent/analysis/spin
+ */
+/** Consecutive empty turns (no tool calls) before the agent is aborted. */
+export const DEFAULT_SPIN_THRESHOLD = 5;
+/**
+ * Update the consecutive empty-turn counter.
+ *
+ * Resets to 0 when the turn included tool calls; increments otherwise.
+ */
+export function updateEmptyTurnCount(current, hadToolCalls) {
+    return hadToolCalls ? 0 : current + 1;
+}
+/**
+ * Check whether a completed run looks like a spin (many turns, zero tool calls).
+ *
+ * Used by the CLI loop for post-run spin detection, since the CLI provider
+ * doesn't have per-turn visibility during execution.
+ */
+export function isSpinningRun(turns, toolCallCount, threshold = DEFAULT_SPIN_THRESHOLD) {
+    return turns >= threshold && toolCallCount === 0;
+}
+//# sourceMappingURL=spin.js.map

package/packages/hench/dist/agent/analysis/spin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spin.js","sourceRoot":"","sources":["../../../src/agent/analysis/spin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,YAAqB;IAErB,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,aAAqB,EACrB,YAAoB,sBAAsB;IAE1C,OAAO,KAAK,IAAI,SAAS,IAAI,aAAa,KAAK,CAAC,CAAC;AACnD,CAAC"}

package/packages/hench/dist/agent/analysis/stuck.d.ts

@@ -0,0 +1,22 @@
+import type { RunRecord } from "../../schema/index.js";
+/**
+ * Count the number of consecutive recent failures for a given task.
+ *
+ * Walks through runs most-recent-first (the array must be sorted by
+ * startedAt descending), filtering to the target taskId. Counts only
+ * hard failures (failed/timeout); stops at the first non-failure run.
+ */
+export declare function countRecentFailures(taskId: string, runs: RunRecord[]): number;
+/**
+ * Return true if a task has accumulated enough consecutive failures
+ * to be considered stuck.
+ */
+export declare function isStuckTask(taskId: string, runs: RunRecord[], threshold: number): boolean;
+/**
+ * Scan all runs and return the set of task IDs that are stuck
+ * (i.e. have ≥ threshold consecutive hard failures, most-recent-first).
+ *
+ * @param runs  Run records sorted by startedAt **descending**
+ * @param threshold  Number of consecutive failures before a task is stuck
+ */
+export declare function getStuckTaskIds(runs: RunRecord[], threshold: number): Set<string>;

package/packages/hench/dist/agent/analysis/stuck.js

@@ -0,0 +1,56 @@
+/**
+ * Statuses that count as a hard failure for stuck-task detection.
+ * Transient errors (API rate limits, network blips) do not count because
+ * they are expected to self-resolve on retry.
+ */
+const FAILURE_STATUSES = new Set(["failed", "timeout", "budget_exceeded"]);
+/**
+ * Count the number of consecutive recent failures for a given task.
+ *
+ * Walks through runs most-recent-first (the array must be sorted by
+ * startedAt descending), filtering to the target taskId. Counts only
+ * hard failures (failed/timeout); stops at the first non-failure run.
+ */
+export function countRecentFailures(taskId, runs) {
+    let count = 0;
+    for (const run of runs) {
+        if (run.taskId !== taskId)
+            continue;
+        if (FAILURE_STATUSES.has(run.status)) {
+            count++;
+        }
+        else {
+            break;
+        }
+    }
+    return count;
+}
+/**
+ * Return true if a task has accumulated enough consecutive failures
+ * to be considered stuck.
+ */
+export function isStuckTask(taskId, runs, threshold) {
+    return countRecentFailures(taskId, runs) >= threshold;
+}
+/**
+ * Scan all runs and return the set of task IDs that are stuck
+ * (i.e. have ≥ threshold consecutive hard failures, most-recent-first).
+ *
+ * @param runs  Run records sorted by startedAt **descending**
+ * @param threshold  Number of consecutive failures before a task is stuck
+ */
+export function getStuckTaskIds(runs, threshold) {
+    // Collect unique task IDs that have appeared in runs
+    const taskIds = new Set();
+    for (const run of runs) {
+        taskIds.add(run.taskId);
+    }
+    const stuck = new Set();
+    for (const taskId of taskIds) {
+        if (isStuckTask(taskId, runs, threshold)) {
+            stuck.add(taskId);
+        }
+    }
+    return stuck;
+}
+//# sourceMappingURL=stuck.js.map

package/packages/hench/dist/agent/analysis/stuck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuck.js","sourceRoot":"","sources":["../../../src/agent/analysis/stuck.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,gBAAgB,GAAgB,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,IAAiB;IAEjB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;YAAE,SAAS;QACpC,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACrC,KAAK,EAAE,CAAC;QACV,CAAC;aAAM,CAAC;YACN,MAAM;QACR,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,IAAiB,EACjB,SAAiB;IAEjB,OAAO,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,SAAS,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAiB,EACjB,SAAiB;IAEjB,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/packages/hench/dist/agent/analysis/summary.d.ts

@@ -0,0 +1,9 @@
+import type { ToolCallRecord, RunSummaryData } from "../../schema/v1.js";
+/**
+ * Build a structured run summary from raw tool call records.
+ *
+ * This is a pure function — no I/O, no side effects. It derives
+ * structured metadata from the tool calls already recorded by the
+ * agent loop.
+ */
+export declare function buildRunSummary(toolCalls: ToolCallRecord[]): RunSummaryData;

package/packages/hench/dist/agent/analysis/summary.js

@@ -0,0 +1,106 @@
+/** Patterns that identify a command as a test invocation. */
+const TEST_PATTERNS = [
+    /\btest\b/i,
+    /\bvitest\b/i,
+    /\bjest\b/i,
+    /\bmocha\b/i,
+    /\bava\b/i,
+    /\btap\b/i,
+    /\bplaywright\b/i,
+    /\bcypress\b/i,
+];
+function isTestCommand(command) {
+    return TEST_PATTERNS.some((p) => p.test(command));
+}
+/** Glob-like args we skip when extracting file paths from git add. */
+const GLOB_ARGS = new Set([".", "-A", "--all", "-u", "--update"]);
+function inferExitStatus(output) {
+    if (output.startsWith("[GUARD]"))
+        return "blocked";
+    if (/timed out/i.test(output))
+        return "timeout";
+    if (output.startsWith("[ERROR]") || /exit code/i.test(output))
+        return "error";
+    return "ok";
+}
+/**
+ * Build a structured run summary from raw tool call records.
+ *
+ * This is a pure function — no I/O, no side effects. It derives
+ * structured metadata from the tool calls already recorded by the
+ * agent loop.
+ */
+export function buildRunSummary(toolCalls) {
+    const changedSet = new Set();
+    const readSet = new Set();
+    const commands = [];
+    const tests = [];
+    for (const call of toolCalls) {
+        switch (call.tool) {
+            case "write_file": {
+                const path = call.input.path;
+                if (path)
+                    changedSet.add(path);
+                break;
+            }
+            case "read_file": {
+                const path = call.input.path;
+                if (path)
+                    readSet.add(path);
+                break;
+            }
+            case "run_command": {
+                const cmd = call.input.command;
+                if (!cmd)
+                    break;
+                const exitStatus = inferExitStatus(call.output);
+                commands.push({ command: cmd, exitStatus, durationMs: call.durationMs });
+                if (isTestCommand(cmd)) {
+                    tests.push({
+                        command: cmd,
+                        passed: exitStatus === "ok",
+                        durationMs: call.durationMs,
+                    });
+                }
+                break;
+            }
+            case "git": {
+                const sub = call.input.subcommand;
+                const args = call.input.args;
+                if (!sub)
+                    break;
+                // Record as a command
+                const gitCmd = args ? `git ${sub} ${args}` : `git ${sub}`;
+                const exitStatus = inferExitStatus(call.output);
+                commands.push({ command: gitCmd, exitStatus, durationMs: call.durationMs });
+                // Extract file paths from git add
+                if (sub === "add" && args) {
+                    const parts = args.split(/\s+/).filter((p) => p && !GLOB_ARGS.has(p));
+                    for (const p of parts) {
+                        changedSet.add(p);
+                    }
+                }
+                break;
+            }
+            // list_directory, search_files, rex_* — no file/command tracking needed
+            default:
+                break;
+        }
+    }
+    const filesChanged = [...changedSet].sort();
+    const filesRead = [...readSet].sort();
+    return {
+        filesChanged,
+        filesRead,
+        commandsExecuted: commands,
+        testsRun: tests,
+        counts: {
+            filesRead: filesRead.length,
+            filesChanged: filesChanged.length,
+            commandsExecuted: commands.length,
+            testsRun: tests.length,
+            toolCallsTotal: toolCalls.length,
+        },
+    };
+}
+//# sourceMappingURL=summary.js.map

package/packages/hench/dist/agent/analysis/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../src/agent/analysis/summary.ts"],"names":[],"mappings":"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"}

package/packages/hench/dist/agent/analysis/workflow.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Workflow analysis engine — analyzes historical run data to identify
+ * bottlenecks, failure patterns, and optimization opportunities.
+ *
+ * Pure functions operating on RunRecord arrays. No I/O or side effects.
+ */
+import type { RunRecord, HenchConfig } from "../../schema/v1.js";
+export type SuggestionCategory = "token-efficiency" | "failure-prevention" | "turn-optimization" | "config-tuning" | "task-health";
+export type SuggestionPriority = "high" | "medium" | "low";
+export interface WorkflowSuggestion {
+    id: string;
+    category: SuggestionCategory;
+    priority: SuggestionPriority;
+    title: string;
+    description: string;
+    rationale: string;
+    impact: string;
+    /** Config changes to apply if accepted. Dot-path keys to values. */
+    configChanges?: Record<string, unknown>;
+    /** Task IDs affected, if any. */
+    affectedTaskIds?: string[];
+    /** Whether this suggestion can be auto-applied via config change. */
+    autoApplicable: boolean;
+}
+export interface WorkflowAnalysis {
+    /** Total runs analyzed. */
+    totalRuns: number;
+    /** Time range covered. */
+    timeRange: {
+        earliest: string;
+        latest: string;
+    } | null;
+    /** Summary statistics. */
+    stats: WorkflowStats;
+    /** Optimization suggestions ordered by priority. */
+    suggestions: WorkflowSuggestion[];
+}
+export interface WorkflowStats {
+    successRate: number;
+    avgTurns: number;
+    avgTokensPerRun: number;
+    avgDurationMs: number;
+    failuresByStatus: Record<string, number>;
+    /** Tasks with the most failures. */
+    troubleTaskIds: string[];
+    /** Runs that hit the max turn limit. */
+    turnLimitHits: number;
+    /** Runs that hit the token budget. */
+    budgetExceededCount: number;
+}
+/** Reset ID counter — only for testing. */
+export declare function _resetIdCounter(): void;
+export declare function computeStats(runs: RunRecord[], config?: HenchConfig): WorkflowStats;
+/**
+ * Analyze workflow run history and produce optimization suggestions.
+ *
+ * @param runs  Run records sorted by startedAt descending (newest first)
+ * @param config  Optional current hench config for context-aware suggestions
+ */
+export declare function analyzeWorkflow(runs: RunRecord[], config?: HenchConfig): WorkflowAnalysis;