@kernel.chat/kbot 3.70.0 → 3.72.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 9997).
+ *
+ * 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 9997.
+     * 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 9997).
+ * Throws if not available.
+ */
+export declare function ensureBrowserBridge(): Promise<AbletonBrowserBridge>;
+/**
+ * Connect to both M4L bridge (9999) and Browser bridge (9997).
+ * 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 9997).
+ *
+ * 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 = 9997;
+    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 9997.
+     * 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 9997).
+ * 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 9997"\n\n' +
+            'To install: kbot ableton install-bridge\n');
+    }
+    return bridge;
+}
+/**
+ * Connect to both M4L bridge (9999) and Browser bridge (9997).
+ * 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 9997 (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 9997.
+ *
+ * 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 9997.
+ *
+ * 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 9997"');
+    log('  - Run: echo \'{"id":1,"action":"ping"}\\n\' | nc localhost 9997');
+    log('');
+    log('KBotBridge runs alongside AbletonOSC — they use different ports:');
+    log('  - KBotBridge: TCP 9997 (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/integrations/mobile-mcp-client.d.ts

@@ -0,0 +1,111 @@
+/**
+ * mobile-mcp-client.ts — kbot <-> mobile-mcp integration
+ *
+ * Singleton client that manages the mobile-mcp server process lifecycle.
+ * Communicates via MCP protocol over stdio transport.
+ * Auto-installs @mobilenext/mobile-mcp via npm if not present.
+ *
+ * mobile-mcp provides native accessibility-tree-based automation for
+ * iOS and Android devices connected via USB or WiFi.
+ *
+ * @see https://github.com/mobile-next/mobile-mcp
+ */
+export interface MobileDevice {
+    id: string;
+    name: string;
+    platform: 'ios' | 'android';
+    type: 'real' | 'simulator' | 'emulator';
+    version: string;
+    state: 'online' | 'offline';
+}
+export interface MobileElement {
+    type: string;
+    text?: string;
+    label?: string;
+    name?: string;
+    value?: string;
+    identifier?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MobileScreenSize {
+    width: number;
+    height: number;
+}
+export declare class MobileMCPClient {
+    private static instance;
+    private process;
+    private messageId;
+    private pending;
+    private buffer;
+    private initialized;
+    private activeDeviceId;
+    static getInstance(): MobileMCPClient;
+    /** Whether the MCP server process is running and initialized */
+    get isConnected(): boolean;
+    /** The device ID currently being controlled */
+    get currentDeviceId(): string | null;
+    /** Start the mobile-mcp server process and perform MCP handshake */
+    start(): Promise<void>;
+    /** Stop the mobile-mcp server process */
+    stop(): void;
+    private parseMessages;
+    private sendRequest;
+    private sendNotification;
+    /** Call a tool on the mobile-mcp server */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Extract text content from an MCP tool result */
+    extractText(result: unknown): string;
+    /** Extract image content (base64) from an MCP tool result */
+    extractImage(result: unknown): {
+        data: string;
+        mimeType: string;
+    } | null;
+    /** List all available devices */
+    listDevices(): Promise<MobileDevice[]>;
+    /** Set the active device for subsequent operations */
+    setActiveDevice(deviceId: string): void;
+    /** Get the active device ID, throwing if none set */
+    private requireDevice;
+    /** List apps on the active device */
+    listApps(deviceId?: string): Promise<string>;
+    /** Launch an app by bundle ID */
+    launchApp(packageName: string, deviceId?: string): Promise<string>;
+    /** Take a screenshot, returns base64 image data */
+    takeScreenshot(deviceId?: string): Promise<{
+        data: string;
+        mimeType: string;
+    } | string>;
+    /** Save screenshot to a file */
+    saveScreenshot(saveTo: string, deviceId?: string): Promise<string>;
+    /** List UI elements on screen via accessibility tree */
+    listElements(deviceId?: string): Promise<string>;
+    /** Tap at coordinates */
+    tap(x: number, y: number, deviceId?: string): Promise<string>;
+    /** Swipe on screen */
+    swipe(direction: 'up' | 'down' | 'left' | 'right', opts?: {
+        x?: number;
+        y?: number;
+        distance?: number;
+        deviceId?: string;
+    }): Promise<string>;
+    /** Type text */
+    typeText(text: string, submit?: boolean, deviceId?: string): Promise<string>;
+    /** Press a device button */
+    pressButton(button: 'HOME' | 'BACK' | 'VOLUME_UP' | 'VOLUME_DOWN' | 'ENTER', deviceId?: string): Promise<string>;
+    /** Get screen size */
+    getScreenSize(deviceId?: string): Promise<string>;
+    /** Open a URL in the device browser */
+    openUrl(url: string, deviceId?: string): Promise<string>;
+    /** Get device orientation */
+    getOrientation(deviceId?: string): Promise<string>;
+    /** Terminate an app */
+    terminateApp(packageName: string, deviceId?: string): Promise<string>;
+    /** Double tap at coordinates */
+    doubleTap(x: number, y: number, deviceId?: string): Promise<string>;
+    /** Long press at coordinates */
+    longPress(x: number, y: number, duration?: number, deviceId?: string): Promise<string>;
+}
+//# sourceMappingURL=mobile-mcp-client.d.ts.map