@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/agent/workflow/runtime.js

@@ -0,0 +1,319 @@
+/**
+ * Workflow runtime (option C) — executes an LLM-authored JS orchestration
+ * script in a QuickJS-wasm sandbox and returns its final value.
+ *
+ * Engine decision (proven empirically, node + bun): the SYNC variant with a
+ * `newPromise` deferred-promise bridge — NOT asyncify. Asyncify serializes
+ * parallel() and corrupts the VM on the 2nd agent failure; the sync+newPromise
+ * bridge gives true concurrency AND clean error propagation across many
+ * failures. The host drives the VM job queue via executePendingJobs().
+ *
+ * The script's only capability is agent(); it has no fs/shell/net/clock/RNG
+ * (determinism gating below). parallel/pipeline/phase/log/budget are a JS
+ * prelude over the single host function __agent plus a few host callbacks.
+ */
+import { getQuickJS } from "quickjs-emscripten";
+/**
+ * Async semaphore bounding how many workflow agents run concurrently — kept
+ * below the global scheduler cap so interactive subagents always have slots
+ * (option C review M2/M5). Permits are acquired/released only around a leaf
+ * agent dispatch, never across parallel/pipeline composition (no deadlock).
+ */
+export class WorkflowConcurrencyGate {
+    capacity;
+    active = 0;
+    waiters = [];
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    async acquire() {
+        if (this.active < this.capacity) {
+            this.active += 1;
+            return;
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+        this.active += 1;
+    }
+    release() {
+        this.active -= 1;
+        const next = this.waiters.shift();
+        if (next)
+            next();
+    }
+}
+const DEFAULT_MAX_AGENTS = 1000;
+const DEFAULT_COMPUTE_DEADLINE_MS = 10_000;
+// JS prelude evaluated before the user script: defines the script API in terms
+// of the minimal host surface (__agent / __phase / __log / __budget*).
+const PRELUDE = `
+globalThis.agent = async (prompt, opts) => {
+  const raw = await __agent(JSON.stringify({ prompt: String(prompt ?? ""), opts: opts || {} }));
+  return JSON.parse(raw);
+};
+globalThis.parallel = (thunks) => {
+  if (!Array.isArray(thunks)) throw new TypeError("parallel() expects an array of functions");
+  if (thunks.some((t) => typeof t !== "function")) {
+    throw new TypeError("parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)");
+  }
+  return Promise.all(thunks.map((t) => {
+    try { return Promise.resolve(t()).catch(() => null); } catch (_e) { return Promise.resolve(null); }
+  }));
+};
+globalThis.pipeline = (items, ...stages) => {
+  if (!Array.isArray(items)) throw new TypeError("pipeline() expects an array as the first argument");
+  if (stages.some((s) => typeof s !== "function")) {
+    throw new TypeError("pipeline() stages must be functions: pipeline(items, item => ..., result => ...)");
+  }
+  return Promise.all(items.map(async (item, i) => {
+    let v = item;
+    for (const stage of stages) {
+      try { v = await stage(v, item, i); } catch (_e) { return null; }
+    }
+    return v;
+  }));
+};
+globalThis.phase = (t) => __phase(String(t ?? ""));
+globalThis.log = (m) => __log(String(m ?? ""));
+globalThis.budget = {
+  get total() { return __budgetTotal(); },
+  spent() { return __budgetSpent(); },
+  remaining() { return __budgetRemaining(); },
+};
+`;
+/** Removes ambient nondeterminism so a run is reproducible (design §4.3). */
+const DETERMINISM_GATING = `
+delete globalThis.Date;
+Object.defineProperty(globalThis, "Date", {
+  configurable: false,
+  get() { throw new Error("Workflow scripts must be deterministic: Date.now()/new Date() are unavailable — pass timestamps in via args"); },
+});
+delete globalThis.WeakRef;
+delete globalThis.FinalizationRegistry;
+Math.random = () => { throw new Error("Workflow scripts must be deterministic: Math.random() is unavailable"); };
+`;
+/** Turns `export const meta = …` / `export function …` into plain declarations. */
+function stripExports(script) {
+    return script.replace(/(^|\n)\s*export\s+(const|let|var|function|class|async)\b/g, "$1$2");
+}
+/** Lines injected before the script body in the wrapped source (keep in sync with buildWrappedWorkflowSource). */
+const WRAPPER_LINE_OFFSET = 2;
+/** The EXACT source runWorkflow executes — the syntax probe must compile this, not the raw script. */
+export function buildWrappedWorkflowSource(script) {
+    return [
+        "globalThis.__wfdone = false; globalThis.__wfresult = null; globalThis.__wferror = null;",
+        "(async () => {",
+        stripExports(script),
+        "})().then(",
+        "  (r) => { globalThis.__wfresult = r === undefined ? null : r; globalThis.__wfdone = true; },",
+        "  (e) => { globalThis.__wferror = (e && e.message) ? String(e.message) : String(e); globalThis.__wfdone = true; }",
+        ");",
+    ].join("\n");
+}
+/**
+ * Submit-time syntax check: compiles the exact transformed source with
+ * QuickJS's compile-only flag (same engine, zero grammar divergence) so the
+ * model gets a teaching error as the immediate tool result instead of one
+ * full turn later through the background-run delivery path.
+ */
+export async function precompileWorkflowScript(script) {
+    const QuickJS = await getQuickJS();
+    const vm = QuickJS.newContext();
+    try {
+        const result = vm.evalCode(buildWrappedWorkflowSource(script), "workflow.js", { compileOnly: true });
+        if (result.error) {
+            const message = vm.dump(result.error);
+            result.error.dispose();
+            return { ok: false, error: `workflow script error: ${formatError(message)}` };
+        }
+        result.value.dispose();
+        return { ok: true };
+    }
+    finally {
+        try {
+            vm.dispose();
+        }
+        catch { /* teardown must not mask the verdict */ }
+    }
+}
+export async function runWorkflow(options) {
+    const QuickJS = await getQuickJS();
+    const vm = QuickJS.newContext();
+    const pending = new Set();
+    // Deferreds for in-flight agent() calls. If the run ends while agents are
+    // still flying (user abort, stall, compute deadline), these were never
+    // settled and their VM-side handles are still alive — disposing the VM
+    // with them alive trips QuickJS's JS_FreeRuntime assertion and Aborts the
+    // (process-wide, cached) wasm module, poisoning every later workflow.
+    const liveDeferreds = new Set();
+    const state = { disposed: false };
+    let agentCount = 0;
+    const maxAgents = options.maxAgents ?? DEFAULT_MAX_AGENTS;
+    // Per-compute deadline: only counts VM bytecode time, reset on each pump so a
+    // long run that is mostly waiting on agents is not killed.
+    let computeStart = Date.now();
+    const computeDeadline = options.computeDeadlineMs ?? DEFAULT_COMPUTE_DEADLINE_MS;
+    vm.runtime.setInterruptHandler(() => Date.now() - computeStart > computeDeadline);
+    try {
+        vm.unwrapResult(vm.evalCode(DETERMINISM_GATING)).dispose();
+        installHostFunctions(vm, options, pending, () => agentCount, () => { agentCount += 1; }, maxAgents, state, liveDeferreds);
+        // args as a deterministic injected global.
+        const argsJson = JSON.stringify(options.args ?? null);
+        vm.unwrapResult(vm.evalCode(`globalThis.args = ${argsJson};`)).dispose();
+        vm.unwrapResult(vm.evalCode(PRELUDE)).dispose();
+        const wrapped = buildWrappedWorkflowSource(options.script);
+        computeStart = Date.now();
+        const evalResult = vm.evalCode(wrapped, "workflow.js");
+        if (evalResult.error) {
+            const message = vm.dump(evalResult.error);
+            evalResult.error.dispose();
+            return { ok: false, error: `workflow script error: ${formatError(message)}` };
+        }
+        evalResult.value.dispose();
+        // Drive the VM job queue interleaved with host agent settlements.
+        const isDone = () => {
+            const h = vm.getProp(vm.global, "__wfdone");
+            const done = vm.dump(h) === true;
+            h.dispose();
+            return done;
+        };
+        while (!isDone()) {
+            if (options.signal?.aborted) {
+                return { ok: false, error: "workflow aborted" };
+            }
+            computeStart = Date.now();
+            vm.runtime.executePendingJobs();
+            if (isDone())
+                break;
+            if (pending.size === 0) {
+                if (!vm.runtime.hasPendingJob || !vm.runtime.hasPendingJob())
+                    break; // settled or stalled
+                continue;
+            }
+            await Promise.race([...pending, abortRace(options.signal)]);
+        }
+        const errH = vm.getProp(vm.global, "__wferror");
+        const err = vm.dump(errH);
+        errH.dispose();
+        if (err != null && err !== "") {
+            return { ok: false, error: String(err) };
+        }
+        const resH = vm.getProp(vm.global, "__wfresult");
+        const value = vm.dump(resH);
+        resH.dispose();
+        return { ok: true, value };
+    }
+    catch (error) {
+        return { ok: false, error: error?.message || String(error) };
+    }
+    finally {
+        state.disposed = true;
+        for (const deferred of liveDeferreds) {
+            try {
+                deferred.dispose();
+            }
+            catch { /* already settled/disposed */ }
+        }
+        liveDeferreds.clear();
+        try {
+            vm.dispose();
+        }
+        catch { /* a dispose failure must not mask the run's result */ }
+    }
+}
+function abortRace(signal) {
+    if (!signal)
+        return new Promise(() => { }); // never settles
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+function installHostFunctions(vm, options, pending, getCount, bumpCount, maxAgents, state, liveDeferreds) {
+    vm.newFunction("__agent", (specHandle) => {
+        const spec = JSON.parse(vm.getString(specHandle));
+        const deferred = vm.newPromise();
+        liveDeferreds.add(deferred);
+        // Settling the VM promise touches the context, which may have been disposed
+        // if the run was aborted while host work was still in flight — guard it.
+        const settle = (fn) => {
+            if (state.disposed)
+                return;
+            try {
+                fn();
+            }
+            catch { /* VM disposed mid-settle */ }
+        };
+        if (getCount() >= maxAgents) {
+            const e = vm.newString(`workflow exceeded the ${maxAgents}-agent cap`);
+            deferred.reject(e);
+            e.dispose();
+        }
+        else {
+            bumpCount();
+            const p = options.dispatchAgent(spec).then((res) => settle(() => {
+                if (res.ok) {
+                    const v = vm.newString(JSON.stringify(res.value ?? null));
+                    deferred.resolve(v);
+                    v.dispose();
+                }
+                else {
+                    const e = vm.newString(res.error);
+                    deferred.reject(e);
+                    e.dispose();
+                }
+            }), (err) => settle(() => {
+                const e = vm.newString(err?.message || String(err));
+                deferred.reject(e);
+                e.dispose();
+            })).finally(() => { pending.delete(p); });
+            pending.add(p);
+        }
+        deferred.settled.then(() => {
+            liveDeferreds.delete(deferred);
+            if (!state.disposed)
+                try {
+                    vm.runtime.executePendingJobs();
+                }
+                catch { /* disposed */ }
+        });
+        return deferred.handle;
+    }).consume((f) => vm.setProp(vm.global, "__agent", f));
+    vm.newFunction("__phase", (h) => {
+        options.onPhase?.(vm.getString(h));
+        return vm.undefined;
+    }).consume((f) => vm.setProp(vm.global, "__phase", f));
+    vm.newFunction("__log", (h) => {
+        options.onLog?.(vm.getString(h));
+        return vm.undefined;
+    }).consume((f) => vm.setProp(vm.global, "__log", f));
+    vm.newFunction("__budgetTotal", () => {
+        const total = options.budget?.total ?? null;
+        return total === null ? vm.null : vm.newNumber(total);
+    }).consume((f) => vm.setProp(vm.global, "__budgetTotal", f));
+    vm.newFunction("__budgetSpent", () => vm.newNumber(options.budget?.spent() ?? 0))
+        .consume((f) => vm.setProp(vm.global, "__budgetSpent", f));
+    vm.newFunction("__budgetRemaining", () => {
+        const remaining = options.budget?.remaining() ?? Number.POSITIVE_INFINITY;
+        return vm.newNumber(Number.isFinite(remaining) ? remaining : Number.MAX_SAFE_INTEGER);
+    }).consume((f) => vm.setProp(vm.global, "__budgetRemaining", f));
+}
+function formatError(value) {
+    if (value && typeof value === "object" && "message" in value) {
+        const obj = value;
+        const message = String(obj.message);
+        const line = extractScriptLine(obj);
+        return line === undefined ? message : `${message} (script line ${line})`;
+    }
+    return String(value);
+}
+/** Maps a QuickJS error location back onto the raw script's line numbering. */
+function extractScriptLine(obj) {
+    if (typeof obj.lineNumber === "number" && Number.isFinite(obj.lineNumber)) {
+        return Math.max(1, obj.lineNumber - WRAPPER_LINE_OFFSET);
+    }
+    if (typeof obj.stack === "string") {
+        const match = obj.stack.match(/workflow\.js:(\d+)/);
+        if (match)
+            return Math.max(1, Number(match[1]) - WRAPPER_LINE_OFFSET);
+    }
+    return undefined;
+}

package/dist/agent/worktree.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Git worktree isolation for write-capable subagents (design doc §8).
+ *
+ * The child works in a runtime-allocated worktree — the parent's working
+ * tree is never touched. Unchanged worktrees are removed automatically;
+ * changed-but-unapplied ones are kept for the user to inspect.
+ */
+export interface SubagentWorktree {
+    /** Absolute path of the isolated checkout the child works in. */
+    path: string;
+    /** Main repository root the worktree was created from. */
+    repoRoot: string;
+    /** Set at finalization: whether the child left any changes behind. */
+    changed?: boolean;
+    /** Set at finalization: `git diff --stat`-style summary of the changes. */
+    diffStat?: string;
+    /** Set when the unchanged worktree was removed at finalization. */
+    removed?: boolean;
+}
+/**
+ * Allocates a detached worktree at the current HEAD. The path is chosen by
+ * the runtime — the child cannot pick it (design §11).
+ */
+export declare function createSubagentWorktree(repoCwd: string, agentId: string): SubagentWorktree;
+/**
+ * Inspects and cleans up a worktree when its child reaches a final state:
+ * no changes → remove; changes → keep for parent review, report a diff stat.
+ */
+export declare function finalizeSubagentWorktree(worktree: SubagentWorktree): SubagentWorktree;

package/dist/agent/worktree.js

@@ -0,0 +1,73 @@
+/**
+ * Git worktree isolation for write-capable subagents (design doc §8).
+ *
+ * The child works in a runtime-allocated worktree — the parent's working
+ * tree is never touched. Unchanged worktrees are removed automatically;
+ * changed-but-unapplied ones are kept for the user to inspect.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function git(cwd, args) {
+    return execFileSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 30_000,
+    });
+}
+/**
+ * Allocates a detached worktree at the current HEAD. The path is chosen by
+ * the runtime — the child cannot pick it (design §11).
+ */
+export function createSubagentWorktree(repoCwd, agentId) {
+    let repoRoot;
+    try {
+        repoRoot = git(repoCwd, ["rev-parse", "--show-toplevel"]).trim();
+    }
+    catch {
+        throw new Error("write_worktree subagents need a git repository: the working directory is not inside one.");
+    }
+    const dir = mkdtempSync(join(tmpdir(), `bubble-wt-${agentId.slice(0, 8)}-`));
+    try {
+        git(repoRoot, ["worktree", "add", "--detach", dir, "HEAD"]);
+    }
+    catch (error) {
+        rmSync(dir, { recursive: true, force: true });
+        throw new Error(`Failed to create subagent worktree: ${error?.message || String(error)}`);
+    }
+    return { path: dir, repoRoot };
+}
+/**
+ * Inspects and cleans up a worktree when its child reaches a final state:
+ * no changes → remove; changes → keep for parent review, report a diff stat.
+ */
+export function finalizeSubagentWorktree(worktree) {
+    if (worktree.changed !== undefined)
+        return worktree; // already finalized
+    let porcelain = "";
+    let diffStat = "";
+    try {
+        porcelain = git(worktree.path, ["status", "--porcelain"]).trim();
+        diffStat = git(worktree.path, ["diff", "HEAD", "--stat"]).trim();
+    }
+    catch {
+        // If the worktree vanished, treat it as unchanged.
+    }
+    const untracked = porcelain
+        .split("\n")
+        .filter((line) => line.startsWith("??"))
+        .map((line) => `  new file: ${line.slice(3)}`);
+    worktree.changed = porcelain.length > 0;
+    worktree.diffStat = [diffStat, ...untracked].filter(Boolean).join("\n") || undefined;
+    if (!worktree.changed) {
+        try {
+            git(worktree.repoRoot, ["worktree", "remove", "--force", worktree.path]);
+            worktree.removed = true;
+        }
+        catch {
+            worktree.removed = false;
+        }
+    }
+    return worktree;
+}