@kernel.chat/kbot 3.99.20 → 3.99.21

package/dist/critic-retrospect.js

@@ -0,0 +1,279 @@
+/**
+ * Critic Retrospect — retroactive judgement of past session tool calls.
+ *
+ * Reads ~/.kbot/observer/session.jsonl, replays tool calls through
+ * gateToolResult (critic-gate.ts), and reports:
+ *   - overall accept/reject ratio
+ *   - tools with highest reject rate (args-validation candidates)
+ *   - rejects that were later retried successfully (critic false positives)
+ *   - sessions ranked by "retries saved" score
+ *   - suggested strictness setting from precision/recall tradeoff
+ *
+ * NB: the observer only logs {ts, tool, args, session} — no results.
+ * We synthesize a *result proxy* from retry behaviour: a call whose exact
+ * (tool, args-hash) recurs inside the same session within RETRY_WINDOW_MS
+ * is treated as having implicitly failed the first time. The critic is
+ * passed this synthesized signal so it can judge on intent + shape.
+ *
+ * Cache: ~/.kbot/critic-cache.json — keyed by (tool, argsHash, resultHash).
+ *
+ * CLI wiring: cli.ts was modified in parallel; leaving subcommand wiring
+ * as a TODO. Invoke via `node -e "import('./dist/critic-retrospect.js').then(m => m.run())"`.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { gateToolResult } from './critic-gate.js';
+const OBSERVER_PATH = join(homedir(), '.kbot', 'observer', 'session.jsonl');
+const CACHE_PATH = join(homedir(), '.kbot', 'critic-cache.json');
+const RETRY_WINDOW_MS = 2 * 60 * 1000; // 2 minutes
+function sha(s) { return createHash('sha256').update(s).digest('hex').slice(0, 16); }
+function hashArgs(args) { try {
+    return sha(JSON.stringify(args));
+}
+catch {
+    return sha(String(args));
+} }
+function loadCache() {
+    if (!existsSync(CACHE_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CACHE_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function saveCache(c) {
+    try {
+        mkdirSync(dirname(CACHE_PATH), { recursive: true });
+        writeFileSync(CACHE_PATH, JSON.stringify(c, null, 2));
+    }
+    catch { /* best-effort */ }
+}
+function readEvents() {
+    if (!existsSync(OBSERVER_PATH))
+        return [];
+    const raw = readFileSync(OBSERVER_PATH, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e && e.tool && e.session && e.ts)
+                out.push(e);
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
+/** Group events by session; keep last N sessions (by latest ts). */
+function pickLastNSessions(events, n) {
+    const bySession = new Map();
+    for (const e of events) {
+        const arr = bySession.get(e.session) ?? [];
+        arr.push(e);
+        bySession.set(e.session, arr);
+    }
+    const ordered = [...bySession.entries()]
+        .map(([id, evs]) => ({ id, evs, lastTs: Date.parse(evs[evs.length - 1].ts) || 0 }))
+        .sort((a, b) => b.lastTs - a.lastTs);
+    const pick = ordered.slice(0, n);
+    const picked = new Map();
+    for (const p of pick)
+        picked.set(p.id, p.evs);
+    return { picked, available: bySession.size };
+}
+/** Annotate each call with retry info inside its session. */
+function enrich(sessionEvents) {
+    const calls = sessionEvents.map(e => ({
+        ...e, argsHash: hashArgs({ tool: e.tool, args: e.args }), retriedLater: false, retrySucceeded: false,
+    }));
+    // Two-pass: mark retriedLater, then mark retrySucceeded.
+    for (let i = 0; i < calls.length; i++) {
+        const a = calls[i];
+        const at = Date.parse(a.ts) || 0;
+        for (let j = i + 1; j < calls.length; j++) {
+            const b = calls[j];
+            const bt = Date.parse(b.ts) || 0;
+            if (bt - at > RETRY_WINDOW_MS)
+                break;
+            if (b.tool === a.tool && b.argsHash === a.argsHash) {
+                a.retriedLater = true;
+                break;
+            }
+        }
+    }
+    for (let i = 0; i < calls.length; i++) {
+        if (!calls[i].retriedLater)
+            continue;
+        // If the LAST occurrence of (tool,argsHash) in this session is NOT retriedLater, consider retry "succeeded".
+        for (let j = calls.length - 1; j > i; j--) {
+            if (calls[j].tool === calls[i].tool && calls[j].argsHash === calls[i].argsHash) {
+                calls[i].retrySucceeded = !calls[j].retriedLater;
+                break;
+            }
+        }
+    }
+    return calls;
+}
+/** Build a synthetic "result" proxy to feed the critic. */
+function synthResult(c) {
+    if (c.retriedLater)
+        return `[observer-proxy] no result captured; same (tool,args) was retried within ${RETRY_WINDOW_MS / 1000}s — likely failed or unsatisfactory.`;
+    return `[observer-proxy] no result captured; call was not retried in-session — presumed accepted by the agent downstream.`;
+}
+async function judge(c, strictness, cache, llmClient) {
+    const resultProxy = synthResult(c);
+    const resultHash = sha(resultProxy);
+    const key = `${c.tool}:${c.argsHash}:${resultHash}:${strictness.toFixed(2)}`;
+    const hit = cache[key];
+    if (hit)
+        return hit.verdict;
+    const verdict = await gateToolResult(c.tool, c.args, resultProxy, { strictness, llmClient });
+    cache[key] = { verdict, cachedAt: new Date().toISOString() };
+    return verdict;
+}
+/** Precision/recall math.
+ *  We treat "retriedLater" as ground-truth "call was bad".
+ *  Critic rejects = positives.
+ *    TP = reject && retriedLater    (correct catch)
+ *    FP = reject && !retriedLater   (nagged a fine call)
+ *    FN = accept && retriedLater    (missed a bad call)
+ *    TN = accept && !retriedLater   (correct pass)
+ *  Precision = TP / (TP + FP)  — of rejects, how many were real
+ *  Recall    = TP / (TP + FN)  — of bad calls, how many did we catch
+ *  Sweep strictness-equivalent proxy: threshold on verdict.confidence for rejects.
+ */
+function prCurve(rows) {
+    const candidates = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9];
+    let best = { s: 0.5, f1: -1, p: 0, r: 0 };
+    for (const s of candidates) {
+        let tp = 0, fp = 0, fn = 0;
+        for (const r of rows) {
+            const gatedReject = r.reject && r.confidence >= 1 - s; // stricter => more rejects pass through
+            if (gatedReject && r.bad)
+                tp++;
+            else if (gatedReject && !r.bad)
+                fp++;
+            else if (!gatedReject && r.bad)
+                fn++;
+        }
+        const p = tp + fp > 0 ? tp / (tp + fp) : 0;
+        const rec = tp + fn > 0 ? tp / (tp + fn) : 0;
+        const f1 = p + rec > 0 ? (2 * p * rec) / (p + rec) : 0;
+        if (f1 > best.f1)
+            best = { s, f1, p, r: rec };
+    }
+    return { suggested: best.s, precision: best.p, recall: best.r };
+}
+export async function run(opts = {}) {
+    const nSessions = opts.sessions ?? 10;
+    const strictness = opts.strictness ?? 0.5;
+    const perSessionCap = opts.maxCallsPerSession ?? 50;
+    const events = readEvents();
+    const { picked, available } = pickLastNSessions(events, nSessions);
+    const cache = loadCache();
+    const byTool = {};
+    const falsePositives = [];
+    const sessionStats = [];
+    const prRows = [];
+    let accepts = 0, rejects = 0, totalCalls = 0;
+    for (const [sid, evs] of picked) {
+        const enriched = enrich(evs).slice(0, perSessionCap);
+        let sessionRetriesSaved = 0;
+        for (const c of enriched) {
+            const v = await judge(c, strictness, cache, opts.llmClient);
+            totalCalls++;
+            const bucket = byTool[c.tool] ?? (byTool[c.tool] = { total: 0, accepts: 0, rejects: 0 });
+            bucket.total++;
+            if (v.accept) {
+                accepts++;
+                bucket.accepts++;
+            }
+            else {
+                rejects++;
+                bucket.rejects++;
+            }
+            prRows.push({ reject: !v.accept, bad: c.retriedLater, confidence: v.confidence });
+            if (!v.accept && c.retriedLater)
+                sessionRetriesSaved++;
+            // Likely false positives: critic rejected, but the call was NOT retried (so downstream accepted it).
+            if (!v.accept && !c.retriedLater) {
+                falsePositives.push({ tool: c.tool, session: sid, retryGap: 0, reason: v.reason });
+            }
+            // Also: rejected AND the retry later succeeded — still a FP if the agent had listened and skipped, it would have worked anyway.
+            if (!v.accept && c.retrySucceeded) {
+                falsePositives.push({ tool: c.tool, session: sid, retryGap: RETRY_WINDOW_MS, reason: `retry later succeeded: ${v.reason ?? ''}` });
+            }
+        }
+        sessionStats.push({ session: sid, calls: enriched.length, retriesSaved: sessionRetriesSaved, score: sessionRetriesSaved / Math.max(1, enriched.length) });
+    }
+    saveCache(cache);
+    const topRejectRate = Object.entries(byTool)
+        .filter(([, v]) => v.total >= 3)
+        .map(([tool, v]) => ({ tool, total: v.total, rejectRate: v.rejects / v.total }))
+        .sort((a, b) => b.rejectRate - a.rejectRate)
+        .slice(0, 5);
+    const sessionsRanked = sessionStats.sort((a, b) => b.score - a.score).slice(0, 10);
+    const fpTop = falsePositives.slice(0, 5);
+    const pr = prCurve(prRows);
+    const report = {
+        totalCalls, sessionsScanned: picked.size, sessionsAvailable: available,
+        accepts, rejects, byTool, topRejectRate, likelyFalsePositives: fpTop,
+        sessionsRanked, suggestedStrictness: pr.suggested, precision: pr.precision, recall: pr.recall,
+    };
+    renderReport(report);
+    if (opts.jsonOut) {
+        try {
+            writeFileSync(opts.jsonOut, JSON.stringify(report, null, 2));
+            console.log(`\nJSON written → ${opts.jsonOut}`);
+        }
+        catch (e) {
+            console.error(`JSON export failed: ${e.message}`);
+        }
+    }
+    return report;
+}
+function renderReport(r) {
+    const line = (s = '') => console.log(s);
+    line('\n=== Critic Retrospective ===');
+    line(`sessions scanned: ${r.sessionsScanned} / ${r.sessionsAvailable} available`);
+    line(`tool calls judged: ${r.totalCalls}`);
+    const ratio = r.totalCalls ? (r.accepts / r.totalCalls) : 0;
+    line(`accept/reject: ${r.accepts} / ${r.rejects}  (accept-rate ${(ratio * 100).toFixed(1)}%)`);
+    line('\n-- top 5 reject rate (candidates for args validation) --');
+    if (!r.topRejectRate.length)
+        line('  (no tool has >=3 calls)');
+    for (const t of r.topRejectRate)
+        line(`  ${t.tool.padEnd(28)}  ${(t.rejectRate * 100).toFixed(1)}% rejected  (${t.total} calls)`);
+    line('\n-- likely critic false positives (rejected but agent did not retry OR retry worked) --');
+    if (!r.likelyFalsePositives.length)
+        line('  (none)');
+    for (const fp of r.likelyFalsePositives)
+        line(`  ${fp.tool.padEnd(28)}  session=${fp.session.slice(0, 8)}  ${fp.reason ?? ''}`);
+    line('\n-- sessions ranked by retries-saved score --');
+    for (const s of r.sessionsRanked.slice(0, 5))
+        line(`  ${s.session.slice(0, 8)}  calls=${s.calls}  saved=${s.retriesSaved}  score=${s.score.toFixed(3)}`);
+    line('\n-- precision / recall tradeoff --');
+    line(`  precision = ${r.precision.toFixed(3)}   recall = ${r.recall.toFixed(3)}`);
+    line(`  suggested critic_strictness = ${r.suggestedStrictness.toFixed(2)}`);
+    line('');
+}
+// TODO(cli-wiring): register `kbot critic retrospect` subcommand in cli.ts once
+// the parallel skills-subcommand edit lands. For now, invoke via:
+//   node -e "import('./dist/critic-retrospect.js').then(m => m.run({ sessions: 20 }))"
+// Direct-execution entrypoint for `node dist/critic-retrospect.js`.
+const argv1 = process.argv[1] || '';
+if (argv1.endsWith('critic-retrospect.js') || argv1.endsWith('critic-retrospect.ts')) {
+    const sessionsArg = process.argv.find(a => a.startsWith('--sessions='));
+    const jsonArg = process.argv.find(a => a.startsWith('--json='));
+    const strictArg = process.argv.find(a => a.startsWith('--strictness='));
+    const sessions = sessionsArg ? Number(sessionsArg.split('=')[1]) : 10;
+    const strictness = strictArg ? Number(strictArg.split('=')[1]) : undefined;
+    const jsonOut = jsonArg ? jsonArg.split('=')[1] : undefined;
+    run({ sessions, strictness, jsonOut }).catch(e => { console.error(e); process.exit(1); });
+}
+//# sourceMappingURL=critic-retrospect.js.map

