@kernel.chat/kbot 3.70.0 → 3.71.0

package/dist/integrations/ableton-m4l.d.ts

@@ -112,13 +112,107 @@ export declare class AbletonM4L {
     /** Generic LOM method call — call any method at any path */
     lomCall(path: string, method: string, args?: unknown[]): Promise<M4LResponse>;
 }
+export interface BrowserSearchResult {
+    name: string;
+    uri: string;
+    is_loadable: boolean;
+    is_device: boolean;
+}
+export interface BrowserCategory {
+    name: string;
+    display_name: string;
+    child_count: number;
+}
+/**
+ * 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 declare class AbletonBrowserBridge {
+    private static instance;
+    private socket;
+    private connected;
+    private pending;
+    private nextId;
+    private buffer;
+    static PORT: number;
+    static HOST: string;
+    static TIMEOUT: number;
+    private constructor();
+    static getInstance(): AbletonBrowserBridge;
+    /**
+     * Connect to the KBotBridge Remote Script on port 9998.
+     * Returns true if connected and the bridge responds to ping.
+     */
+    connect(): Promise<boolean>;
+    disconnect(): void;
+    send(cmd: Omit<M4LCommand, 'id'> & {
+        action: string;
+    }): Promise<M4LResponse>;
+    get isConnected(): boolean;
+    private handleResponse;
+    private handleDisconnect;
+    ping(): Promise<boolean>;
+    /**
+     * 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
+     */
+    browserSearch(query: string, category?: string): Promise<BrowserSearchResult[]>;
+    /**
+     * Load a browser item by URI onto a track.
+     * Use the URI from a browserSearch() result.
+     */
+    browserLoad(track: number, uri: string): Promise<M4LResponse>;
+    /**
+     * 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
+     */
+    browserLoadByName(track: number, name: string, category?: string): Promise<M4LResponse>;
+    /**
+     * List top-level browser categories with child counts.
+     */
+    browserCategories(): Promise<BrowserCategory[]>;
+    /**
+     * List all tracks with names and device counts.
+     */
+    listTracks(): Promise<M4LResponse>;
+    /**
+     * List devices on a track with full parameter details.
+     */
+    listDevices(track: number): Promise<M4LResponse>;
+}
 /**
  * Get a connected M4L bridge instance.
  * Throws if the bridge is not available.
  */
 export declare function ensureM4L(): Promise<AbletonM4L>;
+/**
+ * Get a connected Browser bridge instance (KBotBridge Remote Script on port 9998).
+ * Throws if not available.
+ */
+export declare function ensureBrowserBridge(): Promise<AbletonBrowserBridge>;
+/**
+ * Connect to both M4L bridge (9999) and Browser bridge (9998).
+ * Returns whichever connections succeed. At least one must connect.
+ */
+export declare function connectBrowser(): Promise<{
+    m4l: AbletonM4L | null;
+    browser: AbletonBrowserBridge | null;
+}>;
 /**
  * Format a friendly error message for M4L connection failures.
  */
 export declare function formatM4LError(): string;
+/**
+ * Format a friendly error message for Browser bridge connection failures.
+ */
+export declare function formatBrowserBridgeError(): string;
 //# sourceMappingURL=ableton-m4l.d.ts.map

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/tools/ableton-bridge-tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ableton-bridge-tools.ts — Ableton Browser & Device Loading Tools
+ *
+ * Uses AbletonBridge (port 9001) for full Ableton Browser API access.
+ * Falls back to KBotBridge (port 9998) if AbletonBridge is unavailable.
+ *
+ * Tools:
+ *   ableton_load_effect  — Load any Ableton native effect by name onto a track
+ *   ableton_browse       — Search Ableton's browser (instruments, effects, presets, samples)
+ *   ableton_load_preset  — Load a preset onto a device
+ *   ableton_effect_chain — Apply a full chain of effects to a track in sequence
+ */
+export declare function registerAbletonBridgeTools(): void;
+//# sourceMappingURL=ableton-bridge-tools.d.ts.map