@bubblebrain-ai/bubble 0.0.28 → 0.0.29

package/dist/agent/workflow/runtime.js

@@ -0,0 +1,237 @@
+/**
+ * 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) => Promise.all((thunks || []).map((t) => {
+  try { return Promise.resolve(t()).catch(() => null); } catch (_e) { return Promise.resolve(null); }
+}));
+globalThis.pipeline = (items, ...stages) => 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;
+delete globalThis.WeakRef;
+delete globalThis.FinalizationRegistry;
+Math.random = () => { throw new Error("Math.random is disabled in workflows (nondeterministic)"); };
+`;
+/** 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");
+}
+export async function runWorkflow(options) {
+    const QuickJS = await getQuickJS();
+    const vm = QuickJS.newContext();
+    const pending = 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);
+        // 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 body = stripExports(options.script);
+        const wrapped = [
+            "globalThis.__wfdone = false; globalThis.__wfresult = null; globalThis.__wferror = null;",
+            "(async () => {",
+            body,
+            "})().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");
+        computeStart = Date.now();
+        const evalResult = vm.evalCode(wrapped);
+        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;
+        vm.dispose();
+    }
+}
+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) {
+    vm.newFunction("__agent", (specHandle) => {
+        const spec = JSON.parse(vm.getString(specHandle));
+        const deferred = vm.newPromise();
+        // 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(() => { 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) {
+        return String(value.message);
+    }
+    return String(value);
+}

package/dist/agent.d.ts

@@ -7,6 +7,7 @@ import type { AgentEvent, AgentInputController, ContentPart, PermissionMode, Mes
 import { type TurnHooks } from "./orchestrator/hooks.js";
 import type { ExternalHookController } from "./hooks/controller.js";
 import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "./agent/categories.js";
+import { type WorkflowRunSnapshot } from "./agent/workflow/control.js";
 import { BudgetLedger } from "./agent/budget-ledger.js";
 import { type AgentProfile, type SubagentRunResult } from "./agent/profiles.js";
 import { type SubagentThreadSnapshot } from "./agent/subagent-control.js";
@@ -23,6 +24,8 @@ export interface AgentSubagentRuntimeConfig {
     launchIntervalMs?: number;
     rateLimitMaxAttempts?: number;
     rateLimitBackoffMs?: number[];
+    transportRetryMaxAttempts?: number;
+    transportRetryBackoffMs?: number[];
     /**
      * Directory for persisted child state (design §7). Defaults to
      * `<session>.subagents` next to the session file when a session exists.
@@ -112,6 +115,10 @@ export declare class Agent {
     private readonly subagentScheduler;
     private readonly childRunner;
     private readonly resultIntegrator;
+    /** Background dynamic-workflow runs (option C Phase 4), keyed by runId. */
+    private readonly workflowRuns;
+    /** runIds whose completed result should be ingested at the next turn. */
+    private readonly pendingWorkflowDeliveries;
     private subagentsConfig;
     private readonly rateLimitPolicy?;
     private pendingSubagentUpdates;