package/dist/growth.d.ts

@@ -0,0 +1,37 @@
+interface GrowthSummary {
+    betterPct: number;
+    days: number;
+    sessions: number;
+    toolCalls: number;
+    successRate: number;
+    routingAccuracy: number;
+    newPatterns: number;
+}
+interface GrowthResult {
+    summary: GrowthSummary;
+    metrics: Array<{
+        label: string;
+        current: number;
+        prior: number;
+        delta: number;
+    }>;
+    deltas: Array<{
+        tool: string;
+        current: number;
+        prior: number;
+        delta: number;
+    }>;
+    agents: Array<{
+        agent: string;
+        accuracy: number;
+        samples: number;
+    }>;
+}
+export declare function runGrowth(opts?: {
+    json?: boolean;
+    days?: number;
+    dataDir?: string;
+    now?: number;
+}): GrowthResult | null;
+export {};
+//# sourceMappingURL=growth.d.ts.map

package/dist/growth.js

@@ -0,0 +1,272 @@
+// kbot growth — Make kbot's learning visible. Reads local learning artifacts
+// (~/.kbot/skill-profile.json, confidence.json, evolution-state.json,
+// observer/session.jsonl) and shows a week-over-week improvement report.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+function pathsFor(dataDir) {
+    return {
+        skill: join(dataDir, 'skill-profile.json'),
+        confidence: join(dataDir, 'confidence.json'),
+        evolution: join(dataDir, 'evolution-state.json'),
+        observer: join(dataDir, 'observer', 'session.jsonl'),
+    };
+}
+function readJsonSafe(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readObserver(observerPath) {
+    if (!existsSync(observerPath))
+        return [];
+    try {
+        const raw = readFileSync(observerPath, 'utf8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function inWindow(ts, start, end) {
+    const t = Date.parse(ts);
+    if (Number.isNaN(t))
+        return false;
+    return t >= start && t < end;
+}
+function computeWindow(events, confidence, start, end) {
+    const sessions = new Set();
+    const toolCounts = {};
+    const agentCounts = {};
+    let toolCalls = 0;
+    let errors = 0;
+    for (const e of events) {
+        if (!inWindow(e.ts, start, end))
+            continue;
+        toolCalls++;
+        if (e.error === true)
+            errors++;
+        if (e.session)
+            sessions.add(e.session);
+        toolCounts[e.tool] = (toolCounts[e.tool] ?? 0) + 1;
+        const agent = typeof e.args?.['agent'] === 'string' ? e.args['agent'] : null;
+        if (agent)
+            agentCounts[agent] = (agentCounts[agent] ?? 0) + 1;
+    }
+    const successRate = toolCalls > 0 ? (toolCalls - errors) / toolCalls : 0;
+    // Routing accuracy: |predicted - actual| <= 0.2 counts as accurate
+    let routingSamples = 0;
+    let routingHits = 0;
+    for (const c of confidence) {
+        if (!inWindow(c.timestamp, start, end))
+            continue;
+        routingSamples++;
+        if (Math.abs(c.predicted - c.actual) <= 0.2)
+            routingHits++;
+    }
+    const routingAccuracy = routingSamples > 0 ? routingHits / routingSamples : 0;
+    return {
+        sessions: sessions.size,
+        toolCalls,
+        errors,
+        successRate,
+        routingAccuracy,
+        toolCounts,
+        agentCounts,
+    };
+}
+function topToolDeltas(current, prior, limit = 5) {
+    const tools = new Set([...Object.keys(current), ...Object.keys(prior)]);
+    const rows = [];
+    for (const t of tools) {
+        const c = current[t] ?? 0;
+        const p = prior[t] ?? 0;
+        if (c + p === 0)
+            continue;
+        rows.push({ tool: t, current: c, prior: p, delta: c - p });
+    }
+    rows.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+    return rows.slice(0, limit);
+}
+function perAgentRouting(confidence, start, end) {
+    const agg = {};
+    for (const c of confidence) {
+        if (!inWindow(c.timestamp, start, end))
+            continue;
+        const domain = c.domain || 'general';
+        const bucket = (agg[domain] ??= { hits: 0, total: 0 });
+        bucket.total++;
+        if (Math.abs(c.predicted - c.actual) <= 0.2)
+            bucket.hits++;
+    }
+    return Object.entries(agg)
+        .map(([agent, v]) => ({ agent, accuracy: v.total > 0 ? v.hits / v.total : 0, samples: v.total }))
+        .sort((a, b) => b.samples - a.samples)
+        .slice(0, 8);
+}
+function blendScore(successRate, routingAccuracy) {
+    // 60% tool success, 40% routing. Fall back to either if one is missing.
+    if (successRate === 0 && routingAccuracy === 0)
+        return 0;
+    if (routingAccuracy === 0)
+        return successRate;
+    if (successRate === 0)
+        return routingAccuracy;
+    return successRate * 0.6 + routingAccuracy * 0.4;
+}
+const pct = (n) => `${(n * 100).toFixed(1)}%`;
+function bar(n, width = 20) {
+    const filled = Math.max(0, Math.min(width, Math.round(n * width)));
+    return chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(width - filled));
+}
+function renderNotEnoughData() {
+    return [
+        '',
+        `  ${chalk.bold('kbot growth')}`,
+        `  ${chalk.dim('─'.repeat(40))}`,
+        '',
+        `  ${chalk.yellow('Not enough data yet.')}`,
+        '',
+        `  kbot learns from your sessions. To seed it:`,
+        `    • Run ${chalk.bold('kbot')} on real work for a few days`,
+        `    • Let the observer log tool calls to ${chalk.dim('~/.kbot/observer/session.jsonl')}`,
+        `    • Re-run ${chalk.bold('kbot growth')} after ~3 sessions`,
+        '',
+    ].join('\n');
+}
+function renderPretty(result) {
+    const s = result.summary;
+    const lines = [];
+    lines.push('');
+    lines.push(`  ${chalk.bold('kbot growth')}  ${chalk.dim(`— last ${s.days} days vs prior ${s.days}`)}`);
+    lines.push(`  ${chalk.dim('─'.repeat(60))}`);
+    lines.push('');
+    const headlineColor = s.betterPct >= 0 ? chalk.green : chalk.red;
+    const sign = s.betterPct >= 0 ? '+' : '';
+    lines.push(`  ${chalk.bold('kbot is')} ${headlineColor.bold(`${sign}${s.betterPct.toFixed(1)}%`)} ${chalk.bold('better at your tasks this week')}`);
+    lines.push('');
+    // Core metrics table
+    lines.push(`  ${chalk.bold('Metrics')}`);
+    lines.push(`  ${chalk.dim('─'.repeat(60))}`);
+    for (const m of result.metrics) {
+        const arrow = m.delta > 0 ? chalk.green('▲') : m.delta < 0 ? chalk.red('▼') : chalk.dim('·');
+        const isRate = m.label.includes('rate') || m.label.includes('accuracy');
+        const cur = isRate ? pct(m.current) : String(Math.round(m.current));
+        const prev = isRate ? pct(m.prior) : String(Math.round(m.prior));
+        const deltaStr = isRate
+            ? `${m.delta >= 0 ? '+' : ''}${(m.delta * 100).toFixed(1)}pp`
+            : `${m.delta >= 0 ? '+' : ''}${Math.round(m.delta)}`;
+        lines.push(`  ${arrow} ${m.label.padEnd(24)} ${cur.padStart(8)}  ${chalk.dim(`prev ${prev}`)}  ${chalk.bold(deltaStr)}`);
+    }
+    lines.push('');
+    // Tool deltas
+    if (result.deltas.length > 0) {
+        lines.push(`  ${chalk.bold('Top tools by usage delta')}`);
+        lines.push(`  ${chalk.dim('─'.repeat(60))}`);
+        for (const d of result.deltas) {
+            const arrow = d.delta > 0 ? chalk.green('▲') : d.delta < 0 ? chalk.red('▼') : chalk.dim('·');
+            const deltaStr = `${d.delta >= 0 ? '+' : ''}${d.delta}`;
+            lines.push(`  ${arrow} ${d.tool.padEnd(30)} ${String(d.current).padStart(5)}  ${chalk.dim(`prev ${d.prior}`)}  ${chalk.bold(deltaStr)}`);
+        }
+        lines.push('');
+    }
+    // Per-agent routing
+    if (result.agents.length > 0) {
+        lines.push(`  ${chalk.bold('Per-domain routing accuracy')}`);
+        lines.push(`  ${chalk.dim('─'.repeat(60))}`);
+        for (const a of result.agents) {
+            lines.push(`  ${a.agent.padEnd(16)} ${bar(a.accuracy)}  ${pct(a.accuracy).padStart(6)}  ${chalk.dim(`n=${a.samples}`)}`);
+        }
+        lines.push('');
+    }
+    lines.push(`  ${chalk.dim(`New patterns learned: ${s.newPatterns}`)}`);
+    lines.push('');
+    return lines.join('\n');
+}
+export function runGrowth(opts = {}) {
+    const days = Math.max(1, Math.floor(opts.days ?? 7));
+    const now = opts.now ?? Date.now();
+    const dayMs = 24 * 60 * 60 * 1000;
+    const currentStart = now - days * dayMs;
+    const priorStart = now - 2 * days * dayMs;
+    const paths = pathsFor(opts.dataDir ?? join(homedir(), '.kbot'));
+    const events = readObserver(paths.observer);
+    const confidenceRaw = readJsonSafe(paths.confidence);
+    const confidence = confidenceRaw?.entries ?? [];
+    const skillRaw = readJsonSafe(paths.skill);
+    const skills = skillRaw?.skills ?? {};
+    // evolution state is read to surface future signals; currently used only as a
+    // signal that the file exists and kbot has evolved behaviours.
+    const evolution = readJsonSafe(paths.evolution);
+    if (events.length === 0 && confidence.length === 0 && Object.keys(skills).length === 0) {
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ summary: null, metrics: [], deltas: [] }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(renderNotEnoughData() + '\n');
+        }
+        return null;
+    }
+    const cur = computeWindow(events, confidence, currentStart, now);
+    const prior = computeWindow(events, confidence, priorStart, currentStart);
+    // "Better by N%": compare blended score now vs prior, as a relative lift.
+    const curBlend = blendScore(cur.successRate, cur.routingAccuracy);
+    const priBlend = blendScore(prior.successRate, prior.routingAccuracy);
+    const betterPct = priBlend > 0 ? ((curBlend - priBlend) / priBlend) * 100 : curBlend > 0 ? 100 : 0;
+    // New patterns learned: skills whose lastAttempt is in the current window.
+    let newPatterns = 0;
+    for (const entry of Object.values(skills)) {
+        if (entry.lastAttempt && inWindow(entry.lastAttempt, currentStart, now))
+            newPatterns++;
+    }
+    // Plus unique new domains appearing in confidence in current window but not prior.
+    const priorDomains = new Set(confidence.filter((c) => inWindow(c.timestamp, priorStart, currentStart)).map((c) => c.domain));
+    const newDomains = new Set(confidence
+        .filter((c) => inWindow(c.timestamp, currentStart, now))
+        .map((c) => c.domain)
+        .filter((d) => !priorDomains.has(d)));
+    newPatterns += newDomains.size;
+    void evolution; // evolution data reserved for future deltas
+    const summary = {
+        betterPct,
+        days,
+        sessions: cur.sessions,
+        toolCalls: cur.toolCalls,
+        successRate: cur.successRate,
+        routingAccuracy: cur.routingAccuracy,
+        newPatterns,
+    };
+    const metrics = [
+        { label: 'sessions', current: cur.sessions, prior: prior.sessions, delta: cur.sessions - prior.sessions },
+        { label: 'tool calls', current: cur.toolCalls, prior: prior.toolCalls, delta: cur.toolCalls - prior.toolCalls },
+        { label: 'tool success rate', current: cur.successRate, prior: prior.successRate, delta: cur.successRate - prior.successRate },
+        { label: 'routing accuracy', current: cur.routingAccuracy, prior: prior.routingAccuracy, delta: cur.routingAccuracy - prior.routingAccuracy },
+    ];
+    const deltas = topToolDeltas(cur.toolCounts, prior.toolCounts, 5);
+    const agents = perAgentRouting(confidence, currentStart, now);
+    const result = { summary, metrics, deltas, agents };
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return result;
+    }
+    process.stdout.write(renderPretty(result) + '\n');
+    return result;
+}
+//# sourceMappingURL=growth.js.map

