@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/tasks/manager.js

@@ -0,0 +1,634 @@
+/**
+ * Unified process manager: background tasks + managed servers
+ * (docs/background-tasks-design.md §2.2).
+ *
+ * One registry owns every child process Bubble manages, discriminated by
+ * `kind: "task" | "server"` — NOT `purpose`, which is a shipped model-facing
+ * server field (preview|verification). Server semantics (port conflict scan,
+ * readiness probe, lifecycle, lastUsedAt touch-on-read) are preserved
+ * verbatim from the absorbed src/tools/server-manager.ts; that module remains
+ * as a re-export shim so server tools, agent.ts, and their tests are
+ * untouched.
+ *
+ * State is per-process (as the old server registry was). main.ts fetches the
+ * instance via getProcessManager() and passes it explicitly to createAllTools
+ * and the TUI App — the TUI bridge is subscription-based (onChange /
+ * onTaskFinished), never a hidden import (design §2.2a).
+ *
+ * Task children are spawned detached (own process group, killable as a tree)
+ * but NOT unref'd — unlike servers, a task must never outlive the parent
+ * process, so the event loop keeps owning it (design §2.2a). Reaping is
+ * three-layered (design §2.2b): graceful shutdownTasks() with escalation, a
+ * SIGKILL-only path for signal handlers, and a process.once("exit") backstop.
+ *
+ * Finalization waits for stdio to drain: Node may emit "exit" before the last
+ * pipe chunks are delivered, so a record is settled on "close" — with a short
+ * grace timer from "exit" as the fallback, because a detached grandchild that
+ * inherited the pipes (`some-server &`) can keep "close" from ever firing.
+ * Same pattern as POST_EXIT_STDIO_GRACE_MS in src/tools/bash.ts.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import { platform } from "node:os";
+import { appendTailCapped, killProcessTree, stripAnsi, tail } from "./process-utils.js";
+const MAX_LOG_BYTES = 96 * 1024;
+const STOP_FORCE_AFTER_MS = 1000;
+const POST_EXIT_STDIO_GRACE_MS = 150;
+const MAX_RUNNING_TASKS_PER_SESSION = 8;
+const MAX_FINISHED_TASKS = 20;
+function countLineBreaks(value) {
+    let count = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        if (value.charCodeAt(index) === 10)
+            count += 1;
+    }
+    return count;
+}
+function logicalLineCount(lineBreaks, hasData, endsWithNewline) {
+    if (!hasData)
+        return 0;
+    return lineBreaks + (endsWithNewline ? 0 : 1);
+}
+// ---------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------
+export class ProcessManager {
+    registry = new Map();
+    nextServerId = 1;
+    nextTaskId = 1;
+    /** Bumped on task start/finish/kill — the reminder's state-change gate (design §2.3a). */
+    taskStateVersion = 0;
+    changeListeners = new Set();
+    finishListeners = new Set();
+    // -- tasks ----------------------------------------------------------------
+    getTaskStateVersion() {
+        return this.taskStateVersion;
+    }
+    startTask(input) {
+        if (!existsSync(input.cwd)) {
+            throw new Error(`Working directory does not exist: ${input.cwd}`);
+        }
+        const command = input.command.trim();
+        if (!command)
+            throw new Error("command is required");
+        // Atomic reserve (design §2.2d): the cap check and record insertion are
+        // synchronous with no await between them; spawn failures roll back below.
+        this.reserveTaskSlot(input.ownerSessionId);
+        const shell = platform() === "win32" ? "cmd.exe" : "bash";
+        const shellArgs = platform() === "win32" ? ["/c", command] : ["-c", command];
+        let child;
+        try {
+            child = spawn(shell, shellArgs, {
+                cwd: input.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: process.env,
+                detached: platform() !== "win32",
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        return this.registerTaskChild(child, { ...input, command });
+    }
+    /** Ctrl+B promotion: adopt a child the bash tool already spawned (§2.5). */
+    adoptTask(input) {
+        this.reserveTaskSlot(input.ownerSessionId);
+        return this.registerTaskChild(input.child, input, {
+            outputSoFar: input.outputSoFar,
+            startedAt: input.startedAt,
+        });
+    }
+    reserveTaskSlot(ownerSessionId) {
+        const running = this.taskRecords().filter((task) => task.status === "running" && task.ownerSessionId === ownerSessionId);
+        if (running.length >= MAX_RUNNING_TASKS_PER_SESSION) {
+            throw new Error(`Background task limit reached (${MAX_RUNNING_TASKS_PER_SESSION} running). `
+                + "Wait for one to finish with task_output, or kill one with kill_task.");
+        }
+    }
+    registerTaskChild(child, input, seed) {
+        const id = `task_${String(this.nextTaskId++).padStart(4, "0")}`;
+        const seedOutput = seed?.outputSoFar ?? "";
+        const seedLineBreaks = countLineBreaks(seedOutput);
+        const record = {
+            kind: "task",
+            id,
+            command: input.command,
+            description: input.description,
+            cwd: input.cwd,
+            pid: child.pid,
+            status: "running",
+            startedAt: seed?.startedAt ?? Date.now(),
+            output: seedOutput,
+            outputTruncated: false,
+            outputLines: logicalLineCount(seedLineBreaks, seedOutput.length > 0, seedOutput.endsWith("\n")),
+            outputLineBreaks: seedLineBreaks,
+            outputHasData: seedOutput.length > 0,
+            outputEndsWithNewline: seedOutput.endsWith("\n"),
+            ownerSessionId: input.ownerSessionId,
+            child,
+        };
+        this.registry.set(id, record);
+        const append = (data) => {
+            const chunk = data.toString();
+            const before = record.output;
+            record.output = appendTailCapped(record.output, chunk, MAX_LOG_BYTES);
+            record.outputLineBreaks += countLineBreaks(chunk);
+            if (chunk.length > 0) {
+                record.outputHasData = true;
+                record.outputEndsWithNewline = chunk.endsWith("\n");
+            }
+            record.outputLines = logicalLineCount(record.outputLineBreaks, record.outputHasData, record.outputEndsWithNewline);
+            if (!record.outputTruncated && before.length + data.length > record.output.length) {
+                record.outputTruncated = true;
+            }
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        child.once("error", (error) => {
+            append(Buffer.from(`\n[task failed to start: ${error.message}]\n`));
+            this.finalizeTask(record, "failed", null);
+        });
+        record.settled = onChildSettled(child, {
+            onExit: (code) => {
+                record.exited = { code };
+            },
+            onSettled: (code) => this.finalizeExitedTask(record, code),
+        });
+        this.bumpTaskState(record);
+        return this.publicTask(record);
+    }
+    finalizeExitedTask(record, code) {
+        this.finalizeTask(record, code === 0 ? "completed" : "failed", code);
+    }
+    finalizeTask(record, status, exitCode) {
+        if (record.status !== "running")
+            return;
+        record.status = status;
+        record.exitCode = exitCode;
+        record.endedAt = Date.now();
+        record.child = undefined;
+        this.evictFinishedTasks();
+        this.bumpTaskState(record);
+        const snapshot = this.publicTask(record);
+        for (const listener of this.finishListeners) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // Listener failures must never break task lifecycle.
+            }
+        }
+    }
+    getTask(id) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return undefined;
+        return this.publicTask(record);
+    }
+    listTasks(ownerSessionId) {
+        return this.taskRecords()
+            .filter((task) => ownerSessionId === undefined || task.ownerSessionId === ownerSessionId)
+            .map((task) => this.publicTask(task));
+    }
+    taskOutputTail(id, maxChars = 12000) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return undefined;
+        // Single choke point for every task-output consumer (wake, reminder,
+        // task_output tool, inspector): strip ANSI color noise before tailing.
+        return tail(stripAnsi(record.output), maxChars);
+    }
+    markTaskDelivered(id) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return;
+        if (record.deliveredAt === undefined) {
+            record.deliveredAt = Date.now();
+            // Delivery suppresses duplicate Agent wakes, but the task inspector and
+            // `y` copy action must retain the output for the complete UI lifecycle.
+            // The existing 96KB-per-task cap and 20-task eviction bound memory.
+        }
+    }
+    async waitTasks(ids, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 30000;
+        const mode = options.mode ?? "any";
+        const wanted = new Set(ids);
+        const satisfied = () => {
+            const finished = ids.filter((id) => {
+                const task = this.registry.get(id);
+                return task?.kind === "task" && task.status !== "running";
+            });
+            return mode === "all" ? finished.length === wanted.size : finished.length > 0;
+        };
+        if (!satisfied() && timeoutMs > 0) {
+            await new Promise((resolve) => {
+                let settled = false;
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    this.finishListeners.delete(onFinish);
+                    clearTimeout(timer);
+                    resolve();
+                };
+                const onFinish = (task) => {
+                    if (wanted.has(task.id) && satisfied())
+                        finish();
+                };
+                const timer = setTimeout(finish, timeoutMs);
+                timer.unref?.();
+                this.finishListeners.add(onFinish);
+            });
+        }
+        return ids
+            .map((id) => this.getTask(id))
+            .filter((task) => task !== undefined);
+    }
+    async killTask(id) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return undefined;
+        if (record.status !== "running")
+            return this.publicTask(record);
+        const pid = record.child?.pid ?? record.pid;
+        // Mark first so the exit listener does not double-finalize as failed. A
+        // task that already exited on its own keeps its real outcome instead, and
+        // is left to the close/grace path: finish listeners snapshot the output
+        // tail, so they must not fire before the pending pipe data is appended.
+        if (!record.exited)
+            this.finalizeTask(record, "killed", null);
+        if (pid) {
+            // Also reaps pipe-holding grandchildren, which lets "close" fire promptly.
+            killProcessTree(pid, "SIGTERM");
+            const forceTimer = setTimeout(() => killProcessTree(pid, "SIGKILL"), STOP_FORCE_AFTER_MS);
+            forceTimer.unref?.();
+        }
+        if (record.exited)
+            await record.settled;
+        return this.publicTask(record);
+    }
+    /** Graceful reaping for shutdownRuntime (design §2.2b layer 1). */
+    async shutdownTasks() {
+        const running = this.taskRecords().filter((task) => task.status === "running");
+        if (running.length === 0)
+            return;
+        for (const task of running) {
+            const pid = task.child?.pid ?? task.pid;
+            if (pid)
+                killProcessTree(pid, "SIGTERM");
+        }
+        await new Promise((resolve) => setTimeout(resolve, STOP_FORCE_AFTER_MS));
+        for (const task of running) {
+            const pid = task.child?.pid ?? task.pid;
+            if (pid)
+                killProcessTree(pid, "SIGKILL");
+            if (task.status !== "running")
+                continue;
+            // Exited on its own inside the drain window: bounded wait for its output.
+            if (task.exited)
+                await task.settled;
+            else
+                this.finalizeTask(task, "killed", null);
+        }
+    }
+    /** SIGKILL-only reaping for synchronous signal/exit paths (§2.2b layers 2-3). */
+    reapTasksSync() {
+        for (const task of this.taskRecords()) {
+            if (task.status !== "running")
+                continue;
+            const pid = task.child?.pid ?? task.pid;
+            if (pid)
+                killProcessTree(pid, "SIGKILL");
+            task.status = "killed";
+            task.endedAt = Date.now();
+            task.child = undefined;
+        }
+    }
+    onTaskFinished(listener) {
+        this.finishListeners.add(listener);
+        return () => this.finishListeners.delete(listener);
+    }
+    onChange(listener) {
+        this.changeListeners.add(listener);
+        return () => this.changeListeners.delete(listener);
+    }
+    bumpTaskState(record) {
+        this.taskStateVersion += 1;
+        const snapshot = this.publicTask(record);
+        for (const listener of this.changeListeners) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // Listener failures must never break task lifecycle.
+            }
+        }
+    }
+    evictFinishedTasks() {
+        const finished = this.taskRecords()
+            .filter((task) => task.status !== "running")
+            .sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0));
+        // Evict oldest DELIVERED first; fall back to oldest finished overall.
+        while (finished.length > MAX_FINISHED_TASKS) {
+            const victim = finished.find((task) => task.deliveredAt !== undefined) ?? finished[0];
+            finished.splice(finished.indexOf(victim), 1);
+            this.registry.delete(victim.id);
+        }
+    }
+    taskRecords() {
+        return [...this.registry.values()].filter((record) => record.kind === "task");
+    }
+    publicTask(record) {
+        const { child: _child, exited: _exited, settled: _settled, output: _output, outputLineBreaks: _outputLineBreaks, outputHasData: _outputHasData, outputEndsWithNewline: _outputEndsWithNewline, ...info } = record;
+        return { ...info };
+    }
+    // -- servers (moved verbatim from server-manager.ts, kind-filtered) --------
+    async startManagedServer(input) {
+        if (!existsSync(input.cwd)) {
+            throw new Error(`Working directory does not exist: ${input.cwd}`);
+        }
+        const command = input.command.trim();
+        if (!command) {
+            throw new Error("command is required");
+        }
+        if (input.port !== undefined) {
+            const managed = this.serverRecords().find((server) => server.port === input.port && isActiveStatus(server.status));
+            if (managed) {
+                throw new Error(`Port ${input.port} is already managed by ${managed.id}. Stop it before starting another server.`);
+            }
+            if (await isPortOpen(input.port)) {
+                throw new Error(`Port ${input.port} is already in use by an unmanaged process.`);
+            }
+        }
+        const shell = platform() === "win32" ? "cmd.exe" : "bash";
+        const shellArgs = platform() === "win32" ? ["/c", command] : ["-c", command];
+        const child = spawn(shell, shellArgs, {
+            cwd: input.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+            detached: platform() !== "win32",
+            windowsHide: true,
+        });
+        child.unref();
+        unrefStream(child.stdout);
+        unrefStream(child.stderr);
+        const now = Date.now();
+        const id = `server_${String(this.nextServerId++).padStart(4, "0")}`;
+        const readinessUrl = input.readinessUrl ?? (input.port ? `http://localhost:${input.port}` : undefined);
+        const record = {
+            kind: "server",
+            id,
+            command,
+            cwd: input.cwd,
+            ...(input.port !== undefined ? { port: input.port } : {}),
+            ...(readinessUrl ? { url: readinessUrl } : {}),
+            ownerSessionId: input.ownerSessionId,
+            ownerRunId: input.ownerRunId,
+            purpose: input.purpose ?? "preview",
+            lifecycle: input.lifecycle ?? "keep_alive",
+            startedAt: now,
+            lastUsedAt: now,
+            status: "starting",
+            pid: child.pid,
+            child,
+            logs: "",
+        };
+        this.registry.set(id, record);
+        child.stdout.on("data", (data) => appendServerLog(record, data.toString()));
+        child.stderr.on("data", (data) => appendServerLog(record, data.toString()));
+        child.once("error", (error) => {
+            record.status = "failed";
+            appendServerLog(record, `\n[server failed: ${error.message}]\n`);
+        });
+        // Settle after stdio drains so a fast crash surfaces its logs in the
+        // "did not become ready" error instead of racing the status flip.
+        record.settled = onChildSettled(child, {
+            unrefTimer: true,
+            onExit: (code) => {
+                record.exited = { code };
+            },
+            onSettled: (code) => {
+                record.exitCode = code;
+                if (record.status !== "stopped") {
+                    record.status = code === 0 ? "exited" : "failed";
+                }
+                record.child = undefined;
+            },
+        });
+        const timeoutSec = input.timeoutSec ?? 30;
+        const ready = readinessUrl
+            ? await waitForReadiness(record, readinessUrl, timeoutSec)
+            : await waitForProcessToStayAlive(record, Math.min(timeoutSec, 2));
+        // `exited` is checked on its own: the status flip lags "exit" by the drain
+        // window, so a server dying right at the deadline still reads as active.
+        if (!ready || record.exited) {
+            // Bounded: lets the crash output land before it is quoted below.
+            if (record.exited)
+                await record.settled;
+            const logs = record.logs.trim();
+            await this.stopManagedServer(id);
+            throw new Error(`Server ${id} did not become ready within ${timeoutSec}s.${logs ? `\n\nLogs:\n${tail(logs, 4000)}` : ""}`);
+        }
+        record.status = readinessUrl ? "ready" : "running";
+        record.lastUsedAt = Date.now();
+        return publicServerInfo(record);
+    }
+    listManagedServers() {
+        return this.serverRecords().map(publicServerInfo);
+    }
+    getManagedServer(id) {
+        const server = this.registry.get(id);
+        if (!server || server.kind !== "server")
+            return undefined;
+        server.lastUsedAt = Date.now();
+        return publicServerInfo(server);
+    }
+    getManagedServerLogs(id, maxChars = 12000) {
+        const server = this.registry.get(id);
+        if (!server || server.kind !== "server")
+            return undefined;
+        server.lastUsedAt = Date.now();
+        return tail(server.logs, maxChars);
+    }
+    async stopManagedServer(id) {
+        const server = this.registry.get(id);
+        if (!server || server.kind !== "server")
+            return undefined;
+        server.status = "stopped";
+        server.lastUsedAt = Date.now();
+        const child = server.child;
+        if (child?.pid) {
+            killProcessTree(child.pid, "SIGTERM");
+            await new Promise((resolve) => setTimeout(resolve, STOP_FORCE_AFTER_MS));
+            killProcessTree(child.pid, "SIGKILL");
+        }
+        server.child = undefined;
+        return publicServerInfo(server);
+    }
+    async stopAutoServersForSession(sessionID) {
+        if (!sessionID)
+            return;
+        const owned = this.serverRecords().filter((server) => server.ownerSessionId === sessionID && server.lifecycle === "auto" && isActiveStatus(server.status));
+        await Promise.all(owned.map((server) => this.stopManagedServer(server.id)));
+    }
+    /** process.once("exit") backstop (§2.2b layer 3). */
+    reapOnExit() {
+        for (const record of this.registry.values()) {
+            if (record.kind === "task") {
+                if (record.status === "running") {
+                    const pid = record.child?.pid ?? record.pid;
+                    if (pid)
+                        killProcessTree(pid, "SIGKILL");
+                }
+                continue;
+            }
+            if (record.child?.pid && record.lifecycle !== "keep_alive") {
+                killProcessTree(record.child.pid, "SIGKILL");
+            }
+        }
+    }
+    serverRecords() {
+        return [...this.registry.values()].filter((record) => record.kind === "server");
+    }
+}
+// ---------------------------------------------------------------------------
+// Process-wide instance + compatibility surface
+// ---------------------------------------------------------------------------
+// One registry per process (exactly the scope the old module-level server Map
+// had). main.ts passes this instance down explicitly; the server-manager shim
+// delegates to it so existing imports keep working.
+const defaultManager = new ProcessManager();
+export function getProcessManager() {
+    return defaultManager;
+}
+export const startManagedServer = defaultManager.startManagedServer.bind(defaultManager);
+export const listManagedServers = defaultManager.listManagedServers.bind(defaultManager);
+export const getManagedServer = defaultManager.getManagedServer.bind(defaultManager);
+export const getManagedServerLogs = defaultManager.getManagedServerLogs.bind(defaultManager);
+export const stopManagedServer = defaultManager.stopManagedServer.bind(defaultManager);
+export const stopAutoServersForSession = defaultManager.stopAutoServersForSession.bind(defaultManager);
+process.once("exit", () => {
+    defaultManager.reapOnExit();
+});
+// ---------------------------------------------------------------------------
+// Server internals (moved verbatim)
+// ---------------------------------------------------------------------------
+/**
+ * Calls `onSettled` exactly once, after the child has exited AND its stdio has
+ * drained ("close"), or POST_EXIT_STDIO_GRACE_MS after "exit" when something
+ * else still holds the pipes open. `onExit` fires synchronously at "exit".
+ * The returned promise resolves right after `onSettled` has run.
+ */
+function onChildSettled(child, handlers) {
+    let settled = false;
+    let resolveSettled;
+    const done = new Promise((resolve) => {
+        resolveSettled = resolve;
+    });
+    let graceTimer;
+    const settle = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        if (graceTimer)
+            clearTimeout(graceTimer);
+        try {
+            handlers.onSettled(code);
+        }
+        finally {
+            resolveSettled();
+        }
+    };
+    child.once("exit", (code) => {
+        handlers.onExit?.(code);
+        if (settled)
+            return;
+        // Timers run before the poll phase: if the loop stalled past the grace
+        // period, output already sitting in the pipe has not been read yet. Yield
+        // through one poll phase (setImmediate) so it is appended before settling.
+        graceTimer = setTimeout(() => setImmediate(() => settle(code)), POST_EXIT_STDIO_GRACE_MS);
+        if (handlers.unrefTimer)
+            graceTimer.unref?.();
+    });
+    child.once("close", (code) => settle(code));
+    return done;
+}
+function publicServerInfo(server) {
+    return {
+        id: server.id,
+        command: server.command,
+        cwd: server.cwd,
+        port: server.port,
+        url: server.url,
+        ownerSessionId: server.ownerSessionId,
+        ownerRunId: server.ownerRunId,
+        purpose: server.purpose,
+        lifecycle: server.lifecycle,
+        startedAt: server.startedAt,
+        lastUsedAt: server.lastUsedAt,
+        status: server.status,
+        pid: server.pid,
+        exitCode: server.exitCode,
+    };
+}
+function appendServerLog(server, chunk) {
+    server.logs = appendTailCapped(server.logs, chunk, MAX_LOG_BYTES);
+}
+function unrefStream(stream) {
+    stream.unref?.();
+}
+async function waitForReadiness(server, url, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    while (Date.now() < deadline) {
+        if (!isServerAlive(server))
+            return false;
+        if (await canFetch(url))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return false;
+}
+async function waitForProcessToStayAlive(server, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    while (Date.now() < deadline) {
+        if (!isServerAlive(server))
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return isServerAlive(server);
+}
+async function canFetch(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1000);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        return response.status < 500;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function isServerAlive(server) {
+    return !server.exited && isActiveStatus(server.status);
+}
+function isActiveStatus(status) {
+    return status === "starting" || status === "ready" || status === "running";
+}
+async function isPortOpen(port) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection({ host: "127.0.0.1", port });
+        const done = (open) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(open);
+        };
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+        socket.setTimeout(250, () => done(false));
+    });
+}

