@bubblebrain-ai/bubble 0.0.37 → 0.0.38

package/dist/tasks/wake.js

@@ -0,0 +1,125 @@
+/**
+ * Auto-resume wake decision + coalescing (background-tasks design §2.3b).
+ *
+ * Kept pure and out of the TUI so the guard rails are unit-testable:
+ * - debounce-before-fire coalescing (the idle input queue drains in ~0ms, so
+ *   merging can only happen BEFORE the wake is submitted);
+ * - user preemption (queued user input or a running turn suppresses the wake
+ *   — the state-change reminder covers the completion on the next turn);
+ * - config kill switch (tasks.auto_resume = false);
+ * - killed tasks never wake (killing is an explicit decision, not news).
+ */
+export function shouldFireTaskWake(input) {
+    if (!input.autoResume)
+        return false;
+    if (input.exiting)
+        return false;
+    if (input.turnRunning)
+        return false;
+    if (input.queuedInputs > 0)
+        return false;
+    return true;
+}
+export function taskEligibleForWake(task) {
+    return task.status === "completed" || task.status === "failed";
+}
+export function formatTaskWakeSummary(tasks, outputTail) {
+    const lines = [
+        tasks.length === 1
+            ? "A background task you started has finished."
+            : `${tasks.length} background tasks you started have finished.`,
+    ];
+    for (const task of tasks) {
+        const elapsed = Math.round(((task.endedAt ?? Date.now()) - task.startedAt) / 1000);
+        lines.push(`- ${task.id}${task.description ? ` (${task.description})` : ""}: ${task.status}${task.exitCode != null ? ` exit ${task.exitCode}` : ""} in ${elapsed}s`);
+        lines.push(`  command: ${task.command}`);
+        const tail = outputTail(task.id)?.trim();
+        if (tail) {
+            lines.push("  output tail:");
+            lines.push(...tail.split("\n").slice(-30).map((line) => `    ${line}`));
+        }
+    }
+    // Field-test lesson (2026-07-19): an unconditional "continue the work"
+    // nudge pushed the model to invent follow-up work when nothing was left.
+    lines.push("If unfinished work depends on these results, continue it now. "
+        + "If nothing does, report the outcome to the user in one or two sentences and stop — do not invent new work. "
+        + "Never re-run what already finished.");
+    return lines.join("\n");
+}
+/**
+ * Resume-time orphan detection (design §2.2c): task_started markers with no
+ * matching task_finished/task_killed belong to a previous process. The caller
+ * probes pid liveness before reporting.
+ */
+export function findDanglingTaskStarts(entries) {
+    const started = new Map();
+    for (const entry of entries) {
+        if (entry.type !== "marker" || !entry.value)
+            continue;
+        if (entry.kind === "task_started") {
+            const parsed = parseMarker(entry.value);
+            if (parsed?.id)
+                started.set(parsed.id, parsed);
+        }
+        else if (entry.kind === "task_finished" || entry.kind === "task_killed") {
+            const parsed = parseMarker(entry.value);
+            if (parsed?.id)
+                started.delete(parsed.id);
+        }
+    }
+    return [...started.values()];
+}
+export function isPidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseMarker(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Debounce-then-fire coalescer: the first eligible completion arms a timer;
+ * completions inside the window fold into one wake payload.
+ */
+export class TaskWakeCoalescer {
+    delayMs;
+    fire;
+    pending = [];
+    timer;
+    constructor(delayMs, fire) {
+        this.delayMs = delayMs;
+        this.fire = fire;
+    }
+    add(task) {
+        this.pending.push(task);
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            const tasks = this.pending.splice(0);
+            if (tasks.length > 0)
+                this.fire(tasks);
+        }, this.delayMs);
+        this.timer.unref?.();
+    }
+    /** Drop everything armed (session switch / exit). Returns what was pending. */
+    cancel() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        return this.pending.splice(0);
+    }
+}

package/dist/tools/bash.d.ts

