wotann 0.5.86 → 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/core/runtime-agent-loop.d.ts

@@ -36,8 +36,48 @@ export interface ToolResultEvent {
     readonly toolName: string;
     readonly result: string;
 }
-export type RunAgentControlEvent = IterationStartEvent | ToolResultEvent;
+/**
+ * Emitted at an iteration boundary after the loop drained one or more
+ * user-side redirects (Hermes Gap 2 — interrupt-and-redirect). UI
+ * consumers can render a system bubble showing the redirected text so
+ * the user has visual confirmation the directive landed. The redirect
+ * is ALREADY appended to context by the loop before this event fires;
+ * receivers MUST NOT re-append it themselves.
+ */
+export interface RedirectReceivedEvent {
+    readonly kind: "redirect_received";
+    readonly count: number;
+    readonly messages: readonly string[];
+}
+export type RunAgentControlEvent = IterationStartEvent | ToolResultEvent | RedirectReceivedEvent;
 export type AgentEvent = StreamChunk | RunAgentControlEvent;
+/**
+ * Channel for user-side redirects (Hermes Gap 2). The TUI / RPC client
+ * pushes messages when the user sends a new directive WHILE the agent
+ * is streaming. The runAgent loop drains at each iteration boundary
+ * and appends them to context as new user turns, so the model absorbs
+ * the directive on the next turn — no context loss, no abort needed.
+ *
+ * Implementations MUST be safe to call concurrently (push from the
+ * UI thread, drain from the loop's async generator).
+ */
+export interface RedirectChannel {
+    /** Drain all pending redirects. Returns empty array when none queued. */
+    drain(): readonly string[];
+}
+/**
+ * Default in-memory channel. Pushes are appended to a queue; drain
+ * empties the queue atomically. The queue ignores empty-string pushes
+ * so an accidental Ctrl+R on an empty composer doesn't inject a blank
+ * user turn into the model context.
+ */
+export declare class InMemoryRedirectChannel implements RedirectChannel {
+    private queue;
+    push(message: string): void;
+    drain(): readonly string[];
+    /** Snapshot of pending count — for status-bar indicators. Read-only. */
+    get pending(): number;
+}
 export interface RunAgentOptions {
     readonly prompt: string;
     readonly images?: readonly string[];
@@ -49,6 +89,14 @@ export interface RunAgentOptions {
     readonly signal?: AbortSignal;
     readonly guardrails?: readonly GuardrailCheck[];
     readonly guardrailContext?: GuardrailContext;
+    /**
+     * Optional user-redirect channel. When provided, the loop drains
+     * pending messages BEFORE each iteration's query and appends them
+     * to context as new user turns. Lets the user redirect a streaming
+     * agent without losing context (Hermes Gap 2). See
+     * {@link InMemoryRedirectChannel} for the default implementation.
+     */
+    readonly redirectChannel?: RedirectChannel;
     readonly query: (o: WotannQueryOptions) => AsyncGenerator<StreamChunk>;
     readonly executeTool: (name: string, input: Record<string, unknown>) => Promise<string>;
 }

package/dist/core/runtime-agent-loop.js

@@ -1,5 +1,31 @@
 import { evaluateGuardrails, } from "../guardrails/tripwire.js";
-import { IntelligenceAmplifier, updateDoomLoopState } from "../intelligence/amplifier.js";
+import { IntelligenceAmplifier, updateDoomLoopState, } from "../intelligence/amplifier.js";
+/**
+ * Default in-memory channel. Pushes are appended to a queue; drain
+ * empties the queue atomically. The queue ignores empty-string pushes
+ * so an accidental Ctrl+R on an empty composer doesn't inject a blank
+ * user turn into the model context.
+ */
+export class InMemoryRedirectChannel {
+    queue = [];
+    push(message) {
+        const trimmed = message.trim();
+        if (trimmed.length === 0)
+            return;
+        this.queue.push(trimmed);
+    }
+    drain() {
+        if (this.queue.length === 0)
+            return [];
+        const out = this.queue;
+        this.queue = [];
+        return out;
+    }
+    /** Snapshot of pending count — for status-bar indicators. Read-only. */
+    get pending() {
+        return this.queue.length;
+    }
+}
 export async function* runAgent(opts) {
     const maxIterations = opts.maxIterations ?? 8;
     const guardrails = opts.guardrails ?? [];
@@ -20,6 +46,22 @@ export async function* runAgent(opts) {
     while (iteration < maxIterations) {
         iteration++;
         yield { kind: "iteration_start", iteration };
+        // Hermes Gap 2 — drain user-side redirects BEFORE this iteration's
+        // query. Each pending message becomes a new user turn appended to
+        // context, so the model sees the directive on its next turn. No
+        // abort, no context loss. We emit a `redirect_received` control
+        // event so UI consumers can render a system breadcrumb.
+        if (opts.redirectChannel !== undefined) {
+            const pending = opts.redirectChannel.drain();
+            if (pending.length > 0) {
+                const next = [...context];
+                for (const msg of pending) {
+                    next.push({ role: "user", content: msg });
+                }
+                context = next;
+                yield { kind: "redirect_received", count: pending.length, messages: pending };
+            }
+        }
         let fullContent = "";
         let model;
         let provider;

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/dist/ui/components/v3/AppV3.js

@@ -41,7 +41,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "#wotann-jsx/j
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Box, Text, useInput } from "ink";
-import { runAgent } from "../../../core/runtime-agent-loop.js";
+import { InMemoryRedirectChannel, runAgent } from "../../../core/runtime-agent-loop.js";
 import { buildAgentToolContext } from "../../../core/agent-tool-context.js";
 import { AGENT_TOOL_DEFINITIONS, executeAgentTool } from "../../../tools/agent-tools.js";
 import { ThemeProvider, useThemeTone } from "../../theme/context.js";
@@ -217,6 +217,13 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
     const [transcriptScrollOffset, setTranscriptScrollOffset] = useState(0);
     const activeRunRef = useRef(null);
     const sideActiveRunRef = useRef(null);
+    // Hermes Gap 2 — interrupt-and-redirect: persistent channel for the
+    // host composer's mid-stream redirects. Ctrl+R captures the current
+    // draft and pushes it here; runAgent's iteration loop drains pending
+    // redirects at the next iteration boundary and appends them to
+    // context as new user turns. One channel per AppV3Inner instance so
+    // pending redirects survive within a session.
+    const redirectChannelRef = useRef(new InMemoryRedirectChannel());
     const [sidePaneDraft, setSidePaneDraft] = useState("");
     const [nowMs, setNowMs] = useState(() => Date.now());
     useEffect(() => {
@@ -241,6 +248,16 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
     // composer is empty so we don't intercept the dot from a typed
     // slash-command argument or filename.
     useInput((input, key) => {
+        // Hermes Gap 2 — Ctrl+R: queue the composer draft as a mid-stream
+        // redirect. ONLY fires when the agent is currently streaming AND
+        // the draft has non-whitespace content. The channel's drain runs
+        // at the next iteration boundary, so the user sees a system
+        // "redirect queued" bubble within ~1 turn.
+        if (key.ctrl && input === "r" && isStreaming && draftValue.trim().length > 0) {
+            redirectChannelRef.current.push(draftValue);
+            setDraftValue("");
+            return;
+        }
         if (key.ctrl && (input === "k" || input === "p")) {
             overlay.open("palette");
             return;
@@ -342,6 +359,7 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
                     provider: initialProvider || undefined,
                     tools: AGENT_TOOL_DEFINITIONS,
                     signal: abortController.signal,
+                    redirectChannel: redirectChannelRef.current,
                     query: (o) => runtime.query(o),
                     executeTool: (name, input) => executeAgentTool(name, input, buildAgentToolContext(runtime, {
                         workingDir: runtime.getWorkingDir(),
@@ -362,6 +380,20 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
                                 },
                             ]);
                         }
+                        else if (ev.kind === "redirect_received") {
+                            // Hermes Gap 2 — UI breadcrumb so user sees the directive
+                            // landed. The loop already appended it to context; we
+                            // ONLY render here (do NOT push to context again).
+                            for (const message of ev.messages) {
+                                setMessages((prev) => [
+                                    ...prev,
+                                    {
+                                        role: "system",
+                                        content: `↳ redirect queued: ${message}`,
+                                    },
+                                ]);
+                            }
+                        }
                         continue;
                     }
                     if (ev.type === "text" && ev.content.length > 0) {

package/package.json

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