wotann 0.5.87 → 0.5.89

package/dist/cli/commands/insights.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `wotann insights` — render deterministic metrics from saved sessions.
+ *
+ * Thin CLI wrapper around src/learning/insights.ts. JSON mode emits the
+ * full structured report; text mode formats a Hermes-style readout
+ * with top tools / common query prefixes / error patterns.
+ */
+export interface RunInsightsOptions {
+    /** Defaults to `process.cwd()`. */
+    readonly workingDir?: string;
+    /** Day-window (Number.isFinite + > 0). Omit for all-time. */
+    readonly days?: number;
+    /** Emit the full report as JSON instead of the formatted text. */
+    readonly json?: boolean;
+    /** Injectable writer for tests. Defaults to console.log. */
+    readonly write?: (line: string) => void;
+}
+export declare function runInsights(opts?: RunInsightsOptions): number;

package/dist/cli/commands/insights.js

@@ -0,0 +1,64 @@
+/**
+ * `wotann insights` — render deterministic metrics from saved sessions.
+ *
+ * Thin CLI wrapper around src/learning/insights.ts. JSON mode emits the
+ * full structured report; text mode formats a Hermes-style readout
+ * with top tools / common query prefixes / error patterns.
+ */
+import chalk from "chalk";
+import { generateInsights } from "../../learning/insights.js";
+export function runInsights(opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    const report = generateInsights({
+        workingDir: opts.workingDir ?? process.cwd(),
+        ...(opts.days !== undefined && Number.isFinite(opts.days) && opts.days > 0
+            ? { days: opts.days }
+            : {}),
+    });
+    if (opts.json === true) {
+        write(JSON.stringify(report, null, 2));
+        return 0;
+    }
+    renderTextReport(write, report);
+    return 0;
+}
+function renderTextReport(write, r) {
+    const windowLabel = r.windowDays !== null ? `last ${r.windowDays} days` : "all time";
+    write("");
+    write(chalk.bold(`WOTANN insights — ${windowLabel}`));
+    write("");
+    if (r.sessionsTotal === 0) {
+        write(chalk.dim("  no sessions found in .wotann/sessions/"));
+        write("");
+        return;
+    }
+    write(`  sessions in window:  ${r.sessionsInWindow} of ${r.sessionsTotal} on disk`);
+    if (r.sessionsCorrupt > 0) {
+        write(chalk.yellow(`  sessions corrupt:    ${r.sessionsCorrupt} (skipped)`));
+    }
+    if (r.sessionsIncognito > 0) {
+        write(chalk.dim(`  sessions incognito:  ${r.sessionsIncognito} (excluded from query histograms)`));
+    }
+    write(`  messages:            ${r.messagesTotal}`);
+    if (r.sessionsInWindow > 0) {
+        write(`  avg msgs/session:    ${r.avgMessagesPerSession.toFixed(1)}`);
+    }
+    write(`  tokens:              ${r.tokensTotal.toLocaleString()}`);
+    write(`  cost:                $${r.costTotal.toFixed(4)}`);
+    write(`  tool calls:          ${r.toolCallsTotal}`);
+    write(`  providers:           ${r.providersUsed.join(", ") || chalk.dim("(none)")}`);
+    write(`  models:              ${r.modelsUsed.join(", ") || chalk.dim("(none)")}`);
+    renderHistogram(write, "Top tools", r.topTools, 30);
+    renderHistogram(write, "Common query prefixes", r.topUserPrefixes, 40);
+    renderHistogram(write, "Error patterns", r.errors, 60);
+    write("");
+}
+function renderHistogram(write, title, rows, keyWidth) {
+    if (rows.length === 0)
+        return;
+    write("");
+    write(chalk.bold(`  ${title}:`));
+    for (const row of rows) {
+        write(`    ${row.key.padEnd(keyWidth)} ${row.count}`);
+    }
+}

package/dist/index.js

@@ -416,26 +416,21 @@ program
         import("./ui/alt-buffer.js"),
     ]);
     const { isAltBufferRequested, enterAltBuffer, exitAltBuffer } = altBufferModule;
-    // Switch to the alternate screen buffer NOW that the heavy modules
-    // are loaded. Crash-safe — alt-buffer.ts wires SIGINT/SIGTERM/
-    // uncaughtException to always restore the main buffer. Default ON;
-    // disable with `--no-fullscreen` or `WOTANN_FULLSCREEN=0`.
-    if (isAltBufferRequested(options.fullscreen !== false)) {
-        enterAltBuffer();
-    }
+    const wantsAltBuffer = isAltBufferRequested(options.fullscreen !== false);
     // Mount the single V3 shell through the ONE guarded gate every