@@ -4,4 +4,18 @@
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
 import type { FileStateTracker } from "./file-state.js";
-export declare function createBashTool(cwd: string, approval?: ApprovalController, _fileState?: FileStateTracker): ToolRegistryEntry;
+import type { ProcessManager } from "../tasks/manager.js";
+import type { PromotionChannel } from "../tasks/promotion.js";
+export interface BashToolOptions {
+    /**
+     * Background tasks are a per-host capability (background-tasks design
+     * §2.0): only the interactive TUI wires the manager AND enables the flag.
+     * Print mode, feishu/desktop hosts, and worktree/workflow children leave
+     * this off, so run_in_background is rejected there with a clear error.
+     */
+    processManager?: ProcessManager;
+    allowBackgroundTasks?: boolean;
+    /** Ctrl+G send-to-background requests, keyed by toolCall id (design §2.5). */
+    promotionChannel?: PromotionChannel;
+}
+export declare function createBashTool(cwd: string, approval?: ApprovalController, _fileState?: FileStateTracker, options?: BashToolOptions): ToolRegistryEntry;

package/dist/tools/bash.js

@@ -11,12 +11,17 @@ const MAX_OUTPUT = 50 * 1024;
 const POST_EXIT_STDIO_GRACE_MS = 150;
 const FORCE_KILL_AFTER_MS = 750;
 const ABORT_SETTLE_AFTER_MS = 1500;
