@bubblebrain-ai/bubble 0.0.10 → 0.0.12

package/dist/feishu/serve.js

@@ -0,0 +1,288 @@
+/**
+ * `bubble serve --feishu` entry. Wires every layer of the host together.
+ */
+import chalk from "chalk";
+import { homedir } from "node:os";
+import { configExists, loadConfig, resolveAppSecret } from "./config.js";
+import { runWizard } from "./wizard.js";
+import { ScopeRegistry } from "./scope/scope-registry.js";
+import { SessionStore } from "./scope/session-store.js";
+import { SessionBinder } from "./scope/session-binder.js";
+import { PendingQueue, combineQueuedMessages } from "./runtime/pending-queue.js";
+import { ActiveRuns } from "./runtime/active-runs.js";
+import { ProcessPool } from "./runtime/process-pool.js";
+import { createBubbleChannel } from "./channel/channel.js";
+import { FeishuApprovalUI } from "./agent-host/approval-ui.js";
+import { RunDriver } from "./agent-host/run-driver.js";
+import { EventRouter } from "./router/event-router.js";
+import { FeishuLogger } from "./logger.js";
+import { ProcessRegistry } from "./process-registry.js";
+import { parseScopeKey } from "./types.js";
+// Re-use existing process-level building blocks.
+import { UserConfig } from "../config.js";
+import { ProviderRegistry } from "../provider-registry.js";
+import { createProviderInstance } from "../provider.js";
+import { SettingsManager } from "../permissions/settings.js";
+import { SkillRegistry } from "../skills/registry.js";
+import { loadMcpConfig } from "../mcp/config.js";
+import { McpManager } from "../mcp/manager.js";
+import { BashAllowlist } from "../approval/session-cache.js";
+export async function serveFeishu(opts = {}) {
+    // 1. Setup or load config
+    if (opts.setup || !configExists()) {
+        await runWizard();
+        if (opts.setup) {
+            console.log(chalk.dim("Re-run `bubble serve --feishu` (without --setup) to start serving."));
+            return;
+        }
+    }
+    const config = loadConfig();
+    const appSecret = resolveAppSecret(config);
+    // 2. Process registry — detect duplicates
+    const procRegistry = new ProcessRegistry();
+    procRegistry.gc();
+    const conflicts = procRegistry.findConflicts(config.app.appId);
+    if (conflicts.length > 0) {
+        if (opts.killOld || process.env.BUBBLE_KILL_OLD === "1") {
+            const killed = procRegistry.killConflicts(config.app.appId);
+            console.log(chalk.dim(`Killed ${killed} stale instance(s) for appId ${config.app.appId}.`));
+        }
+        else if (process.stdin.isTTY) {
+            console.log(chalk.yellow(`\n⚠ Another bubble serve --feishu is running for app ${config.app.appId}:`));
+            for (const c of conflicts) {
+                console.log(`  pid ${c.entry.pid} (started ${new Date(c.entry.startedAt).toLocaleString()})`);
+            }
+            console.log("\n  c) Continue anyway (both will fight for events — not recommended)");
+            console.log("  k) Kill the old one and continue");
+            console.log("  a) Abort\n");
+            const choice = await prompt("Choice [c/k/a]: ");
+            if (/^k/i.test(choice)) {
+                procRegistry.killConflicts(config.app.appId);
+            }
+            else if (!/^c/i.test(choice)) {
+                console.log("Aborted.");
+                process.exit(2);
+            }
+        }
+        else {
+            console.error(chalk.red(`Another instance is running for appId ${config.app.appId}. Set BUBBLE_KILL_OLD=1 to kill it, or run without -y to interactively resolve.`));
+            process.exit(2);
+        }
+    }
+    procRegistry.register({
+        pid: process.pid,
+        appId: config.app.appId,
+        startedAt: Date.now(),
+        cwd: process.cwd(),
+    });
+    // 3. Process-level dependencies (shared across scopes)
+    const userConfig = new UserConfig();
+    const providerRegistry = new ProviderRegistry(userConfig);
+    // Use the user's home as the "root" for settings/skills/MCP discovery.
+    // Per-scope cwd overrides happen at the run-driver level (future work).
+    const rootCwd = homedir();
+    const settingsManager = new SettingsManager(rootCwd);
+    const skillRegistry = new SkillRegistry({
+        cwd: rootCwd,
+        skillPaths: userConfig.getSkillPaths(),
+    });
+    const mcpLoaded = loadMcpConfig({ cwd: rootCwd });
+    const mcpManager = new McpManager({ servers: mcpLoaded.servers });
+    if (mcpLoaded.servers.length > 0) {
+        await mcpManager.start();
+    }
+    const createProvider = (providerId, apiKey, baseURL, promptCacheKey) => createProviderInstance({ providerId, apiKey, baseURL, promptCacheKey });
+    const createProviderForRoute = async (route, promptCacheKey) => {
+        const target = providerRegistry.getConfigured().find((p) => p.id === route.providerId);
+        if (!target?.apiKey) {
+            throw new Error(`Subagent route requires provider "${route.providerId}", not configured.`);
+        }
+        return createProvider(route.providerId, target.apiKey, target.baseURL, promptCacheKey);
+    };
+    const deps = {
+        settingsManager,
+        providerRegistry,
+        userConfig,
+        skillRegistry,
+        mcpManager,
+        createProvider,
+        createProviderForRoute,
+        ownerOpenId: config.app.ownerOpenId,
+    };
+    // 4. Persistence stores
+    const scopeRegistry = ScopeRegistry.load();
+    const sessionStore = SessionStore.load();
+    const sessionBinder = new SessionBinder(sessionStore);
+    // 5. Channel
+    const channel = createBubbleChannel({
+        appId: config.app.appId,
+        appSecret,
+        outputThrottleMs: config.preferences.outputThrottleMs,
+        requireMentionInGroup: config.preferences.requireMentionInGroup,
+    });
+    // 6. Logger
+    const logger = new FeishuLogger();
+    logger.pruneOldLogs(7);
+    // 7. Approval UI (shared across all scopes; clicker-restricted enforces per-scope safety)
+    const approvalUI = new FeishuApprovalUI({
+        sendCard: async (chatId, card) => {
+            const res = await channel.send(chatId, { card }, undefined);
+            return { messageId: res.messageId };
+        },
+        updateCard: (messageId, card) => channel.updateCard(messageId, card),
+        bashAllowlist: new BashAllowlist(),
+        timeoutMs: 60_000,
+    });
+    // 8. Runtime control
+    const activeRuns = new ActiveRuns();
+    const processPool = new ProcessPool({ concurrency: config.globalLimits.maxConcurrentRuns });
+    // 9. Run driver
+    const driver = new RunDriver({
+        channel,
+        deps,
+        binder: sessionBinder,
+        approvalUI,
+        outputThrottleMs: config.preferences.outputThrottleMs,
+        idleTimeoutMinutes: config.preferences.idleTimeoutMinutes,
+        maxBytesPerElement: config.preferences.maxBytesPerElement,
+        maxBytesPerCard: config.preferences.maxBytesPerCard,
+    });
+    // 10. PendingQueue with flush → run-driver
+    const pendingQueue = new PendingQueue({
+        debounceMs: 600,
+        onFlush: async (scopeKey, batch) => {
+            const parsed = parseScopeKey(scopeKey);
+            if (!parsed)
+                return;
+            const scope = scopeRegistry.get(parsed.chatId);
+            if (!scope)
+                return;
+            // Block further flushes for this scope while the run is in flight.
+            pendingQueue.block(scopeKey);
+            const { signal, complete } = await activeRuns.startOrReplace(scopeKey);
+            try {
+                await processPool.run(async () => driver.runOnce({
+                    scopeKey,
+                    scope,
+                    chatId: parsed.chatId,
+                    userId: parsed.userId,
+                    prompt: combineQueuedMessages(batch),
+                    replyToMessageId: batch[0]?.messageId,
+                    abortSignal: signal,
+                }));
+            }
+            catch (err) {
+                logger.error("run_driver_error", {
+                    phase: "runtime",
+                    scope: scopeKey,
+                    error: serializeError(err),
+                });
+            }
+            finally {
+                complete();
+                pendingQueue.unblock(scopeKey);
+            }
+        },
+    });
+    // 11. Event router
+    const router = new EventRouter({
+        channel,
+        scopeRegistry,
+        sessionStore,
+        activeRuns,
+        pendingQueue,
+        approvalUI,
+        logger,
+        requireMentionInGroup: config.preferences.requireMentionInGroup,
+        commandContext: {
+            channel,
+            scopeRegistry,
+            sessionStore,
+            sessionBinder,
+            activeRuns,
+        },
+    });
+    // 12. Channel events for status/log
+    channel.onError((err) => {
+        logger.error("channel_error", { phase: "channel", error: serializeError(err) });
+        console.error(chalk.red(`[channel] ${err.message}`));
+    });
+    channel.onReconnecting(() => {
+        logger.warn("channel_reconnecting", { phase: "channel" });
+        console.log(chalk.yellow("[channel] reconnecting…"));
+    });
+    channel.onReconnected(() => {
+        logger.info("channel_reconnected", { phase: "channel" });
+        console.log(chalk.green("[channel] reconnected"));
+    });
+    router.start();
+    // 13. Shutdown
+    let shuttingDown = false;
+    let resolveServeDone;
+    const serveDone = new Promise((resolve) => {
+        resolveServeDone = resolve;
+    });
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(chalk.dim(`\nGot ${signal}, shutting down…`));
+        router.stop();
+        pendingQueue.shutdown();
+        const aborted = activeRuns.abortAll();
+        if (aborted > 0)
+            console.log(chalk.dim(`Aborted ${aborted} active run(s).`));
+        approvalUI.cancelAll("Shutdown");
+        await activeRuns.waitAll(8_000);
+        try {
+            await channel.disconnect();
+        }
+        catch { /* */ }
+        try {
+            await mcpManager.shutdown();
+        }
+        catch { /* */ }
+        procRegistry.deregister(process.pid);
+        resolveServeDone?.();
+    };
+    process.once("SIGINT", () => void shutdown("SIGINT"));
+    process.once("SIGTERM", () => void shutdown("SIGTERM"));
+    // 14. Connect
+    console.log(chalk.dim(`\nConnecting to Feishu (app ${config.app.appId})…`));
+    try {
+        await channel.connect();
+    }
+    catch (err) {
+        console.error(chalk.red(`Failed to connect: ${err.message}`));
+        procRegistry.deregister(process.pid);
+        process.exit(1);
+    }
+    const botId = channel.botOpenId();
+    const scopesCount = scopeRegistry.list().length;
+    console.log(chalk.green(`✅ Listening on Feishu.`));
+    console.log(chalk.dim(`   bot open_id: ${botId ?? "(unknown)"}`));
+    console.log(chalk.dim(`   ${scopesCount} scope${scopesCount === 1 ? "" : "s"} configured`));
+    console.log(chalk.dim("\nSend a message to your bot to start. /help in chat for commands."));
+    if (opts.dryRun) {
+        console.log(chalk.dim("\n--dry-run set; exiting after successful connect."));
+        await shutdown("dry-run");
+        return;
+    }
+    // Block here until SIGINT/SIGTERM triggers shutdown. Without this await
+    // the function would return, main() would resolve, and exitAfterFlush()
+    // in main.ts would call process.exit(0) — killing the freshly-connected
+    // service. The LarkChannel WebSocket alone doesn't always keep Node's
+    // event loop alive (e.g., under detached spawn where stdin is /dev/null).
+    await serveDone;
+}
+function prompt(question) {
+    return new Promise((resolve) => {
+        process.stdout.write(question);
+        process.stdin.once("data", (data) => resolve(String(data).trim()));
+    });
+}
+function serializeError(err) {
+    if (err instanceof Error)
+        return { message: err.message, name: err.name, stack: err.stack };
+    return { message: String(err) };
+}