-    // interactive Ink mount must use: viewport repair (Ink reads
-    // stdout.columns directly — undefined under npx collapses the
-    // root box to width 0), raw-mode-capable stdin resolution
-    // (process.stdin → /dev/tty → none), and refuse-cleanly-with-
-    // guidance instead of mounting Ink into the error-render-loop
-    // hang ("npx wotann just hangs"). See ui/mount-interactive-ink.ts.
+    // interactive Ink mount must use: viewport repair, raw-mode-
+    // capable stdin resolution, refuse-cleanly-with-guidance.
+    // See src/ui/mount-interactive-ink.ts for the full contract.
     //
-    // The try/catch + exitAltBuffer pair is the recovery contract:
-    // if Ink throws (e.g. setRawMode passes the guard probe but
-    // fails on Ink's first useInput commit on some terminal combos),
-    // we ALWAYS restore the main buffer first so the user sees the
-    // diagnostic instead of a frozen black screen.
+    // v0.5.89 hotfix: alt-buffer entry is now gated through
+    // `onResolved`, which fires AFTER the guard probe succeeds and
+    // BEFORE Ink's first paint. Entering eagerly (v0.5.85 → v0.5.88
+    // behavior) meant any guard refusal would write the diagnostic
+    // INTO the alt-buffer, then exitAltBuffer would tear it down,
+    // leaving the user with no visible error message ("npx wotann
+    // exits silently" — user-reported 2026-05-24). Now: refusal
+    // path NEVER enters alt-buffer, so the diagnostic stays visible
+    // in the main buffer.
     let mountResult;
     try {
         mountResult = await mountInteractiveInk(React.createElement(AppV3, {
@@ -444,17 +439,26 @@ program
             initialModel: interactive.initialModel,
             initialProvider: interactive.initialProvider,
             runtime: interactive.runtime,
-        }));
+        }), {
+            onResolved: () => {
+                if (wantsAltBuffer)
+                    enterAltBuffer();
+            },
+        });
     }
     catch (error) {
+        // If onResolved fired, alt-buffer is up; restore main buffer
+        // so the error message is visible. Idempotent — no-op if
+        // alt-buffer was never entered.
         exitAltBuffer();
         process.stderr.write(`[wotann] Interactive TUI failed to mount: ${error instanceof Error ? error.message : String(error)}\n`);
         return;
     }
     if (mountResult.refused) {
-        // mountInteractiveInk already wrote actionable guidance to
-        // stderr. Restore main buffer so guidance is visible instead
-        // of trapped behind an alt-buffer Ink never painted into.
+        // onResolved did NOT fire (guard refused or Ink threw before
+        // commit). Alt-buffer was never entered. exitAltBuffer is
+        // still safe (idempotent), but the diagnostic mountInteractiveInk
+        // wrote to stderr is already visible in the main buffer.
         exitAltBuffer();
         return;
     }
@@ -1946,15 +1950,10 @@ program
         import("./ui/alt-buffer.js"),
     ]);
     const { isAltBufferRequested, enterAltBuffer, exitAltBuffer } = altBufferModule;
-    if (isAltBufferRequested(true)) {
-        enterAltBuffer();
-    }
-    // Single V3 shell — initialMessages seeds the transcript so the
-    // resumed session continues where it left off (AppV3 wires it via
-    // useState([...initialMessages])). Same guarded gate as the start
-    // path: viewport repair + raw-mode stdin + refuse-instead-of-hang.
-    // try/catch + exitAltBuffer pair ensures the user always sees the
-    // diagnostic on Ink-mount failure instead of a frozen black screen.
+    const wantsAltBuffer = isAltBufferRequested(true);
+    // v0.5.89 hotfix: alt-buffer entry is now gated through `onResolved`
+    // so a guard refusal never swallows the diagnostic. See start
+    // command for the full discussion.
     let mountResult;
     try {
         mountResult = await mountInteractiveInk(React.createElement(AppV3, {
@@ -1964,7 +1963,12 @@ program
             initialProvider: session.provider,
             initialMessages: session.messages,
             runtime: interactive.runtime,
-        }));
+        }), {
+            onResolved: () => {
+                if (wantsAltBuffer)
+                    enterAltBuffer();
+            },
+        });
     }
     catch (error) {
         exitAltBuffer();
@@ -3630,6 +3634,28 @@ curatorCmd
     const mod = await import("./cli/commands/skills-curator.js");
     process.exit(mod.runUnpin(name));
 });
