@kernel.chat/kbot 3.69.1 → 3.71.0

package/dist/integrations/ableton-m4l.js

@@ -301,7 +301,204 @@ export class AbletonM4L {
         return this.send({ action: 'lom_call', path, method, args });
     }
 }
-// ── Convenience export ──────────────────────────────────────────────
+/**
+ * Client for the KBotBridge Remote Script (TCP 9998).
+ *
+ * This is separate from the M4L bridge (9999) because the Browser API
+ * (browser.load_item) is ONLY available from Python Remote Scripts,
+ * not from Max for Live.
+ *
+ * Use this to programmatically load any native device (Saturator,
+ * EQ Eight, Compressor, etc.) onto any track.
+ */
+export class AbletonBrowserBridge {
+    static instance = null;
+    socket = null;
+    connected = false;
+    pending = new Map();
+    nextId = 1;
+    buffer = '';
+    static PORT = 9998;
+    static HOST = '127.0.0.1';
+    static TIMEOUT = 15_000; // Browser operations can be slow
+    constructor() { }
+    static getInstance() {
+        if (!AbletonBrowserBridge.instance) {
+            AbletonBrowserBridge.instance = new AbletonBrowserBridge();
+        }
+        return AbletonBrowserBridge.instance;
+    }
+    /**
+     * Connect to the KBotBridge Remote Script on port 9998.
+     * Returns true if connected and the bridge responds to ping.
+     */
+    async connect() {
+        if (this.connected && this.socket) {
+            try {
+                await this.send({ action: 'ping' });
+                return true;
+            }
+            catch {
+                this.disconnect();
+            }
+        }
+        return new Promise((resolve) => {
+            this.socket = new net.Socket();
+            this.buffer = '';
+            this.socket.on('data', (data) => {
+                this.buffer += data.toString();
+                const lines = this.buffer.split('\n');
+                this.buffer = lines.pop() || '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    try {
+                        const response = JSON.parse(trimmed);
+                        this.handleResponse(response);
+                    }
+                    catch {
+                        // Malformed JSON — skip
+                    }
+                }
+            });
+            this.socket.on('error', () => {
+                if (!this.connected)
+                    resolve(false);
+                this.handleDisconnect();
+            });
+            this.socket.on('close', () => {
+                this.handleDisconnect();
+            });
+            this.socket.connect(AbletonBrowserBridge.PORT, AbletonBrowserBridge.HOST, async () => {
+                this.connected = true;
+                try {
+                    const pong = await this.send({ action: 'ping' });
+                    resolve(pong.ok);
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+            setTimeout(() => {
+                if (!this.connected) {
+                    this.socket?.destroy();
+                    resolve(false);
+                }
+            }, 5000);
+        });
+    }
+    disconnect() {
+        this.connected = false;
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        for (const [, req] of this.pending) {
+            clearTimeout(req.timer);
+            req.reject(new Error('Disconnected'));
+        }
+        this.pending.clear();
+        this.buffer = '';
+    }
+    async send(cmd) {
+        if (!this.connected || !this.socket) {
+            throw new Error('Not connected to KBotBridge Remote Script.\n' +
+                'Make sure KBotBridge is selected as a Control Surface in Ableton Preferences.');
+        }
+        const id = this.nextId++;
+        const fullCmd = { id, ...cmd };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Timeout: ${cmd.action}`));
+            }, AbletonBrowserBridge.TIMEOUT);
+            this.pending.set(id, { resolve, reject, timer });
+            this.socket.write(JSON.stringify(fullCmd) + '\n');
+        });
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    handleResponse(response) {
+        if (response.id && this.pending.has(response.id)) {
+            const req = this.pending.get(response.id);
+            this.pending.delete(response.id);
+            clearTimeout(req.timer);
+            req.resolve(response);
+        }
+    }
+    handleDisconnect() {
+        if (!this.connected)
+            return;
+        this.connected = false;
+        this.socket = null;
+        for (const [, req] of this.pending) {
+            clearTimeout(req.timer);
+            req.reject(new Error('Connection lost'));
+        }
+        this.pending.clear();
+    }
+    // ── Browser convenience methods ─────────────────────────────────
+    async ping() {
+        try {
+            const r = await this.send({ action: 'ping' });
+            return r.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Search Ableton's browser for items matching a query.
+     * @param query - Search string (case-insensitive)
+     * @param category - instruments/audio_effects/midi_effects/drums/samples/all
+     */
+    async browserSearch(query, category = 'all') {
+        const r = await this.send({ action: 'browser_search', query, category });
+        if (!r.ok)
+            throw new Error(r.error || 'Browser search failed');
+        return r.results || [];
+    }
+    /**
+     * Load a browser item by URI onto a track.
+     * Use the URI from a browserSearch() result.
+     */
+    async browserLoad(track, uri) {
+        return this.send({ action: 'browser_load', track, uri });
+    }
+    /**
+     * Search + load in one step. Finds first loadable match and loads it.
+     * @param track - 0-indexed track number
+     * @param name - Device name to search for (e.g., "Saturator", "EQ Eight")
+     * @param category - instruments/audio_effects/midi_effects/drums/samples/all
+     */
+    async browserLoadByName(track, name, category = 'all') {
+        return this.send({ action: 'browser_load_by_name', track, name, category });
+    }
+    /**
+     * List top-level browser categories with child counts.
+     */
+    async browserCategories() {
+        const r = await this.send({ action: 'browser_categories' });
+        if (!r.ok)
+            throw new Error(r.error || 'Failed to list categories');
+        return r.categories || [];
+    }
+    /**
+     * List all tracks with names and device counts.
+     */
+    async listTracks() {
+        return this.send({ action: 'list_tracks' });
+    }
+    /**
+     * List devices on a track with full parameter details.
+     */
+    async listDevices(track) {
+        return this.send({ action: 'list_devices', track });
+    }
+}
+// ── Convenience exports ─────────────────────────────────────────────
 /**
  * Get a connected M4L bridge instance.
  * Throws if the bridge is not available.
@@ -320,6 +517,41 @@ export async function ensureM4L() {
     }
     return m4l;
 }
+/**
+ * Get a connected Browser bridge instance (KBotBridge Remote Script on port 9998).
+ * Throws if not available.
+ */
+export async function ensureBrowserBridge() {
+    const bridge = AbletonBrowserBridge.getInstance();
+    if (bridge.isConnected)
+        return bridge;
+    const ok = await bridge.connect();
+    if (!ok) {
+        throw new Error('Cannot connect to KBotBridge Remote Script.\n\n' +
+            'Make sure:\n' +
+            '1. Ableton Live is running\n' +
+            '2. KBotBridge is selected as a Control Surface in Preferences > Link, Tempo & MIDI\n' +
+            '3. Ableton status bar shows "KBotBridge: Listening on port 9998"\n\n' +
+            'To install: kbot ableton install-bridge\n');
+    }
+    return bridge;
+}
+/**
+ * Connect to both M4L bridge (9999) and Browser bridge (9998).
+ * Returns whichever connections succeed. At least one must connect.
+ */
+export async function connectBrowser() {
+    const m4l = AbletonM4L.getInstance();
+    const browser = AbletonBrowserBridge.getInstance();
+    const [m4lOk, browserOk] = await Promise.all([
+        m4l.connect().catch(() => false),
+        browser.connect().catch(() => false),
+    ]);
+    return {
+        m4l: m4lOk ? m4l : null,
+        browser: browserOk ? browser : null,
+    };
+}
 /**
  * Format a friendly error message for M4L connection failures.
  */
@@ -335,4 +567,23 @@ export function formatM4LError() {
         'The M4L bridge gives kbot full control over Ableton — instruments, effects, clips, mixing, everything.',
     ].join('\n');
 }
+/**
+ * Format a friendly error message for Browser bridge connection failures.
+ */
+export function formatBrowserBridgeError() {
+    return [
+        '**KBotBridge Remote Script not connected**',
+        '',
+        'The Browser API (for loading native devices) requires the KBotBridge Remote Script:',
+        '1. Install: `kbot ableton install-bridge`',
+        '2. Open Ableton Live Preferences (Cmd+,)',
+        '3. Go to Link, Tempo & MIDI',
+        '4. Set a Control Surface to "KBotBridge"',
+        '5. Close Preferences',
+        '',
+        'This runs alongside the M4L bridge — they use different ports:',
+        '- KBotBridge: TCP 9998 (Browser API, device loading)',
+        '- M4L Bridge: TCP 9999 (LOM access, clips, mixing)',
+    ].join('\n');
+}
 //# sourceMappingURL=ableton-m4l.js.map

package/dist/integrations/install-remote-script.d.ts

@@ -0,0 +1,23 @@
+/**
+ * install-remote-script.ts — Install KBotBridge Remote Script into Ableton Live
+ *
+ * Copies the KBotBridge Python Remote Script to Ableton's User Library,
+ * enabling the Browser API bridge on TCP port 9998.
+ *
+ * The Remote Script exposes Ableton's browser.load_item() API, which is
+ * ONLY available from Python Remote Scripts (not from Max for Live).
+ * This lets kbot programmatically load any native device (Saturator,
+ * EQ Eight, Compressor, etc.) onto any track.
+ *
+ * Usage:
+ *   npx tsx packages/kbot/src/integrations/install-remote-script.ts
+ *   kbot ableton install-bridge
+ */
+export declare function installKBotBridge(): Promise<string>;
+export declare function isKBotBridgeInstalled(): boolean;
+export declare function uninstallKBotBridge(): string;
+/**
+ * Get the path to the KBotBridge log file inside Ableton's Remote Scripts.
+ */
+export declare function getKBotBridgeLogPath(): string | null;
+//# sourceMappingURL=install-remote-script.d.ts.map

package/dist/integrations/install-remote-script.js

@@ -0,0 +1,121 @@
+/**
+ * install-remote-script.ts — Install KBotBridge Remote Script into Ableton Live
+ *
+ * Copies the KBotBridge Python Remote Script to Ableton's User Library,
+ * enabling the Browser API bridge on TCP port 9998.
+ *
+ * The Remote Script exposes Ableton's browser.load_item() API, which is
+ * ONLY available from Python Remote Scripts (not from Max for Live).
+ * This lets kbot programmatically load any native device (Saturator,
+ * EQ Eight, Compressor, etc.) onto any track.
+ *
+ * Usage:
+ *   npx tsx packages/kbot/src/integrations/install-remote-script.ts
+ *   kbot ableton install-bridge
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const SCRIPT_NAME = 'KBotBridge';
+const SOURCE_FILES = [
+    '__init__.py',
+    'kbot_control_surface.py',
+    'tcp_server.py',
+];
+function getRemoteScriptsDir() {
+    const home = os.homedir();
+    return path.join(home, 'Music', 'Ableton', 'User Library', 'Remote Scripts');
+}
+function getDestDir() {
+    return path.join(getRemoteScriptsDir(), SCRIPT_NAME);
+}
+function getSourceDir() {
+    // Source files live alongside this installer in the integrations directory
+    return path.join(__dirname, SCRIPT_NAME);
+}
+export async function installKBotBridge() {
+    const lines = [];
+    const log = (msg) => { lines.push(msg); console.log(msg); };
+    log('Installing KBotBridge Remote Script...');
+    log('');
+    const sourceDir = getSourceDir();
+    const destDir = getDestDir();
+    const remoteScriptsDir = getRemoteScriptsDir();
+    // Verify source files exist
+    for (const file of SOURCE_FILES) {
+        const srcPath = path.join(sourceDir, file);
+        if (!fs.existsSync(srcPath)) {
+            log(`  ERROR: Source file missing: ${srcPath}`);
+            log('  Run from the kbot package directory.');
+            return lines.join('\n');
+        }
+    }
+    // Create Remote Scripts directory if it doesn't exist
+    if (!fs.existsSync(remoteScriptsDir)) {
+        fs.mkdirSync(remoteScriptsDir, { recursive: true });
+        log(`  Created: ${remoteScriptsDir}`);
+    }
+    // Remove old installation if present
+    if (fs.existsSync(destDir)) {
+        fs.rmSync(destDir, { recursive: true });
+        log('  Removed previous KBotBridge installation');
+    }
+    // Copy files
+    fs.mkdirSync(destDir, { recursive: true });
+    for (const file of SOURCE_FILES) {
+        const src = path.join(sourceDir, file);
+        const dst = path.join(destDir, file);
+        fs.copyFileSync(src, dst);
+        log(`  Copied: ${file}`);
+    }
+    // Create logs directory (the script will log here)
+    const logsDir = path.join(destDir, 'logs');
+    if (!fs.existsSync(logsDir)) {
+        fs.mkdirSync(logsDir, { recursive: true });
+    }
+    log('');
+    log(`KBotBridge installed to: ${destDir}`);
+    log('');
+    log('To activate:');
+    log('  1. Open Ableton Live (or restart if already running)');
+    log('  2. Preferences (Cmd+,) > Link, Tempo & MIDI');
+    log('  3. Set a Control Surface slot to "KBotBridge"');
+    log('  4. Input/Output can be left as "None"');
+    log('  5. Close Preferences');
+    log('');
+    log('Verify:');
+    log('  - Ableton status bar shows "KBotBridge: Listening on port 9998"');
+    log('  - Run: echo \'{"id":1,"action":"ping"}\\n\' | nc localhost 9998');
+    log('');
+    log('KBotBridge runs alongside AbletonOSC — they use different ports:');
+    log('  - KBotBridge: TCP 9998 (Browser API, device loading)');
+    log('  - M4L Bridge: TCP 9999 (LOM access, clips, mixing)');
+    log('  - AbletonOSC: UDP 11000/11001 (OSC, legacy)');
+    return lines.join('\n');
+}
+export function isKBotBridgeInstalled() {
+    const destDir = getDestDir();
+    return fs.existsSync(path.join(destDir, '__init__.py'))
+        && fs.existsSync(path.join(destDir, 'kbot_control_surface.py'))
+        && fs.existsSync(path.join(destDir, 'tcp_server.py'));
+}
+export function uninstallKBotBridge() {
+    const destDir = getDestDir();
+    if (fs.existsSync(destDir)) {
+        fs.rmSync(destDir, { recursive: true });
+        return `KBotBridge removed from ${destDir}`;
+    }
+    return 'KBotBridge was not installed.';
+}
+/**
+ * Get the path to the KBotBridge log file inside Ableton's Remote Scripts.
+ */
+export function getKBotBridgeLogPath() {
+    const logPath = path.join(getDestDir(), 'logs', 'kbot_bridge.log');
+    return fs.existsSync(logPath) ? logPath : null;
+}
+// ── CLI entrypoint ──────────────────────────────────────────────────
+if (require.main === module || process.argv[1]?.includes('install-remote-script')) {
+    installKBotBridge().catch(console.error);
+}
+//# sourceMappingURL=install-remote-script.js.map

package/dist/machine.d.ts

@@ -73,6 +73,7 @@ export interface MachineProfile {
     canRunLocalModels: boolean;
     gpuAcceleration: 'metal' | 'cuda' | 'vulkan' | 'cpu-only';
     recommendedModelSize: string;
+    mlxAvailable: boolean;
     probedAt: string;
 }
 export declare function probeMachine(): Promise<MachineProfile>;

package/dist/machine.js

@@ -314,6 +314,18 @@ function detectGpuAcceleration(gpus) {
         return 'vulkan';
     return 'cpu-only';
 }
+// ── MLX framework detection (Apple Silicon) ──
+function detectMLX() {
+    if (platform() !== 'darwin' || arch() !== 'arm64')
+        return false;
+    // Quick check: try importing mlx in Python
+    const result = exec('python3 -c "import mlx; print(mlx.__version__)" 2>/dev/null', 3000);
+    if (result && !result.includes('ModuleNotFoundError'))
+        return true;
+    // Fallback: check common pip install path
+    const globCheck = exec('ls /usr/local/lib/python3.*/site-packages/mlx/__init__.py 2>/dev/null || ls ~/Library/Python/3.*/lib/python/site-packages/mlx/__init__.py 2>/dev/null', 2000);
+    return !!globCheck;
+}
 // ── Model size recommendation ──
 function recommendModelSize(totalMemoryGB, gpuAccel) {
     // Conservative: leave room for OS + apps
@@ -374,6 +386,7 @@ export async function probeMachine() {
         osInfo = probeLinuxOs();
     }
     const gpuAccel = detectGpuAcceleration(gpus);
+    const mlxAvailable = detectMLX();
     const devTools = probeDevTools();
     // Uptime
     const uptimeSeconds = plat === 'darwin'
@@ -420,6 +433,7 @@ export async function probeMachine() {
         canRunLocalModels: gpuAccel !== 'cpu-only' || totalGB >= 8,
         gpuAcceleration: gpuAccel,
         recommendedModelSize: recommendModelSize(totalGB, gpuAccel),
+        mlxAvailable,
         probedAt: new Date().toISOString(),
     };
     cached = profile;
@@ -505,6 +519,8 @@ export function formatMachineProfile(p) {
     lines.push('');
     lines.push('  AI Capabilities');
     lines.push(`    Acceleration    ${p.gpuAcceleration}`);
+    if (p.mlxAvailable)
+        lines.push(`    MLX framework   available (Apple Silicon accelerated)`);
     lines.push(`    Local models    ${p.canRunLocalModels ? 'yes' : 'no'}`);
     lines.push(`    Recommended     up to ${p.recommendedModelSize} parameters`);
     lines.push('');
@@ -529,7 +545,7 @@ export function formatMachineForPrompt(p) {
     if (p.battery.present) {
         parts.push(`Battery: ${p.battery.percent}% ${p.battery.charging ? 'charging' : 'discharging'}`);
     }
-    parts.push(`GPU accel: ${p.gpuAcceleration} — local models up to ${p.recommendedModelSize}`);
+    parts.push(`GPU accel: ${p.gpuAcceleration}${p.mlxAvailable ? ' + MLX' : ''} — local models up to ${p.recommendedModelSize}`);
     const toolNames = p.devTools.map(t => `${t.name} ${t.version}`).join(', ');
     if (toolNames)
         parts.push(`Tools: ${toolNames}`);

package/dist/serve.js

@@ -235,8 +235,9 @@ export async function startServe(options) {
         printInfo(`  GET  /metrics               — Execution metrics`);
         printInfo(`  GET  /apps                  — List MCP App-capable tools`);
         printInfo(`  GET  /.well-known/agent.json — A2A Agent Card`);
-        printInfo(`  POST /a2a/tasks             — A2A submit task`);
-        printInfo(`  GET  /a2a/tasks/:id         — A2A task status`);
+        printInfo(`  POST /a2a                   — A2A JSON-RPC endpoint`);
+        printInfo(`  POST /a2a/tasks             — A2A submit task (REST)`);
+        printInfo(`  GET  /a2a/tasks/:id         — A2A task status (REST)`);
         if (options.token) {
             printInfo(`  Auth: Bearer token required`);
         }

package/dist/tools/a2a.d.ts

@@ -0,0 +1,2 @@
+export declare function registerA2ATools(): void;
+//# sourceMappingURL=a2a.d.ts.map