@@ -164,6 +171,17 @@ export declare class Agent {
     private recoverFromOverflow;
     compactResidentHistory(): void;
     private maybeCompactWithLLM;
+    /**
+     * Stream a 9-section handoff summary of `oldMessages` from the session model.
+     * Powers the manual `/compact` command: streaming (rather than `complete()`)
+     * is what lets the TUI show live progress as the summary is produced.
+     *
+     * `onDelta` receives the full accumulated text and the latest delta on each
+     * chunk. Returns the trimmed summary, or "" if the model produced nothing
+     * (the caller falls back to heuristic compaction in that case). Throws only
+     * if the provider stream itself errors.
+     */
+    summarizeForCompaction(oldMessages: Message[], onDelta?: (full: string, delta: string) => void, abortSignal?: AbortSignal): Promise<string>;
     runSubtask(input: string | ContentPart[], cwd: string, options?: {
         subtaskType?: string;
         description?: string;
@@ -186,6 +204,8 @@ export declare class Agent {
         profile: AgentProfile;
         parentToolCallId: string;
         category?: string;
+        model?: string;
+        effort?: ThinkingLevel;
         route?: ResolvedSubagentRoute;
         approval?: "fail" | "disabled";
         description?: string;
@@ -211,6 +231,8 @@ export declare class Agent {
     runAgentTeam(cwd: string, options: {
         profile: AgentProfile;
         category?: string;
+        model?: string;
+        effort?: ThinkingLevel;
         promptTemplate: string;
         items: string[];
         parentToolCallId: string;
@@ -218,6 +240,83 @@ export declare class Agent {
         abortSignal?: AbortSignal;
         approval?: "fail" | "disabled";
     }): Promise<SubagentThreadSnapshot[]>;
+    /**
+     * Heterogeneous fan-out (design v2 §1.3): N independent specs, each with its
+     * own task, profile, and per-call model/effort, dispatched concurrently as a
+     * SINGLE tool call. Unlike runAgentTeam (one template over N items), members
+     * differ. Like the team, every member goes through the same scheduler
+     * dispatch and the tool blocks until all are final, returning in spec order.
+     * Keeping fan-out inside one tool call (rather than N parallel spawn_agent
+     * tool_calls) avoids the provider parallel-tool_call bug (Kimi 400 / lost
+     * responses).
+     */
+    runAgentBatch(cwd: string, options: {
+        specs: Array<{
+            task: string;
+            profile: AgentProfile;
+            category?: string;
+            model?: string;
+            effort?: ThinkingLevel;
+            outputSchema?: unknown;
+        }>;
+        parentToolCallId: string;
+        emitUpdate?: (update: ToolUpdate) => void;
+        abortSignal?: AbortSignal;
+        approval?: "fail" | "disabled";
+    }): Promise<SubagentThreadSnapshot[]>;
+    /**
+     * Dynamic workflow (option C): runs an LLM-authored JS orchestration script in
+     * a QuickJS sandbox. Each agent() call in the script becomes a real scheduled
+     * subagent (same route resolution, ChildRunner, scheduler, schema validation
+     * as spawn_agent), so the script expresses deterministic control flow while
+     * the runtime keeps owning concurrency/budget/retry.
+     *
+     * Foreground entry point (used by `-p`/headless and tests): awaits to
+     * completion and returns the result. Background runs go through startWorkflow.
+     */
+    runWorkflow(cwd: string, options: {
+        script: string;
+        args?: unknown;
+        parentToolCallId: string;
+        emitUpdate?: (update: ToolUpdate) => void;
+        abortSignal?: AbortSignal;
+    }): Promise<{
+        result: {
+            ok: true;
+            value: unknown;
+        } | {
+            ok: false;
+            error: string;
+        };
+        agentCount: number;
+        logs: string[];
+        snapshots: SubagentThreadSnapshot[];
+    }>;
+    /**
+     * Starts a workflow in the BACKGROUND (option C Phase 4): returns a runId
+     * immediately; the script runs detached, its agents stream progress through
+     * the queued channel (drained at turn boundaries like spawn_agent), and its
+     * result is ingested at the next turn. Collect explicitly with waitWorkflow.
+     */
+    startWorkflow(cwd: string, options: {
+        script: string;
+        args?: unknown;
+        title?: string;
+        parentToolCallId: string;
+        abortSignal?: AbortSignal;
+    }): {
+        runId: string;
+        title: string;
+    };
+    /** Blocks until a background workflow reaches a final state (or times out). */
+    waitWorkflow(runId: string, timeoutMs?: number): Promise<WorkflowRunSnapshot | undefined>;
+    /** Cancels a running background workflow. */
+    closeWorkflow(runId: string): WorkflowRunSnapshot | undefined;
+    listWorkflows(): WorkflowRunSnapshot[];
+    private snapshotWorkflow;
+    /** Injects completed background-workflow results before the next turn (§5 analog). */
+    private flushWorkflowDeliveries;
+    private executeWorkflow;
     /** Marks a child's full summary as delivered to parent context (design §3.3). */
     markSubagentDelivered(agentId: string): void;
     private snapshotSubagent;
@@ -234,6 +333,12 @@ export declare class Agent {
     private dispatchSubagentRun;
     private emitSubagentLifecycle;
     private runSubagentLifecycleHookFor;
+    /**
+     * Resolves a child's model route. Priority, highest first (design v2 §1.1):
+     *   call-site override (model/effort)  >  profile.model  >  category  >  inherit parent.
+     * The call-site override is what lets the model say "opus for this reviewer,
+     * haiku for these twenty scouts" per spawn/batch member at request time.
+     */
     private resolveRouteForSubagent;
     private createSubagentThreadRecord;
     private runSubagentThread;