+// ── wotann insights ──────────────────────────────────────────
+//
+// Hermes Gap 3 port — deterministic metrics over saved sessions:
+// top tools, common query prefixes, error patterns. Pure-data MVP;
+// LLM-graded review deferred to a follow-up (aux-cred pattern).
+// Module lives at src/learning/insights.ts; CLI shell in
+// src/cli/commands/insights.ts.
+program
+    .command("insights")
+    .description("Show session metrics — top tools, common query prefixes, error patterns")
+    .option("--days <n>", "Only include sessions started within the last N days (default: all time)", (v) => parseInt(v, 10))
+    .option("--json", "Emit the full report as JSON instead of formatted text")
+    .action(async (opts) => {
+    const mod = await import("./cli/commands/insights.js");
+    const cliOpts = {};
+    if (opts.days !== undefined && Number.isFinite(opts.days) && opts.days > 0) {
+        cliOpts.days = opts.days;
+    }
+    if (opts.json === true)
+        cliOpts.json = true;
+    process.exit(mod.runInsights(cliOpts));
+});
 // ── wotann cost ──────────────────────────────────────────────
 //
 // Wave 4G: the cost command now accepts an optional `period` argument

package/dist/learning/insights.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Insights — deterministic metrics over saved WOTANN sessions.
+ *
+ * Hermes Gap 3 port: surface the "what worked / what failed / repeating
+ * patterns" data WOTANN already stores. The Hermes implementation adds
+ * an LLM-graded pass on top — that's deferred to a follow-up ticket
+ * (lands with the same aux-cred pattern the Skill Curator is waiting on).
+ * The data layer below is the foundation: pure aggregation, zero LLM,
+ * works fully offline.
+ *
+ * Inputs: every `.json` file in `<workingDir>/.wotann/sessions/`.
+ *   Each file is a {@link SessionState} round-trip (see
+ *   `src/core/session.ts`).
+ *
+ * Output: a structured {@link InsightsReport} with totals + top-N
+ * histograms for tools, user query prefixes, and error patterns.
+ *
+ * Strict invariants:
+ *   - Pure read-only — never writes back to the sessions directory.
+ *   - Skips sessions that fail to parse (corrupt JSON) rather than
+ *     crashing the whole report. Honest count via {@link
+ *     InsightsReport.sessionsTotal}.
+ *   - Ignores incognito sessions when counting query patterns (those
+ *     are explicitly off-the-record).
+ *   - Stable sort — top-N lists are deterministic across runs.
+ */
+export interface InsightsOptions {
+    /** Working directory containing `.wotann/sessions/`. */
+    readonly workingDir: string;
+    /** Limit to sessions started within the last N days (omit = all time). */
+    readonly days?: number;
+}
+export interface TopCount {
+    readonly key: string;
+    readonly count: number;
+}
+export interface InsightsReport {
+    /** The day-window applied, or null when no window was requested. */
+    readonly windowDays: number | null;
+    /** Sessions present on disk (regardless of window). */
+    readonly sessionsTotal: number;
+    /** Sessions that fell within the configured day-window. */
+    readonly sessionsInWindow: number;
+    /** Sessions skipped because the JSON failed to parse. */
+    readonly sessionsCorrupt: number;
+    /** Sessions skipped because they were incognito. */
+    readonly sessionsIncognito: number;
+    /** Aggregate message count across the in-window non-incognito set. */
+    readonly messagesTotal: number;
+    readonly avgMessagesPerSession: number;
+    readonly tokensTotal: number;
+    readonly costTotal: number;
+    readonly toolCallsTotal: number;
+    /** Top tools by invocation count (descending). */
+    readonly topTools: readonly TopCount[];
+    /** Top user-query prefixes (first 5 words, lowercased) — descending. */
+    readonly topUserPrefixes: readonly TopCount[];
+    /** Top error patterns (Runtime error / [Guardrail] prefix). */
+    readonly errors: readonly TopCount[];
+    /** Distinct models observed in-window — sorted alphabetically. */
+    readonly modelsUsed: readonly string[];
+    /** Distinct providers observed in-window — sorted alphabetically. */
+    readonly providersUsed: readonly string[];
+}
+export declare function generateInsights(opts: InsightsOptions): InsightsReport;
+/**
+ * Extract a 5-word, lowercased prefix from a user message. Returns null
+ * when the content is empty or whitespace-only so {@link bump} doesn't
+ * inflate a phantom "" bucket.
+ */
+export declare function extractPrefix(content: string): string | null;
+/**
+ * Recognize the two error shapes WOTANN's runtime emits as system
+ * messages: `Runtime error: <reason>` (from AppV3.tsx) and
+ * `[Guardrail] <reason>` (from runtime-agent-loop.ts). Anything else
+ * is treated as informational and ignored.
+ *
+ * The returned string is truncated to 80 chars to keep the histogram
+ * cardinality bounded (different stack traces / file paths shouldn't
+ * each get their own bucket).
+ */
+export declare function normalizeErrorMessage(content: string): string | null;