-export function createBashTool(cwd, approval, _fileState) {
+export function createBashTool(cwd, approval, _fileState, options = {}) {
+    const backgroundEnabled = options.allowBackgroundTasks === true && !!options.processManager;
     return {
         name: "bash",
         effect: "unknown",
         requiresApproval: true,
-        description: "Execute a bounded bash command in the working directory. Use timeout for long-running commands. For persistent dev servers or watchers such as npm run dev, next dev, vite, or webpack --watch, use the managed server tools instead of backgrounding a bash command (deferred: load them first via tool_search with query 'select:start_server,server_status,server_logs,stop_server').",
+        description: "Execute a bounded bash command in the working directory. Use timeout for long-running commands. "
+            + (backgroundEnabled
+                ? "For long one-shot commands with a definite end (full test suites, release builds, downloads), pass run_in_background: true — the command keeps running while you continue working and you are notified when it finishes; never poll with foreground sleep. "
+                : "")
+            + "For persistent dev servers or watchers such as npm run dev, next dev, vite, or webpack --watch, use the managed server tools instead of backgrounding a bash command (deferred: load them first via tool_search with query 'select:start_server,server_status,server_logs,stop_server').",
         parameters: {
             type: "object",
             properties: {
@@ -26,6 +31,14 @@ export function createBashTool(cwd, approval, _fileState) {
                     description: "One short sentence (5-10 words) describing what this command does, shown to the user in the UI. Write it in the same language the user is conversing in.",
                 },
                 timeout: { type: "number", description: "Timeout in seconds (optional)" },
+                ...(backgroundEnabled
+                    ? {
+                        run_in_background: {
+                            type: "boolean",
+                            description: "Run as a background task: returns a task id immediately and the command keeps running while you continue. Only for long one-shot commands with a definite end; not for quick commands or persistent servers.",
+                        },
+                    }
+                    : {}),
             },
             required: ["command"],
         },
@@ -35,6 +48,7 @@ export function createBashTool(cwd, approval, _fileState) {
             }
             const command = String(args.command);
             const timeoutSec = typeof args.timeout === "number" ? args.timeout : 60;
+            const runInBackground = args.run_in_background === true;
             const parsedSearch = parseSearchBashCommand(command);
             const parsedRead = parsedSearch ? undefined : parseReadBashCommand(command);
             if (referencesSensitivePath(command)) {
@@ -48,12 +62,50 @@ export function createBashTool(cwd, approval, _fileState) {
                     },
                 };
             }
-            const gate = await gateToolAction(approval, { type: "bash", command, cwd });
+            if (runInBackground && !backgroundEnabled) {
+                return {
+                    content: "Error: run_in_background is unavailable in this session (non-interactive host or subagent). "
+                        + "Run the command in the foreground with an explicit timeout instead.",
+                    isError: true,
+                    status: "blocked",
+                    metadata: { kind: "shell", reason: "background_unavailable" },
+                };
+            }
+            const gate = await gateToolAction(approval, {
+                type: "bash",
+                command,
+                cwd,
+                ...(runInBackground ? { background: true } : {}),
+            });
             if (!gate.approved)
                 return gate.result;
+            if (runInBackground) {
+                try {
+                    const task = options.processManager.startTask({
+                        command,
+                        description: typeof args.description === "string" ? args.description : undefined,
+                        cwd: ctx.cwd || cwd,
+                        ownerSessionId: ctx.sessionID,
+                    });
+                    // Make the read/kill path available immediately — no tool_search hop
+                    // (design §2.1: programmatic unlock at first spawn).
+                    ctx.agent?.unlockDeferredTools?.(["task_output", "kill_task"]);
+                    return {
+                        content: `Started background task ${task.id}${task.description ? ` (${task.description})` : ""}. `
+                            + "It runs while you continue working; you will be notified when it finishes. "
+                            + "Use task_output to check on it, kill_task to stop it.",
+                        status: "success",
+                        metadata: { kind: "shell", command, taskId: task.id, background: true },
+                    };
+                }
+                catch (error) {
+                    return { content: `Error: ${error?.message ?? String(error)}`, isError: true };
+                }
+            }
             return new Promise((resolve) => {
                 const shell = platform() === "win32" ? "cmd.exe" : "bash";
                 const shellArgs = platform() === "win32" ? ["/c", command] : ["-c", command];
+                const spawnedAt = Date.now();
                 const child = spawn(shell, shellArgs, {
                     cwd,
                     stdio: ["ignore", "pipe", "pipe"],
@@ -63,6 +115,8 @@ export function createBashTool(cwd, approval, _fileState) {
                 });
                 let stdout = "";
                 let stderr = "";
+                let promotedTaskId;
+                let unregisterPromotion;
                 let stdoutTruncated = false;
                 let stderrTruncated = false;
                 let stdoutEnded = child.stdout === null;
@@ -127,6 +181,7 @@ export function createBashTool(cwd, approval, _fileState) {
                     if (postExitHandle)
                         clearTimeout(postExitHandle);
                     ctx.abortSignal?.removeEventListener("abort", abortChild);
+                    unregisterPromotion?.();
                     child.stdout?.removeListener("data", onStdoutData);
                     child.stderr?.removeListener("data", onStderrData);
                     child.stdout?.removeListener("end", onStdoutEnd);
@@ -152,6 +207,17 @@ export function createBashTool(cwd, approval, _fileState) {
                         return;
                     resolved = true;
                     cleanup();
+                    if (terminal === "promoted") {
+                        // Ctrl+G promotion (design §2.5): the process lives on under the
+                        // task manager — skip the group kill AND the stream destruction
+                        // (the manager attached its own data listeners in adoptTask).
+                        resolve({
+                            content: buildOutput(`[Moved to background: ${promotedTaskId}. The command keeps running; check it with task_output.]`),
+                            status: "success",
+                            metadata: { kind: "shell", command, taskId: promotedTaskId, background: true },
+                        });
+                        return;
+                    }
                     cleanupBackgroundGroup();
                     destroyStreams();
                     if (terminal === "error") {
@@ -281,6 +347,40 @@ export function createBashTool(cwd, approval, _fileState) {
                         terminal = "exit";
                     finish();
                 };
+                // Ctrl+G promotion (design §2.5): flag-flip into the task manager.
+                // Registered only for background-capable hosts; a no-op once any
+                // terminal state is set (benign race with exit/timeout/cancel).
+                const promoteToBackground = () => {
+                    if (resolved || terminal)
+                        return undefined;
+                    if (!options.processManager)
+                        return undefined;
+                    try {
+                        const task = options.processManager.adoptTask({
+                            command,
+                            description: typeof args.description === "string" ? args.description : undefined,
+                            cwd: ctx.cwd || cwd,
+                            ownerSessionId: ctx.sessionID,
+                            child,
+                            outputSoFar: [stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`]
+                                .filter(Boolean)
+                                .join(""),
+                            startedAt: spawnedAt,
+                        });
+                        promotedTaskId = task.id;
+                    }
+                    catch {
+                        // Task cap reached or adopt failed — keep running in the foreground.
+                        return undefined;
+                    }
+                    terminal = "promoted";
+                    ctx.agent?.unlockDeferredTools?.(["task_output", "kill_task"]);
+                    finish();
+                    return promotedTaskId;
+                };
+                if (backgroundEnabled && options.promotionChannel && ctx.toolCall?.id) {
+                    unregisterPromotion = options.promotionChannel.register(ctx.toolCall.id, promoteToBackground);
+                }
                 timeoutHandle = setTimeout(timeoutChild, timeoutSec * 1000);
                 if (ctx.abortSignal?.aborted)
                     abortChild();

package/dist/tools/child-tools.js

@@ -65,9 +65,11 @@ export class WorktreeApprovalController {
             }
             case "edit":
             case "write":
+                // Reason before the path: subagent tool notes truncate long lines,
+                // and a long absolute path would push the reason off the end.
                 return isPathInsideWorktree(this.worktreeRoot, req.path)
                     ? { action: "approve" }
-                    : { action: "reject", feedback: `Blocked by worktree policy: ${req.path} is outside the subagent worktree.` };
+                    : { action: "reject", feedback: `Blocked by worktree policy: the path is outside the subagent worktree (${req.path}).` };
             case "patch":
                 return req.paths.every((path) => isPathInsideWorktree(this.worktreeRoot, path))
                     ? { action: "approve" }

package/dist/tools/edit.js

@@ -114,18 +114,9 @@ export function createEditTool(cwd, approval, lsp, fileState, checkpoints) {
                 }
             }
             const filePath = resolveToolPath(cwd, args.path);
-            if (!isWithinWorkspace(cwd, filePath)) {
-                return {
-                    content: `Error: Edit path is outside the workspace: ${filePath}`,
-                    isError: true,
-                    status: "blocked",
-                    metadata: {
-                        kind: "security",
-                        path: filePath,
-                        reason: "Edit path is outside the workspace.",
-                    },
-                };
-            }
+            // Outside-workspace paths escalate the approval request instead of
+            // being blocked outright — see the matching note in write.ts.
+            const outsideWorkspace = !isWithinWorkspace(cwd, filePath);
             return withFileMutationQueue(filePath, async () => {
                 try {
                     await access(filePath, constants.R_OK | constants.W_OK);
@@ -161,6 +152,7 @@ export function createEditTool(cwd, approval, lsp, fileState, checkpoints) {
                     path: filePath,
                     diff,
                     fileExists: true,
+                    outsideWorkspace,
                 });
                 if (!gate.approved)
                     return gate.result;

package/dist/tools/index.d.ts

@@ -31,6 +31,8 @@ import type { QuestionController } from "../question/index.js";
 import type { CheckpointStore } from "../checkpoints.js";
 import { FileStateTracker } from "./file-state.js";
 import type { GoalStore } from "../goal/store.js";
+import type { ProcessManager } from "../tasks/manager.js";
+import type { PromotionChannel } from "../tasks/promotion.js";
 export interface CreateAllToolsOptions {
     todoStore?: TodoStore;
     planController?: PlanController;
@@ -47,5 +49,16 @@ export interface CreateAllToolsOptions {
     checkpoints?: () => CheckpointStore | undefined;
     /** Shared goal state; when present, registers the update_goal tool. */
     goalStore?: GoalStore;
+    /**
+     * Unified process manager (background tasks + managed servers). Background
+     * tasks are a per-host capability (background-tasks design §2.0): pass the
+     * manager AND set allowBackgroundTasks only in hosts that wire the full
+     * completion story (currently the interactive TUI). Without it, bash
+     * rejects run_in_background and the task tools are not registered.
+     */
+    processManager?: ProcessManager;
+    allowBackgroundTasks?: boolean;
+    /** Ctrl+G send-to-background requests from the TUI (design §2.5). */
+    promotionChannel?: PromotionChannel;
 }
 export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -41,13 +41,20 @@ import { createQuestionTool } from "./question.js";
 import { createMemoryTool } from "./memory.js";
 import { FileStateTracker } from "./file-state.js";
 import { createGoalTools } from "../goal/tools.js";
+import { createBackgroundTaskTools } from "./task-tools.js";
 export function createAllTools(cwd, skillRegistry, options = {}) {
     const approval = options.approvalController;
     const lsp = options.lspService ?? getLspService(cwd);
     const fileState = options.fileStateTracker ?? new FileStateTracker(cwd);
+    const backgroundTasks = options.allowBackgroundTasks === true && !!options.processManager;
     return [
         createReadTool(cwd, approval, lsp, fileState),
-        createBashTool(cwd, approval, fileState),
+        createBashTool(cwd, approval, fileState, {
+            processManager: options.processManager,
+            allowBackgroundTasks: backgroundTasks,
+            promotionChannel: backgroundTasks ? options.promotionChannel : undefined,
+        }),
+        ...(backgroundTasks ? createBackgroundTaskTools(options.processManager) : []),
         ...createManagedServerTools(cwd, approval),
         createWriteTool(cwd, {}, approval, lsp, fileState, options.checkpoints),
         createEditTool(cwd, approval, lsp, fileState, options.checkpoints),

package/dist/tools/server-manager.d.ts

@@ -1,36 +1,6 @@
-export type ManagedServerPurpose = "preview" | "verification";
-export type ManagedServerLifecycle = "auto" | "keep_alive";
-export type ManagedServerStatus = "starting" | "ready" | "running" | "exited" | "failed" | "stopped";
-export interface ManagedServerInfo {
-    id: string;
-    command: string;
-    cwd: string;
-    port?: number;
-    url?: string;
-    ownerSessionId?: string;
-    ownerRunId?: string;
-    purpose: ManagedServerPurpose;
-    lifecycle: ManagedServerLifecycle;
-    startedAt: number;
-    lastUsedAt: number;
-    status: ManagedServerStatus;
-    pid?: number;
-    exitCode?: number | null;
-}
-export interface StartManagedServerInput {
-    command: string;
-    cwd: string;
-    port?: number;
-    readinessUrl?: string;
-    timeoutSec?: number;
-    ownerSessionId?: string;
-    ownerRunId?: string;
-    purpose?: ManagedServerPurpose;
-    lifecycle?: ManagedServerLifecycle;
-}
-export declare function startManagedServer(input: StartManagedServerInput): Promise<ManagedServerInfo>;
-export declare function listManagedServers(): ManagedServerInfo[];
-export declare function getManagedServer(id: string): ManagedServerInfo | undefined;
-export declare function getManagedServerLogs(id: string, maxChars?: number): string | undefined;
-export declare function stopManagedServer(id: string): Promise<ManagedServerInfo | undefined>;
-export declare function stopAutoServersForSession(sessionID?: string): Promise<void>;
+/**
+ * Compatibility shim: the managed-server runtime moved into the unified
+ * process manager (src/tasks/manager.ts, background-tasks design §2.2).
+ * Existing imports — server tools, agent.ts, tests — keep working unchanged.
+ */
+export { getManagedServer, getManagedServerLogs, listManagedServers, startManagedServer, stopAutoServersForSession, stopManagedServer, type ManagedServerInfo, type ManagedServerLifecycle, type ManagedServerPurpose, type ManagedServerStatus, type StartManagedServerInput, } from "../tasks/manager.js";