wotann 0.5.87 → 0.5.88

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

@@ -3630,6 +3630,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/package.json

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