package/dist/learning/insights.js

@@ -0,0 +1,180 @@
+/**
+ * Insights — deterministic metrics over saved WOTANN sessions.
+ *
+ * Hermes Gap 3 port: surface the "what worked / what failed / repeating
+ * patterns" data WOTANN already stores. The Hermes implementation adds
+ * an LLM-graded pass on top — that's deferred to a follow-up ticket
+ * (lands with the same aux-cred pattern the Skill Curator is waiting on).
+ * The data layer below is the foundation: pure aggregation, zero LLM,
+ * works fully offline.
+ *
+ * Inputs: every `.json` file in `<workingDir>/.wotann/sessions/`.
+ *   Each file is a {@link SessionState} round-trip (see
+ *   `src/core/session.ts`).
+ *
+ * Output: a structured {@link InsightsReport} with totals + top-N
+ * histograms for tools, user query prefixes, and error patterns.
+ *
+ * Strict invariants:
+ *   - Pure read-only — never writes back to the sessions directory.
+ *   - Skips sessions that fail to parse (corrupt JSON) rather than
+ *     crashing the whole report. Honest count via {@link
+ *     InsightsReport.sessionsTotal}.
+ *   - Ignores incognito sessions when counting query patterns (those
+ *     are explicitly off-the-record).
+ *   - Stable sort — top-N lists are deterministic across runs.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { restoreSession } from "../core/session.js";
+// ── Public API ────────────────────────────────────────────────────
+export function generateInsights(opts) {
+    const sessionsDir = join(opts.workingDir, ".wotann", "sessions");
+    if (!existsSync(sessionsDir)) {
+        return emptyReport(opts.days ?? null);
+    }
+    const files = readdirSync(sessionsDir).filter((name) => name.endsWith(".json"));
+    const parsed = [];
+    let corrupt = 0;
+    for (const name of files) {
+        const session = restoreSession(join(sessionsDir, name));
+        if (session === null) {
+            corrupt++;
+            continue;
+        }
+        parsed.push(session);
+    }
+    return buildReport(parsed, opts.days, corrupt);
+}
+// ── Internal helpers ──────────────────────────────────────────────
+function buildReport(sessions, days, corruptCount) {
+    const cutoffMs = days !== undefined ? Date.now() - days * 86_400_000 : null;
+    const inWindow = cutoffMs !== null
+        ? sessions.filter((s) => {
+            const startMs = s.startedAt instanceof Date ? s.startedAt.getTime() : new Date(s.startedAt).getTime();
+            return Number.isFinite(startMs) && startMs >= cutoffMs;
+        })
+        : sessions;
+    const incognito = inWindow.filter((s) => s.incognito);
+    const live = inWindow.filter((s) => !s.incognito);
+    let messagesTotal = 0;
+    let tokensTotal = 0;
+    let costTotal = 0;
+    let toolCallsTotal = 0;
+    const toolCounts = new Map();
+    const prefixCounts = new Map();
+    const errorCounts = new Map();
+    const models = new Set();
+    const providers = new Set();
+    for (const session of live) {
+        messagesTotal += session.messages.length;
+        tokensTotal += session.totalTokens;
+        costTotal += session.totalCost;
+        toolCallsTotal += session.toolCalls;
+        if (typeof session.model === "string" && session.model.length > 0) {
+            models.add(session.model);
+        }
+        if (typeof session.provider === "string" && session.provider.length > 0) {
+            providers.add(session.provider);
+        }
+        for (const msg of session.messages) {
+            if (msg.role === "tool" && typeof msg.toolName === "string" && msg.toolName.length > 0) {
+                bump(toolCounts, msg.toolName);
+            }
+            if (msg.role === "user" && typeof msg.content === "string") {
+                const prefix = extractPrefix(msg.content);
+                if (prefix !== null)
+                    bump(prefixCounts, prefix);
+            }
+            if (msg.role === "system" && typeof msg.content === "string") {
+                const normalized = normalizeErrorMessage(msg.content);
+                if (normalized !== null)
+                    bump(errorCounts, normalized);
+            }
+        }
+    }
+    return {
+        windowDays: days ?? null,
+        sessionsTotal: sessions.length,
+        sessionsInWindow: inWindow.length,
+        sessionsCorrupt: corruptCount,
+        sessionsIncognito: incognito.length,
+        messagesTotal,
+        avgMessagesPerSession: live.length > 0 ? messagesTotal / live.length : 0,
+        tokensTotal,
+        costTotal,
+        toolCallsTotal,
+        topTools: topN(toolCounts, 10),
+        topUserPrefixes: topN(prefixCounts, 10),
+        errors: topN(errorCounts, 10),
+        modelsUsed: [...models].sort(),
+        providersUsed: [...providers].sort(),
+    };
+}
+/**
+ * Extract a 5-word, lowercased prefix from a user message. Returns null
+ * when the content is empty or whitespace-only so {@link bump} doesn't
+ * inflate a phantom "" bucket.
+ */
+export function extractPrefix(content) {
+    const words = content
+        .trim()
+        .split(/\s+/)
+        .filter((w) => w.length > 0)
+        .slice(0, 5);
+    if (words.length === 0)
+        return null;
+    return words.join(" ").toLowerCase();
+}
+/**
+ * Recognize the two error shapes WOTANN's runtime emits as system
+ * messages: `Runtime error: <reason>` (from AppV3.tsx) and
+ * `[Guardrail] <reason>` (from runtime-agent-loop.ts). Anything else
+ * is treated as informational and ignored.
+ *
+ * The returned string is truncated to 80 chars to keep the histogram
+ * cardinality bounded (different stack traces / file paths shouldn't
+ * each get their own bucket).
+ */
+export function normalizeErrorMessage(content) {
+    if (content.startsWith("Runtime error:") || content.startsWith("[Guardrail]")) {
+        return content.slice(0, 80);
+    }
+    return null;
+}
+function bump(counts, key) {
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+/**
+ * Top-N by count, descending. Ties resolve by key lexicographic order
+ * so output is deterministic across runs.
+ */
+function topN(counts, n) {
+    return [...counts.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .sort((a, b) => {
+        if (b.count !== a.count)
+            return b.count - a.count;
+        return a.key.localeCompare(b.key);
+    })
+        .slice(0, n);
+}
+function emptyReport(windowDays) {
+    return {
+        windowDays,
+        sessionsTotal: 0,
+        sessionsInWindow: 0,
+        sessionsCorrupt: 0,
+        sessionsIncognito: 0,
+        messagesTotal: 0,
+        avgMessagesPerSession: 0,
+        tokensTotal: 0,
+        costTotal: 0,
+        toolCallsTotal: 0,
+        topTools: [],
+        topUserPrefixes: [],
+        errors: [],
+        modelsUsed: [],
+        providersUsed: [],
+    };
+}

package/dist/ui/mount-interactive-ink.d.ts

@@ -39,6 +39,20 @@ export interface MountInteractiveOptions {
     };
     /** Replace the default refusal guidance text. */
     readonly refusalMessage?: string;
+    /**
+     * Fires AFTER stdin resolution succeeds and BEFORE Ink's `render`
+     * commits its first frame. Lets the caller enter the alt-buffer
+     * ONLY when we're committed to mounting — avoiding the
+     * "enter-alt-buffer, write refusal in alt-buffer, exit-alt-buffer,
+     * refusal swallowed" bug fixed in v0.5.89 (user-reported regression
+     * in v0.5.88 where `npx wotann` exited silently because the
+     * diagnostic was lost in the alt-buffer tear-down).
+     *
+     * When the guard refuses or Ink throws, this callback DOES NOT fire,
+     * so any caller-side side effects (alt-buffer entry) are skipped and
+     * the stderr diagnostic stays visible in the main buffer.
+     */
+    readonly onResolved?: () => void;
 }
 export interface MountInteractiveResult {
     /**

package/dist/ui/mount-interactive-ink.js

@@ -55,6 +55,10 @@ export async function mountInteractiveInk(element, opts = {}) {
         return { instance: null, refused: true };
     }
     const inkRender = opts.inkRender ?? (await import("ink")).render;
+    // We are committed to mounting — fire the caller's pre-mount hook so
+    // it can enter alt-buffer (or any other render-time setup) NOW, after
+    // the guard passed and before Ink's first frame paints.
+    opts.onResolved?.();
     try {
         const instance = inkRender(element, { stdin: inputStdin });
         return { instance, refused: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wotann",
-  "version": "0.5.87",
+  "version": "0.5.89",
   "description": "WOTANN — The All-Father of AI Agent Harnesses",
   "type": "module",
   "main": "dist/index.js",