@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/feishu/serve.js

@@ -0,0 +1,302 @@
+/**
+ * `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(),
+        disabledSkills: userConfig.getDisabledSkills(),
+        onDisabledSkillsChange: (disabledSkills) => userConfig.setDisabledSkills(disabledSkills),
+    });
+    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) => {
+        const profile = providerRegistry.getConfigured().find((provider) => provider.id === providerId);
+        return createProviderInstance({
+            providerId,
+            apiKey,
+            baseURL,
+            promptCacheKey,
+            protocol: profile?.protocol,
+            headers: profile?.headers,
+            openAICodexAuth: providerRegistry.createOpenAICodexAuthAdapter(providerId),
+            grokAuth: providerRegistry.createGrokAuthAdapter(providerId),
+        });
+    };
+    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;
+}

package/dist/goal/command.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure parser for the `/goal` slash command.
+ *
+ * Forms:
+ *   /goal                      -> show summary
+ *   /goal <objective> [--budget N]  -> set a new goal
+ *   /goal status | clear | pause | resume
+ *   /goal edit <new objective>
+ *
+ * --budget accepts plain integers and k/m suffixes: 200000, 200k, 1.5m.
+ */
+export type GoalCommandKind = "show" | "set" | "clear" | "pause" | "resume" | "edit";
+export interface GoalCommand {
+    kind: GoalCommandKind;
+    objective?: string;
+    tokenBudget?: number;
+    error?: string;
+}
+export declare function parseGoalCommand(input: string): GoalCommand;
+export declare function parseBudgetValue(raw: string): number | undefined;

package/dist/goal/command.js

@@ -0,0 +1,76 @@
+/**
+ * Pure parser for the `/goal` slash command.
+ *
+ * Forms:
+ *   /goal                      -> show summary
+ *   /goal <objective> [--budget N]  -> set a new goal
+ *   /goal status | clear | pause | resume
+ *   /goal edit <new objective>
+ *
+ * --budget accepts plain integers and k/m suffixes: 200000, 200k, 1.5m.
+ */
+const SUBCOMMANDS = new Set(["status", "clear", "pause", "resume", "edit"]);
+export function parseGoalCommand(input) {
+    const body = input.trim().replace(/^\/goal\b/, "").trim();
+    if (!body)
+        return { kind: "show" };
+    const firstToken = body.split(/\s+/, 1)[0].toLowerCase();
+    const rest = body.slice(firstToken.length).trim();
+    if (SUBCOMMANDS.has(firstToken)) {
+        if (firstToken === "status") {
+            if (rest)
+                return { kind: "show", error: "/goal status takes no arguments" };
+            return { kind: "show" };
+        }
+        if (firstToken === "edit") {
+            if (!rest)
+                return { kind: "edit", error: "Usage: /goal edit <new objective>" };
+            const { text, tokenBudget, error } = extractBudget(rest);
+            if (error)
+                return { kind: "edit", error };
+            const objective = text.trim();
+            if (!objective)
+                return { kind: "edit", error: "Usage: /goal edit <new objective>" };
+            return { kind: "edit", objective, tokenBudget };
+        }
+        // clear / pause / resume take no arguments.
+        if (rest)
+            return { kind: firstToken, error: `/goal ${firstToken} takes no arguments` };
+        return { kind: firstToken };
+    }
+    // Anything else is a new objective.
+    const { text, tokenBudget, error } = extractBudget(body);
+    if (error)
+        return { kind: "set", error };
+    const objective = text.trim();
+    if (!objective)
+        return { kind: "set", error: "Usage: /goal <objective> [--budget N]" };
+    return { kind: "set", objective, tokenBudget };
+}
+function extractBudget(s) {
+    const match = s.match(/--budget(?:=|\s+)(\S+)/);
+    if (!match || match.index === undefined)
+        return { text: s };
+    const value = parseBudgetValue(match[1]);
+    if (value === undefined || value <= 0) {
+        return { text: s, error: `Invalid --budget value: "${match[1]}" (use e.g. 200000, 200k, 1.5m)` };
+    }
+    const text = (s.slice(0, match.index) + s.slice(match.index + match[0].length))
+        .replace(/\s+/g, " ")
+        .trim();
+    return { text, tokenBudget: value };
+}
+export function parseBudgetValue(raw) {
+    const match = raw.trim().match(/^(\d+(?:\.\d+)?)([kmKM]?)$/);
+    if (!match)
+        return undefined;
+    let value = parseFloat(match[1]);
+    if (!Number.isFinite(value))
+        return undefined;
+    const suffix = match[2].toLowerCase();
+    if (suffix === "k")
+        value *= 1_000;
+    else if (suffix === "m")
+        value *= 1_000_000;
+    return Math.round(value);
+}

package/dist/goal/engine.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure decision logic for the goal auto-continuation loop.
+ *
+ * Kept out of the TUI so the stop conditions can be unit-tested directly. The
+ * TUI calls shouldContinueGoal() after each goal turn finishes and either fires
+ * another turn or stops with the returned reason.
+ *
+ * The agent decides when the work is done — there is intentionally NO turn-count
+ * cap (unlike a fixed iteration limit). The loop only stops when:
+ *   - the model marks the goal complete/blocked (via update_goal),
+ *   - the user pauses/clears it,
+ *   - the run is interrupted or the provider errors (out of quota, network, …),
+ *   - or a user-set token budget is exhausted.
+ * Otherwise it keeps going.
+ */
+import type { GoalState } from "./store.js";
+export type GoalStopReason = "complete" | "blocked" | "paused" | "budget" | "error" | "cancelled" | "user_input" | "no_goal";
+export interface ContinueDecisionInput {
+    goal: GoalState | null;
+    /** The last run was interrupted/cancelled by the user. */
+    cancelled?: boolean;
+    /** The last run failed with a provider/run error (quota, network, API). */
+    errored?: boolean;
+    /** Number of user inputs queued to run next (a real message preempts the goal). */
+    queuedInputs?: number;
+}
+export interface ContinueDecision {
+    continue: boolean;
+    reason?: GoalStopReason;
+}
+export declare function shouldContinueGoal(input: ContinueDecisionInput): ContinueDecision;
+/** Human-readable one-liner explaining why auto-continuation stopped. */
+export declare function stopReasonNotice(reason: GoalStopReason | undefined): string;