package/dist/feishu/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Public types for the Feishu host.
+ */
+import type { PermissionMode } from "../types.js";
+export interface FeishuConfig {
+    version: 1;
+    app: {
+        appId: string;
+        secretRef: SecretRef;
+        ownerOpenId: string;
+        encryptCheck: string;
+    };
+    preferences: {
+        outputThrottleMs: number;
+        idleTimeoutMinutes: number;
+        renderMode: "card" | "markdown" | "text";
+        requireMentionInGroup: boolean;
+        maxBytesPerElement: number;
+        maxBytesPerCard: number;
+    };
+    globalLimits: {
+        maxConcurrentRuns: number;
+    };
+}
+export type SecretRef = {
+    source: "keystore";
+    name: string;
+} | {
+    source: "env";
+    varName: string;
+};
+export interface ScopesFile {
+    version: 1;
+    scopes: Record<string, ScopeConfig>;
+}
+export interface ScopeConfig {
+    /** Initial cwd used the first time this scope sees traffic. */
+    cwd: string;
+    displayName: string;
+    allowedUsers: string[];
+    admins: string[];
+    defaultPermissionMode: PermissionMode;
+    model: string | null;
+    createdAt: number;
+    lastActiveAt: number;
+}
+export interface SessionsFile {
+    version: 1;
+    sessions: Record<string, SessionEntry>;
+}
+/** Keyed by `<chatId>:<userId>` in sessions.json. */
+export interface SessionEntry {
+    sessionFile: string;
+    cwd: string;
+    permissionMode: PermissionMode;
+    lastActiveAt: number;
+}
+export interface ProcessRegistryFile {
+    version: 1;
+    processes: ProcessRegistryEntry[];
+}
+export interface ProcessRegistryEntry {
+    pid: number;
+    appId: string;
+    startedAt: number;
+    cwd: string;
+}
+export declare const DEFAULT_PREFERENCES: FeishuConfig["preferences"];
+export declare const DEFAULT_GLOBAL_LIMITS: FeishuConfig["globalLimits"];
+export type ScopeKey = string;
+export declare function makeScopeKey(chatId: string, userId: string): ScopeKey;
+export declare function parseScopeKey(key: ScopeKey): {
+    chatId: string;
+    userId: string;
+} | undefined;

