@bubblebrain-ai/bubble 0.0.21 → 0.0.23

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;
+}

package/dist/agent.d.ts

@@ -10,11 +10,24 @@ import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "./agent/
 import { BudgetLedger } from "./agent/budget-ledger.js";
 import { type AgentProfile, type SubagentRunResult } from "./agent/profiles.js";
 import { type SubagentThreadSnapshot } from "./agent/subagent-control.js";
+import { type RateLimitPolicy } from "./network/errors.js";
 import type { SkillSummary } from "./skills/types.js";
 import type { FileStateTracker } from "./tools/file-state.js";
+export { AgentAbortError, SubagentAbortError } from "./agent/abort-errors.js";
 export declare const INTERRUPTED_ASSISTANT_CONTENT = "Interrupted by user. The prior request was stopped and should not be resumed unless the user asks.";
-export declare class AgentAbortError extends Error {
-    constructor(message?: string);
+/** Runtime tuning for the subagent scheduler and per-child budgets. */
+export interface AgentSubagentRuntimeConfig {
+    maxActiveSubagents?: number;
+    childTokenCap?: number;
+    launchBurst?: number;
+    launchIntervalMs?: number;
+    rateLimitMaxAttempts?: number;
+    rateLimitBackoffMs?: number[];
+    /**
+     * Directory for persisted child state (design §7). Defaults to
+     * `<session>.subagents` next to the session file when a session exists.
+     */
+    persistDir?: string;
 }
 export interface AgentOptions {
     provider: Provider;
@@ -50,10 +63,19 @@ export interface AgentOptions {
     fileStateTracker?: FileStateTracker;
     agentCategories?: AgentCategoriesConfig;
     providerFactory?: (route: ResolvedSubagentRoute) => Provider | Promise<Provider>;
+    subagents?: AgentSubagentRuntimeConfig;
+    /** Subagent routes use "defer" so the scheduler is the single 429 backoff layer (design §4.5). */
+    rateLimitPolicy?: RateLimitPolicy;
 }
 export interface AgentRunOptions {
     abortSignal?: AbortSignal;
     inputController?: AgentInputController;
+    /**
+     * Internal: re-enter the loop without appending the input as a new user
+     * message. Used by the subagent scheduler's rate-limit re-entry so a child
+     * history contains exactly one copy of its input (design doc §4.5).
+     */
+    resumeWithoutInput?: boolean;
 }
 export declare class Agent {
     messages: Message[];
@@ -86,13 +108,20 @@ export declare class Agent {
     private fileStateTracker?;
     private agentCategories;
     private providerFactory?;
-    private subagentThreads;
+    private readonly subagentStore;
+    private readonly subagentScheduler;
+    private readonly childRunner;
+    private readonly resultIntegrator;
+    private subagentsConfig;
+    private readonly rateLimitPolicy?;
     private pendingSubagentUpdates;
     private lastInputTokens;
     private lastAnchorMessageCount;
     constructor(options: AgentOptions);
     private runExternalHook;
     private injectHookModelContext;
+    /** Whether a tool is registered on this agent (e.g. delegation tools on parents). */
+    hasToolAvailable(name: string): boolean;
     /** Unlock a list of deferred tools so they're included in subsequent turns. */
     unlockDeferredTools(names: string[]): void;
     /** All deferred tools in this session (for tool_search to inspect). */
@@ -174,10 +203,40 @@ export declare class Agent {
     }): Promise<SubagentThreadSnapshot>;
     closeSubAgent(agentId: string): Promise<SubagentThreadSnapshot>;
     listSubAgents(): SubagentThreadSnapshot[];
+    /**
+     * Homogeneous map fan-out (design §1.2): one profile, one template, N items.
+     * Every member goes through the same admission and the same scheduler
+     * dispatch as spawn_agent; the tool blocks until all members are final.
+     */
+    runAgentTeam(cwd: string, options: {
+        profile: AgentProfile;
+        category?: string;
+        promptTemplate: string;
+        items: string[];
+        parentToolCallId: string;
+        emitUpdate?: (update: ToolUpdate) => void;
+        abortSignal?: AbortSignal;
+        approval?: "fail" | "disabled";
+    }): Promise<SubagentThreadSnapshot[]>;
+    /** Marks a child's full summary as delivered to parent context (design §3.3). */
+    markSubagentDelivered(agentId: string): void;
+    private snapshotSubagent;
+    /** Returns the blocking diagnostic message when the profile cannot run, else undefined. */
+    private admitSubagentProfile;
+    /**
+     * Background children (queueUpdates) get their results ingested before the
+     * parent's next inference turn (design §5); foreground children (team,
+     * legacy task) deliver through their tool result instead.
+     */
+    private maybeEnqueueIngestion;
+    private flushSubagentIngestions;
+    private finalizeSubagentBlocked;
+    private dispatchSubagentRun;
+    private emitSubagentLifecycle;
+    private runSubagentLifecycleHookFor;
     private resolveRouteForSubagent;
     private createSubagentThreadRecord;
     private runSubagentThread;
-    private runSubagentFinalSummaryTurn;
     private createSubAgentInstance;
     private resolveProviderForRoute;
     private forkMessagesForSubagent;
@@ -186,7 +245,6 @@ export declare class Agent {
     private drainSubagentToolUpdates;
     private activeSubagentNicknames;
     private resolveSubagentTargets;
-    private notifySubagentWaiters;
     private maybeCompactResidentHistory;
     private appendMessage;
     private appendInterruptedAssistantBoundary;