package/dist/integrations/ableton.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ableton.ts — unified Ableton client helper.
+ *
+ * Single entry point for all kbot Ableton tools. Tries kbot-control.amxd
+ * (TCP:9000) first; falls back to AbletonOSC (UDP:11000) if the device
+ * isn't loaded. Over time, as kbot-control's dispatcher covers the full
+ * OSC surface, the OSC fallback goes away.
+ *
+ * Tool code should import from here, not from kbot-control-client.ts
+ * or ableton-osc.ts directly.
+ */
+import { ensureAbleton, type OscArg } from './ableton-osc.js';
+/**
+ * Call a kbot-control method if the device is loaded. Returns undefined
+ * if unavailable — caller should fall back to OSC.
+ */
+export declare function tryKc<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T | undefined>;
+/**
+ * Route an OSC operation through kbot-control if possible, else AbletonOSC.
+ * The two functions are called with the same args — whichever resolves wins.
+ *
+ * Use when you have parallel implementations. Example:
+ *   await routed(
+ *     () => tryKc('song.tempo', { value: 120 }),
+ *     async () => { (await ensureAbleton()).send('/live/song/set/tempo', 120); return 120 },
+ *   )
+ */
+export declare function routed<T>(kc: () => Promise<T | undefined>, osc: () => Promise<T>): Promise<T>;
+export { ensureAbleton, type OscArg };
+//# sourceMappingURL=ableton.d.ts.map