package/dist/feishu/types.js

@@ -0,0 +1,23 @@
+/**
+ * Public types for the Feishu host.
+ */
+export const DEFAULT_PREFERENCES = {
+    outputThrottleMs: 400,
+    idleTimeoutMinutes: 15,
+    renderMode: "card",
+    requireMentionInGroup: true,
+    maxBytesPerElement: 28000,
+    maxBytesPerCard: 140000,
+};
+export const DEFAULT_GLOBAL_LIMITS = {
+    maxConcurrentRuns: 5,
+};
+export function makeScopeKey(chatId, userId) {
+    return `${chatId}:${userId}`;
+}
+export function parseScopeKey(key) {
+    const idx = key.indexOf(":");
+    if (idx <= 0)
+        return undefined;
+    return { chatId: key.slice(0, idx), userId: key.slice(idx + 1) };
+}

package/dist/feishu/wizard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * First-time setup wizard.
+ *
+ *  Flow:
+ *    1. Call `registerApp` from the SDK — it returns a QR code URL that
+ *       points at Feishu's app-registration page; user scans on phone to
+ *       create an app and authorize us.
+ *    2. We receive `{ client_id, client_secret, user_info.open_id }`.
+ *    3. Encrypt the secret to `secrets.enc`, write `config.json`, prompt
+ *       the user (in terminal) for the first scope (chat_id + cwd).
+ *    4. Persist the scope to `scopes.json`.
+ *
+ *  The terminal prompts use a tiny line-mode reader (readline). We don't
+ *  pull in @clack to keep dependencies flat.
+ */
+import type { FeishuConfig, ScopeConfig } from "./types.js";
+export interface WizardResult {
+    config: FeishuConfig;
+    firstScope?: {
+        chatId: string;
+        scope: ScopeConfig;
+    };
+}
+export declare function runWizard(): Promise<WizardResult>;

