@kernel.chat/kbot 3.99.20 → 3.99.22

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

package/dist/integrations/kbot-control-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * kbot-control-client.ts — TCP client for kbot-control.amxd
+ *
+ * Singleton client that connects to the kbot-control Max for Live device
+ * at 127.0.0.1:9000. Newline-delimited JSON-RPC 2.0 over plain TCP.
+ * Zero npm dependencies — uses node:net only.
+ *
+ * Supersedes:
+ *   - ableton-osc.ts (UDP 11000, AbletonOSC Remote Script)
+ *   - ableton-bridge.ts (TCP 9001, AbletonBridge)
+ *   - ableton-m4l.ts (TCP 9999, kbot-bridge.amxd)
+ *
+ * Fallback order when this client can't connect:
+ *   1. kbot-control.amxd (this)
+ *   2. ableton-osc.ts (legacy)
+ *   3. Claude computer-use MCP (last resort)
+ */
+export interface RpcRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface RpcResponse<T = unknown> {
+    jsonrpc: '2.0';
+    id: number | null;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export type Listener = (value: unknown) => void;
+export declare class KbotControlClient {
+    private static instance;
+    private socket;
+    private connected;
+    private buffer;
+    private pending;
+    private listeners;
+    private nextId;
+    private connectAttempt;
+    static HOST: string;
+    static PORT: number;
+    static TIMEOUT: number;
+    static CONNECT_TIMEOUT: number;
+    private constructor();
+    static get(): KbotControlClient;
+    connect(): Promise<void>;
+    private handleData;
+    private handleMessage;
+    call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    subscribe(path: string, fn: Listener): Promise<void>;
+    unsubscribe(path: string, fn: Listener): Promise<void>;
+    private pollers;
+    private startPolling;
+    private stopPolling;
+    disconnect(): void;
+    get isConnected(): boolean;
+}
+/**
+ * Convenience: connect + call + return result.
+ * Throws if kbot-control.amxd isn't loaded in Ableton.
+ */
+export declare function kc<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+//# sourceMappingURL=kbot-control-client.d.ts.map

package/dist/integrations/kbot-control-client.js

@@ -0,0 +1,224 @@
+/**
+ * kbot-control-client.ts — TCP client for kbot-control.amxd
+ *
+ * Singleton client that connects to the kbot-control Max for Live device
+ * at 127.0.0.1:9000. Newline-delimited JSON-RPC 2.0 over plain TCP.
+ * Zero npm dependencies — uses node:net only.
+ *
+ * Supersedes:
+ *   - ableton-osc.ts (UDP 11000, AbletonOSC Remote Script)
+ *   - ableton-bridge.ts (TCP 9001, AbletonBridge)
+ *   - ableton-m4l.ts (TCP 9999, kbot-bridge.amxd)
+ *
+ * Fallback order when this client can't connect:
+ *   1. kbot-control.amxd (this)
+ *   2. ableton-osc.ts (legacy)
+ *   3. Claude computer-use MCP (last resort)
+ */
+import * as net from 'node:net';
+export class KbotControlClient {
+    static instance = null;
+    socket = null;
+    connected = false;
+    buffer = '';
+    pending = new Map();
+    listeners = new Map();
+    nextId = 1;
+    connectAttempt = null;
+    static HOST = '127.0.0.1';
+    static PORT = 9000;
+    static TIMEOUT = 15_000;
+    static CONNECT_TIMEOUT = 3_000;
+    constructor() { }
+    static get() {
+        if (!this.instance)
+            this.instance = new KbotControlClient();
+        return this.instance;
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.connectAttempt)
+            return this.connectAttempt;
+        this.connectAttempt = new Promise((resolve, reject) => {
+            const sock = new net.Socket();
+            const timer = setTimeout(() => {
+                sock.destroy();
+                reject(new Error(`kbot-control: connect timeout (${KbotControlClient.CONNECT_TIMEOUT}ms)`));
+            }, KbotControlClient.CONNECT_TIMEOUT);
+            sock.connect(KbotControlClient.PORT, KbotControlClient.HOST, () => {
+                clearTimeout(timer);
+                this.socket = sock;
+                this.connected = true;
+                resolve();
+            });
+            sock.on('data', (chunk) => this.handleData(chunk.toString()));
+            sock.on('close', () => {
+                this.connected = false;
+                this.socket = null;
+                for (const [, p] of this.pending) {
+                    clearTimeout(p.timer);
+                    p.reject(new Error('kbot-control: connection closed'));
+                }
+                this.pending.clear();
+            });
+            sock.on('error', (e) => {
+                clearTimeout(timer);
+                this.connected = false;
+                reject(new Error(`kbot-control: ${e.message} — is kbot-control.amxd loaded in Ableton on a track?`));
+            });
+        });
+        try {
+            await this.connectAttempt;
+        }
+        finally {
+            this.connectAttempt = null;
+        }
+    }
+    handleData(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() || '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            this.handleMessage(trimmed);
+        }
+    }
+    handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        // Notifications (listener events) — no id
+        if ('method' in msg && msg.method === 'notify') {
+            const { path, value } = msg.params || {};
+            if (path) {
+                const set = this.listeners.get(path);
+                if (set)
+                    for (const fn of set)
+                        fn(value);
+            }
+            return;
+        }
+        // Server hello greeting
+        if ('method' in msg && msg.method === 'hello')
+            return;
+        const response = msg;
+        if (response.id == null)
+            return;
+        const p = this.pending.get(response.id);
+        if (!p)
+            return;
+        this.pending.delete(response.id);
+        clearTimeout(p.timer);
+        if (response.error)
+            p.reject(new Error(`[${response.error.code}] ${response.error.message}`));
+        else
+            p.resolve(response.result);
+    }
+    async call(method, params) {
+        await this.connect();
+        if (!this.socket)
+            throw new Error('kbot-control: not connected');
+        const id = this.nextId++;
+        const req = { jsonrpc: '2.0', id, method, params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`kbot-control: timeout on ${method} (${KbotControlClient.TIMEOUT}ms)`));
+            }, KbotControlClient.TIMEOUT);
+            this.pending.set(id, {
+                resolve: (r) => resolve(r),
+                reject,
+                timer,
+            });
+            this.socket.write(JSON.stringify(req) + '\n');
+        });
+    }
+    async subscribe(path, fn) {
+        let set = this.listeners.get(path);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(path, set);
+            await this.call('listen.subscribe', { path });
+            // Start a polling loop as a fallback until the outlet-based push works.
+            // This also catches events even when the push path breaks.
+            this.startPolling(path);
+        }
+        set.add(fn);
+    }
+    async unsubscribe(path, fn) {
+        const set = this.listeners.get(path);
+        if (!set)
+            return;
+        set.delete(fn);
+        if (set.size === 0) {
+            this.listeners.delete(path);
+            this.stopPolling(path);
+            try {
+                await this.call('listen.unsubscribe', { path });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    pollers = new Map();
+    startPolling(path, intervalMs = 150) {
+        if (this.pollers.has(path))
+            return;
+        const state = { timer: null, since: 0 };
+        state.timer = setInterval(async () => {
+            try {
+                const r = await this.call('listen.poll', { path, since: state.since });
+                if (r && r.events && r.events.length > 0) {
+                    state.since = r.latest_seq;
+                    const set = this.listeners.get(path);
+                    if (set) {
+                        for (const ev of r.events) {
+                            // LiveAPI often reports values as [propertyName, value]; unwrap.
+                            let v = ev.value;
+                            if (Array.isArray(v) && v.length === 2 && typeof v[0] === 'string')
+                                v = v[1];
+                            for (const fn of set)
+                                fn(v);
+                        }
+                    }
+                }
+                else if (r && typeof r.latest_seq === 'number') {
+                    state.since = r.latest_seq;
+                }
+            }
+            catch { /* ignore transient errors */ }
+        }, intervalMs);
+        this.pollers.set(path, state);
+    }
+    stopPolling(path) {
+        const s = this.pollers.get(path);
+        if (s) {
+            clearInterval(s.timer);
+            this.pollers.delete(path);
+        }
+    }
+    disconnect() {
+        for (const [, s] of this.pollers)
+            clearInterval(s.timer);
+        this.pollers.clear();
+        if (this.socket)
+            this.socket.destroy();
+        this.socket = null;
+        this.connected = false;
+    }
+    get isConnected() { return this.connected; }
+}
+/**
+ * Convenience: connect + call + return result.
+ * Throws if kbot-control.amxd isn't loaded in Ableton.
+ */
+export async function kc(method, params) {
+    return KbotControlClient.get().call(method, params);
+}
+//# sourceMappingURL=kbot-control-client.js.map

package/dist/observer.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Outcome classification for tool calls.
+ * Required for training an action-token model — cannot be backfilled from logs.
+ */
+export type ToolOutcome = 'success' | 'error' | 'timeout' | 'empty' | 'large';
 export interface ObservedToolCall {
     ts: string;
     tool: string;
@@ -5,6 +10,14 @@ export interface ObservedToolCall {
     result_length?: number;
     session?: string;
     error?: boolean;
+    /** Schema version. Absent = v1 (legacy). 2 = includes durationMs/outcome/resultSize. */
+    schema?: number;
+    /** Wall-clock duration of tool execution in milliseconds. (schema v2+) */
+    durationMs?: number;
+    /** Outcome classification for training. (schema v2+) */
+    outcome?: ToolOutcome;
+    /** Bytes of serialized result (Buffer.byteLength of result string). (schema v2+) */
+    resultSize?: number;
 }
 export interface ObserverStats {
     totalObserved: number;