package/dist/integrations/ableton.js

@@ -0,0 +1,66 @@
+/**
+ * ableton.ts — unified Ableton client helper.
+ *
+ * Single entry point for all kbot Ableton tools. Tries kbot-control.amxd
+ * (TCP:9000) first; falls back to AbletonOSC (UDP:11000) if the device
+ * isn't loaded. Over time, as kbot-control's dispatcher covers the full
+ * OSC surface, the OSC fallback goes away.
+ *
+ * Tool code should import from here, not from kbot-control-client.ts
+ * or ableton-osc.ts directly.
+ */
+import { KbotControlClient } from './kbot-control-client.js';
+import { ensureAbleton } from './ableton-osc.js';
+let kbotControlAvailable = null;
+let lastProbeAt = 0;
+const PROBE_CACHE_MS = 5_000;
+async function probeKbotControl() {
+    const now = Date.now();
+    if (kbotControlAvailable !== null && now - lastProbeAt < PROBE_CACHE_MS) {
+        return kbotControlAvailable;
+    }
+    try {
+        await KbotControlClient.get().connect();
+        kbotControlAvailable = KbotControlClient.get().isConnected;
+    }
+    catch {
+        kbotControlAvailable = false;
+    }
+    lastProbeAt = now;
+    return kbotControlAvailable;
+}
+/**
+ * Call a kbot-control method if the device is loaded. Returns undefined
+ * if unavailable — caller should fall back to OSC.
+ */
+export async function tryKc(method, params) {
+    if (!(await probeKbotControl()))
+        return undefined;
+    try {
+        return await KbotControlClient.get().call(method, params);
+    }
+    catch {
+        // Method might not be implemented yet in the dispatcher;
+        // let the caller fall through to OSC.
+        return undefined;
+    }
+}
+/**
+ * Route an OSC operation through kbot-control if possible, else AbletonOSC.
+ * The two functions are called with the same args — whichever resolves wins.
+ *
+ * Use when you have parallel implementations. Example:
+ *   await routed(
+ *     () => tryKc('song.tempo', { value: 120 }),
+ *     async () => { (await ensureAbleton()).send('/live/song/set/tempo', 120); return 120 },
+ *   )
+ */
+export async function routed(kc, osc) {
+    const v = await kc();
+    if (v !== undefined)
+        return v;
+    return osc();
+}
+// Re-export the legacy OSC escape hatch for tools that haven't migrated yet.
+export { ensureAbleton };
+//# sourceMappingURL=ableton.js.map