package/dist/feishu/wizard.js

@@ -0,0 +1,121 @@
+/**
+ * First-time setup wizard.
+ *
+ *  Flow:
+ *    1. Call `registerApp` from the SDK — it returns a QR code URL that
+ *       points at Feishu's app-registration page; user scans on phone to
+ *       create an app and authorize us.
+ *    2. We receive `{ client_id, client_secret, user_info.open_id }`.
+ *    3. Encrypt the secret to `secrets.enc`, write `config.json`, prompt
+ *       the user (in terminal) for the first scope (chat_id + cwd).
+ *    4. Persist the scope to `scopes.json`.
+ *
+ *  The terminal prompts use a tiny line-mode reader (readline). We don't
+ *  pull in @clack to keep dependencies flat.
+ */
+import { registerApp } from "@larksuiteoapi/node-sdk";
+import qrTerminal from "qrcode-terminal";
+import chalk from "chalk";
+import { createInterface } from "node:readline";
+import { existsSync, statSync } from "node:fs";
+import { resolve as resolvePath, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { bootstrapConfig } from "./config.js";
+import { ScopeRegistry } from "./scope/scope-registry.js";
+export async function runWizard() {
+    console.log(chalk.bold("\n🫧 Bubble Feishu setup\n"));
+    console.log("This will register a Feishu personal-agent app, encrypt the secret to your");
+    console.log("keystore, and let you bind your first chat to a local directory.\n");
+    const registered = await runQrFlow();
+    console.log(chalk.green(`✅ Registered. owner open_id: ${registered.userInfo?.open_id ?? "(unknown)"}\n`));
+    const ownerOpenId = registered.userInfo?.open_id ?? "";
+    if (!ownerOpenId) {
+        throw new Error("registerApp did not return user_info.open_id — cannot continue.");
+    }
+    const config = bootstrapConfig({
+        appId: registered.clientId,
+        appSecret: registered.clientSecret,
+        ownerOpenId,
+    });
+    console.log(chalk.dim(`Wrote config + encrypted secret to ~/.bubble/feishu/\n`));
+    // Optional first-scope binding.
+    console.log("Want to bind a chat to a local directory now? You can also do this later by");
+    console.log("editing ~/.bubble/feishu/scopes.json directly.\n");
+    const wantBind = await ask("Bind a chat now? [y/N]: ");
+    if (!/^y/i.test(wantBind.trim())) {
+        return { config };
+    }
+    const chatId = (await ask("Chat ID (oc_...): ")).trim();
+    if (!chatId.startsWith("oc_")) {
+        console.log(chalk.yellow("Chat IDs typically start with `oc_`. Continuing anyway."));
+    }
+    const cwdInput = (await ask(`Local cwd to bind (e.g. ${homedir()}/projects/my-app): `)).trim();
+    const expandedCwd = expandUser(cwdInput);
+    if (!isAbsolute(expandedCwd) || !existsSync(expandedCwd) || !statSync(expandedCwd).isDirectory()) {
+        throw new Error(`Invalid cwd: ${expandedCwd} (must be an existing absolute directory)`);
+    }
+    const displayName = (await ask("Display name (short label for the card header): ")).trim() || basenameSafe(expandedCwd);
+    const scope = {
+        cwd: expandedCwd,
+        displayName,
+        allowedUsers: [ownerOpenId],
+        admins: [ownerOpenId],
+        defaultPermissionMode: "default",
+        model: null,
+        createdAt: Date.now(),
+        lastActiveAt: Date.now(),
+    };
+    const registry = ScopeRegistry.load();
+    registry.upsert(chatId, scope);
+    console.log(chalk.green(`\n✅ Bound chat ${chatId} → ${expandedCwd}\n`));
+    return { config, firstScope: { chatId, scope } };
+}
+async function runQrFlow() {
+    console.log("Opening QR code below. Scan with your Feishu mobile app and authorize.\n");
+    return new Promise((resolve, reject) => {
+        let printed = false;
+        void registerApp({
+            onQRCodeReady: (info) => {
+                if (!printed) {
+                    qrTerminal.generate(info.url, { small: true }, (code) => {
+                        process.stdout.write(code + "\n");
+                        console.log(chalk.dim(`(QR expires in ${info.expireIn}s)`));
+                    });
+                    printed = true;
+                }
+            },
+            onStatusChange: (info) => {
+                if (info.status === "slow_down")
+                    console.log(chalk.dim("(polling slowed — still waiting…)"));
+                if (info.status === "domain_switched")
+                    console.log(chalk.dim("(domain switched)"));
+            },
+        })
+            .then((res) => {
+            resolve({
+                clientId: res.client_id,
+                clientSecret: res.client_secret,
+                userInfo: res.user_info,
+            });
+        })
+            .catch(reject);
+    });
+}
+function ask(prompt) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+function expandUser(p) {
+    if (p === "~" || p.startsWith("~/"))
+        return homedir() + p.slice(1);
+    return resolvePath(p);
+}
+function basenameSafe(p) {
+    const parts = p.split(/[\\/]/);
+    return parts[parts.length - 1] || p;
+}