package/dist/tasks/process-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared child-process mechanics for the unified process manager (background
+ * tasks + managed servers) and the bash tool: process-tree kill with Windows
+ * fallback, tail-keeping capped log buffers.
+ */
+export declare function killProcessTree(pid: number, signal: NodeJS.Signals): void;
+/** Keep the LAST maxBytes of a growing log (ring-buffer semantics). */
+export declare function appendTailCapped(current: string, chunk: string, maxBytes: number): string;
+export declare function tail(value: string, maxChars: number): string;
+export declare function stripAnsi(value: string): string;

package/dist/tasks/process-utils.js

@@ -0,0 +1,49 @@
+/**
+ * Shared child-process mechanics for the unified process manager (background
+ * tasks + managed servers) and the bash tool: process-tree kill with Windows
+ * fallback, tail-keeping capped log buffers.
+ */
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+export function killProcessTree(pid, signal) {
+    if (platform() === "win32") {
+        try {
+            spawn("taskkill", ["/pid", String(pid), "/f", "/t"], {
+                stdio: "ignore",
+                windowsHide: true,
+            });
+        }
+        catch {
+            // Process may already be gone or taskkill may be unavailable.
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Process already exited.
+        }
+    }
+}
+/** Keep the LAST maxBytes of a growing log (ring-buffer semantics). */
+export function appendTailCapped(current, chunk, maxBytes) {
+    const next = current + chunk;
+    if (Buffer.byteLength(next, "utf-8") <= maxBytes)
+        return next;
+    return Buffer.from(next, "utf-8").subarray(-maxBytes).toString("utf-8");
+}
+export function tail(value, maxChars) {
+    return value.length <= maxChars ? value : value.slice(-maxChars);
+}
+// Test runners color their output; raw escape sequences in a model-facing
+// tail are token noise (observed with vitest in the first field test).
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\u001b\[[0-9;?]*[a-zA-Z]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g;
+export function stripAnsi(value) {
+    return value.replace(ANSI_PATTERN, "");
+}