@bubblebrain-ai/bubble 0.0.21 → 0.0.22

package/dist/agent/result-integrator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ResultIntegrator — turns background child completions into ingestion
+ * notices injected before the parent's next inference turn (design doc §5).
+ *
+ * Injection marks the child as delivered (§3.3), so the lifecycle reminder
+ * demotes it to a one-liner and the same summary never appears twice in full
+ * form in the parent transcript.
+ */
+import type { SubagentThreadRecord } from "./subagent-control.js";
+import type { SubagentStore } from "./subagent-store.js";
+export declare class ResultIntegrator {
+    private readonly pending;
+    enqueue(agentId: string): void;
+    hasPending(): boolean;
+    /**
+     * Builds notices for children whose results have not yet reached parent
+     * context, marking them delivered. Already-delivered children (e.g. the
+     * model wait_agent-ed first) are skipped silently.
+     */
+    drainNotices(store: SubagentStore, now?: number): string[];
+}
+export declare function buildIngestionNotice(record: SubagentThreadRecord): string;

package/dist/agent/result-integrator.js

@@ -0,0 +1,50 @@
+/**
+ * ResultIntegrator — turns background child completions into ingestion
+ * notices injected before the parent's next inference turn (design doc §5).
+ *
+ * Injection marks the child as delivered (§3.3), so the lifecycle reminder
+ * demotes it to a one-liner and the same summary never appears twice in full
+ * form in the parent transcript.
+ */
+import { fenceChildOutput } from "./subagent-summary.js";
+export class ResultIntegrator {
+    pending = [];
+    enqueue(agentId) {
+        if (!this.pending.includes(agentId)) {
+            this.pending.push(agentId);
+        }
+    }
+    hasPending() {
+        return this.pending.length > 0;
+    }
+    /**
+     * Builds notices for children whose results have not yet reached parent
+     * context, marking them delivered. Already-delivered children (e.g. the
+     * model wait_agent-ed first) are skipped silently.
+     */
+    drainNotices(store, now = Date.now()) {
+        const ids = this.pending.splice(0, this.pending.length);
+        const notices = [];
+        for (const id of ids) {
+            const record = store.get(id);
+            if (!record || record.deliveredAt !== undefined)
+                continue;
+            notices.push(buildIngestionNotice(record));
+            store.markDelivered(id, now);
+        }
+        return notices;
+    }
+}
+export function buildIngestionNotice(record) {
+    const lines = [
+        `subagent ${record.nickname} (agent_id: ${record.agentId}) ${record.status}.`,
+    ];
+    if (record.error) {
+        lines.push(`error: ${record.error}`);
+    }
+    if (record.summary) {
+        lines.push(fenceChildOutput(record.summary));
+    }
+    lines.push("Full result via wait_agent. Do not redo this delegated work.");
+    return lines.join("\n");
+}

package/dist/agent/subagent-control.d.ts

@@ -1,7 +1,24 @@
 import type { AgentProfile, AgentProfileSource, SubagentRunResult } from "./profiles.js";
 import type { ResolvedSubagentRoute } from "./categories.js";
+import type { SubagentWorktree } from "./worktree.js";
 import type { AgentEvent, ContentPart, Message, ToolUpdate } from "../types.js";
 export type SubagentThreadStatus = "queued" | "running" | "completed" | "failed" | "blocked" | "cancelled" | "closed";
+/**
+ * Why a child run ended. Drives the `resumable` flag and the guidance line
+ * rendered in lifecycle tool replies (design doc §3.1) — a resume hint is
+ * emitted iff the runtime judged the run resumable, never as a blanket string.
+ */
+export type SubagentFinalReason = "completed" | "failed_transient" | "failed_fatal" | "rate_limited_exhausted" | "blocked" | "cancelled_interrupt" | "cancelled_user" | "cancelled_budget" | "cancelled_parent_abort";
+export declare function isResumableReason(reason: SubagentFinalReason): boolean;
+/** Per-child token budget, fixed at dispatch time (design doc §6). */
+export interface SubagentTokenCap {
+    /** Soft cap: crossing it injects a wrap-up reminder into the child. */
+    soft: number;
+    /** Hard cap: crossing it aborts this child only. Updated at turn checks. */
+    hard: number;
+    /** Ledger tokens already attributed to this child when the run started. */
+    baseline: number;
+}
 export interface SubagentThreadSnapshot {
     agentId: string;
     runId: string;
@@ -11,6 +28,8 @@ export interface SubagentThreadSnapshot {
     category?: string;
     route?: ResolvedSubagentRoute;
     status: SubagentThreadStatus;
+    finalReason?: SubagentFinalReason;
+    resumable?: boolean;
     task: string;
     summary: string;
     toolNotes: string[];
@@ -18,6 +37,12 @@ export interface SubagentThreadSnapshot {
     error?: string;
     createdAt: number;
     updatedAt: number;
+    deliveredAt?: number;
+    /** 1-based position in the scheduler queue while status is "queued". */
+    queuePosition?: number;
+    tokenCap?: SubagentTokenCap;
+    /** Present for write_worktree children: where the isolated checkout lives. */
+    worktree?: SubagentWorktree;
 }
 export interface SubagentThreadRecord {
     agentId: string;
@@ -29,6 +54,7 @@ export interface SubagentThreadRecord {
     parentToolCallId: string;
     parentToolName: string;
     status: SubagentThreadStatus;
+    finalReason?: SubagentFinalReason;
     task: string;
     summary: string;
     toolNotes: string[];
@@ -36,6 +62,9 @@ export interface SubagentThreadRecord {
     error?: string;
     createdAt: number;
     updatedAt: number;
+    deliveredAt?: number;
+    tokenCap?: SubagentTokenCap;
+    worktree?: SubagentWorktree;
     abortController: AbortController;
     waiters: Set<() => void>;
     agent?: {
@@ -43,6 +72,7 @@ export interface SubagentThreadRecord {
         injectSystemReminder(content: string): void;
         run(input: string | ContentPart[], cwd: string, options?: {
             abortSignal?: AbortSignal;
+            resumeWithoutInput?: boolean;
         }): AsyncIterable<AgentEvent>;
     };
     messages?: Message[];
@@ -55,3 +85,4 @@ export interface PendingSubagentToolUpdate {
 }
 export declare function snapshotSubagentThread(record: SubagentThreadRecord): SubagentThreadSnapshot;
 export declare function subagentResultFromThread(record: SubagentThreadRecord): SubagentRunResult;
+export declare function isFinalSubagentThreadStatus(status: SubagentThreadStatus): boolean;

package/dist/agent/subagent-control.js

@@ -1,3 +1,18 @@
+export function isResumableReason(reason) {
+    switch (reason) {
+        case "failed_transient":
+        case "rate_limited_exhausted":
+        case "cancelled_interrupt":
+        case "cancelled_user":
+        case "cancelled_parent_abort":
+            return true;
+        case "completed":
+        case "failed_fatal":
+        case "blocked":
+        case "cancelled_budget":
+            return false;
+    }
+}
 export function snapshotSubagentThread(record) {
     return {
         agentId: record.agentId,
@@ -8,6 +23,8 @@ export function snapshotSubagentThread(record) {
         category: record.category,
         route: record.route,
         status: record.status,
+        finalReason: record.finalReason,
+        resumable: record.finalReason !== undefined ? isResumableReason(record.finalReason) : undefined,
         task: record.task,
         summary: record.summary,
         toolNotes: [...record.toolNotes],
@@ -15,6 +32,9 @@ export function snapshotSubagentThread(record) {
         error: record.error,
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
+        deliveredAt: record.deliveredAt,
+        tokenCap: record.tokenCap ? { ...record.tokenCap } : undefined,
+        worktree: record.worktree ? { ...record.worktree } : undefined,
     };
 }
 export function subagentResultFromThread(record) {
@@ -40,3 +60,10 @@ export function subagentResultFromThread(record) {
         error: record.error,
     };
 }
+export function isFinalSubagentThreadStatus(status) {
+    return status === "completed"
+        || status === "failed"
+        || status === "blocked"
+        || status === "cancelled"
+        || status === "closed";
+}

package/dist/agent/subagent-lifecycle-reminder.js

@@ -1,6 +1,11 @@
+const FINAL_STATUSES = new Set(["completed", "failed", "blocked", "cancelled", "closed"]);
 const STATUS_ORDER = ["queued", "running", "completed", "blocked", "failed", "cancelled", "closed"];
 export function buildSubagentLifecycleReminder(snapshots, toolResults) {
-    const subagents = collectUniqueSubagents(snapshots, toolResults);
+    // Closed children whose result already reached parent context carry no
+    // remaining information — pruning them keeps the reminder from growing by
+    // one line per finished child forever (design §3.3).
+    const subagents = collectUniqueSubagents(snapshots, toolResults)
+        .filter((subagent) => !(subagent.status === "closed" && subagent.delivered));
     if (subagents.length === 0)
         return undefined;
     const counts = statusCounts(subagents);
@@ -37,6 +42,7 @@ function collectUniqueSubagents(snapshots, toolResults) {
             status: snapshot.status,
             summary: snapshot.summary,
             error: snapshot.error,
+            delivered: snapshot.deliveredAt !== undefined,
         });
     }
     return [...byId.values()].sort((a, b) => a.agentId.localeCompare(b.agentId));
@@ -87,7 +93,10 @@ function formatSubagentLine(subagent) {
     const label = subagent.nickname || subagent.agentName || subagent.agentId;
     const role = [subagent.agentName, subagent.category ? `/${subagent.category}` : ""].join("") || "default";
     const status = subagent.status || "unknown";
-    const note = subagent.error || subagent.summary;
+    // A delivered final result already reached parent context in full — repeat
+    // only the id and status, never the summary again (design §3.3).
+    const demoted = subagent.delivered && !!subagent.status && FINAL_STATUSES.has(subagent.status);
+    const note = demoted ? undefined : subagent.error || subagent.summary;
     const suffix = note ? `; note=${truncateForReminder(oneLine(note))}` : "";
     return `  - ${label} (${role}) agent_id=${subagent.agentId} status=${status}${suffix}`;
 }

package/dist/agent/subagent-scheduler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SubagentScheduler — the single dispatch point for child runs.
+ *
+ * Every code path that starts or restarts a child thread (spawn_agent,
+ * send_input restarts, team members, rate-limit retries) submits a
+ * DispatchRequest here; nothing calls the thread runner directly
+ * (design doc §4). Responsibilities:
+ *
+ * - admission queueing with a global active cap and per-category caps,
+ *   released eligibility-FIFO (a blocked queue head never starves entries of
+ *   other categories, §4.3);
+ * - launch-rate throttling: an initial burst starts immediately, further
+ *   launches are spaced out — this throttles launch *rate*, not concurrency;
+ * - queued-entry cancellation: aborting a queued entry removes it atomically
+ *   and never consumes a slot (§4.4);
+ * - rate-limit retry: a run that reports `rate_limited` keeps its agent
+ *   instance, re-enters the queue after a backoff honoring retryAfterMs, and
+ *   the scheduler is the only 429 backoff layer (§4.5);
+ * - AIMD capacity: each 429 shrinks effective global capacity by 1 (min 1, at
+ *   most once per window), a quiet period grows it back (§4.5).
+ */
+export type SubagentRunOutcome = {
+    kind: "final";
+} | {
+    kind: "rate_limited";
+    retryAfterMs?: number;
+};
+export interface DispatchRequest {
+    agentId: string;
+    category?: string;
+    /** Composed abort signal (parent ∪ child controller ∪ budget). */
+    signal?: AbortSignal;
+    /** Runs the child thread. attempt is 1-based; >1 means rate-limit re-entry. */
+    run: (ctx: {
+        attempt: number;
+    }) => Promise<SubagentRunOutcome>;
+    /** Finalize the record when the entry is aborted while still queued. */
+    onCancelledWhileQueued: (reason: unknown) => void;
+    /** Finalize the record when rate-limit retries are exhausted. */
+    onRateLimitExhausted: (attempts: number) => void;
+}
+export interface SubagentSchedulerOptions {
+    maxActiveSubagents?: number;
+    /** Per-category concurrency limits; undefined means no category cap. */
+    getCategoryLimit?: (category: string) => number | undefined;
+    /** Number of immediate launches before rate spacing applies. Default 4. */
+    launchBurst?: number;
+    /** Minimum spacing between launches beyond the burst. Default 500ms (0 under NODE_ENV=test). */
+    launchIntervalMs?: number;
+    rateLimitMaxAttempts?: number;
+    /** Backoff per attempt when the provider gave no retry-after. Default 3s/6s/12s (0 under NODE_ENV=test). */
+    rateLimitBackoffMs?: number[];
+    /** AIMD: minimum spacing between capacity decreases. Default 2s. */
+    aimdDecreaseIntervalMs?: number;
+    /** AIMD: quiet period after which capacity grows by 1. Default 3min. */
+    aimdIncreaseAfterMs?: number;
+    now?: () => number;
+}
+export declare class SubagentScheduler {
+    private readonly queue;
+    private readonly activeIds;
+    private readonly activeByCategory;
+    private readonly maxActive;
+    private readonly getCategoryLimit;
+    private readonly launchBurst;
+    private readonly launchIntervalMs;
+    private readonly rateLimitMaxAttempts;
+    private readonly rateLimitBackoffMs;
+    private readonly aimdDecreaseIntervalMs;
+    private readonly aimdIncreaseAfterMs;
+    private readonly now;
+    private burstRemaining;
+    private nextLaunchAt;
+    private aimdCapacity;
+    private lastCapacityDecreaseAt;
+    private lastRateLimitAt;
+    private pumpTimer;
+    constructor(options?: SubagentSchedulerOptions);
+    /** Resolves when the child run reaches a final state (or queue cancellation). */
+    dispatch(request: DispatchRequest): Promise<void>;
+    queuePosition(agentId: string): number | undefined;
+    activeCount(): number;
+    queuedCount(): number;
+    /** Effective global concurrency cap, AIMD-adjusted. */
+    effectiveCapacity(): number;
+    private cancelQueuedEntry;
+    private maybeGrowCapacity;
+    private notifyRateLimited;
+    private eligible;
+    private pump;
+    private scheduleWakeup;
+    private launch;
+    private releaseSlot;
+    private settle;
+}

package/dist/agent/subagent-scheduler.js

@@ -0,0 +1,256 @@
+/**
+ * SubagentScheduler — the single dispatch point for child runs.
+ *
+ * Every code path that starts or restarts a child thread (spawn_agent,
+ * send_input restarts, team members, rate-limit retries) submits a
+ * DispatchRequest here; nothing calls the thread runner directly
+ * (design doc §4). Responsibilities:
+ *
+ * - admission queueing with a global active cap and per-category caps,
+ *   released eligibility-FIFO (a blocked queue head never starves entries of
+ *   other categories, §4.3);
+ * - launch-rate throttling: an initial burst starts immediately, further
+ *   launches are spaced out — this throttles launch *rate*, not concurrency;
+ * - queued-entry cancellation: aborting a queued entry removes it atomically
+ *   and never consumes a slot (§4.4);
+ * - rate-limit retry: a run that reports `rate_limited` keeps its agent
+ *   instance, re-enters the queue after a backoff honoring retryAfterMs, and
+ *   the scheduler is the only 429 backoff layer (§4.5);
+ * - AIMD capacity: each 429 shrinks effective global capacity by 1 (min 1, at
+ *   most once per window), a quiet period grows it back (§4.5).
+ */
+const TEST_ENV = process.env.NODE_ENV === "test";
+export class SubagentScheduler {
+    queue = [];
+    activeIds = new Set();
+    activeByCategory = new Map();
+    maxActive;
+    getCategoryLimit;
+    launchBurst;
+    launchIntervalMs;
+    rateLimitMaxAttempts;
+    rateLimitBackoffMs;
+    aimdDecreaseIntervalMs;
+    aimdIncreaseAfterMs;
+    now;
+    burstRemaining;
+    nextLaunchAt = 0;
+    aimdCapacity = null;
+    lastCapacityDecreaseAt = 0;
+    lastRateLimitAt = 0;
+    pumpTimer;
+    constructor(options = {}) {
+        this.maxActive = Math.max(1, options.maxActiveSubagents ?? 8);
+        this.getCategoryLimit = options.getCategoryLimit ?? (() => undefined);
+        this.launchBurst = Math.max(1, options.launchBurst ?? 4);
+        this.launchIntervalMs = options.launchIntervalMs ?? (TEST_ENV ? 0 : 500);
+        this.rateLimitMaxAttempts = Math.max(1, options.rateLimitMaxAttempts ?? 3);
+        this.rateLimitBackoffMs = options.rateLimitBackoffMs ?? (TEST_ENV ? [0, 0, 0] : [3_000, 6_000, 12_000]);
+        this.aimdDecreaseIntervalMs = options.aimdDecreaseIntervalMs ?? 2_000;
+        this.aimdIncreaseAfterMs = options.aimdIncreaseAfterMs ?? 180_000;
+        this.now = options.now ?? Date.now;
+        this.burstRemaining = this.launchBurst;
+    }
+    /** Resolves when the child run reaches a final state (or queue cancellation). */
+    dispatch(request) {
+        return new Promise((resolve) => {
+            const entry = {
+                request,
+                attempt: 0,
+                notBefore: 0,
+                resolve,
+            };
+            if (request.signal) {
+                if (request.signal.aborted) {
+                    request.onCancelledWhileQueued(request.signal.reason);
+                    resolve();
+                    return;
+                }
+                const onAbort = () => this.cancelQueuedEntry(entry, request.signal?.reason);
+                request.signal.addEventListener("abort", onAbort, { once: true });
+                entry.removeAbortListener = () => request.signal?.removeEventListener("abort", onAbort);
+            }
+            this.queue.push(entry);
+            this.pump();
+        });
+    }
+    queuePosition(agentId) {
+        const index = this.queue.findIndex((entry) => entry.request.agentId === agentId);
+        return index >= 0 ? index + 1 : undefined;
+    }
+    activeCount() {
+        return this.activeIds.size;
+    }
+    queuedCount() {
+        return this.queue.length;
+    }
+    /** Effective global concurrency cap, AIMD-adjusted. */
+    effectiveCapacity() {
+        return this.aimdCapacity !== null ? Math.min(this.aimdCapacity, this.maxActive) : this.maxActive;
+    }
+    cancelQueuedEntry(entry, reason) {
+        const index = this.queue.indexOf(entry);
+        if (index < 0)
+            return; // already launched; the run's own signal handles it
+        this.queue.splice(index, 1);
+        entry.removeAbortListener?.();
+        entry.request.onCancelledWhileQueued(reason);
+        entry.resolve();
+        this.pump();
+    }
+    maybeGrowCapacity(now) {
+        if (this.aimdCapacity === null)
+            return;
+        if (now - this.lastRateLimitAt < this.aimdIncreaseAfterMs)
+            return;
+        this.aimdCapacity += 1;
+        this.lastRateLimitAt = now; // next increase needs another quiet window
+        if (this.aimdCapacity >= this.maxActive) {
+            this.aimdCapacity = null;
+        }
+    }
+    notifyRateLimited(now) {
+        if (this.aimdCapacity === null) {
+            this.aimdCapacity = Math.max(1, this.activeIds.size);
+            this.lastCapacityDecreaseAt = now;
+        }
+        else if (now - this.lastCapacityDecreaseAt >= this.aimdDecreaseIntervalMs) {
+            this.aimdCapacity = Math.max(1, this.aimdCapacity - 1);
+            this.lastCapacityDecreaseAt = now;
+        }
+        this.lastRateLimitAt = now;
+    }
+    eligible(entry, now) {
+        if (entry.notBefore > now)
+            return false;
+        if (this.activeIds.size >= this.effectiveCapacity())
+            return false;
+        const category = entry.request.category;
+        if (category) {
+            const limit = this.getCategoryLimit(category);
+            if (limit !== undefined && (this.activeByCategory.get(category) ?? 0) >= limit) {
+                return false;
+            }
+        }
+        return true;
+    }
+    pump() {
+        const now = this.now();
+        this.maybeGrowCapacity(now);
+        while (true) {
+            if (this.queue.length === 0) {
+                if (this.activeIds.size === 0) {
+                    this.burstRemaining = this.launchBurst;
+                }
+                return;
+            }
+            // Eligibility-FIFO: first entry that satisfies both the global and its
+            // category limit launches; a capacity-blocked head does not starve the rest.
+            const entry = this.queue.find((candidate) => this.eligible(candidate, now));
+            if (!entry) {
+                this.scheduleWakeup(now);
+                return;
+            }
+            // Launch-rate throttle (burst, then spacing).
+            if (this.burstRemaining > 0) {
+                this.burstRemaining -= 1;
+            }
+            else if (now >= this.nextLaunchAt) {
+                this.nextLaunchAt = now + this.launchIntervalMs;
+            }
+            else {
+                this.scheduleWakeup(now, this.nextLaunchAt);
+                return;
+            }
+            this.launch(entry);
+        }
+    }
+    scheduleWakeup(now, explicitAt) {
+        const candidates = [];
+        if (explicitAt !== undefined)
+            candidates.push(explicitAt);
+        for (const entry of this.queue) {
+            if (entry.notBefore > now)
+                candidates.push(entry.notBefore);
+        }
+        if (this.aimdCapacity !== null) {
+            candidates.push(this.lastRateLimitAt + this.aimdIncreaseAfterMs);
+        }
+        if (candidates.length === 0)
+            return; // a slot release will pump
+        const at = Math.min(...candidates);
+        const delay = Math.max(1, at - now);
+        if (this.pumpTimer)
+            clearTimeout(this.pumpTimer);
+        this.pumpTimer = setTimeout(() => {
+            this.pumpTimer = undefined;
+            this.pump();
+        }, delay);
+        if (typeof this.pumpTimer === "object" && "unref" in this.pumpTimer) {
+            this.pumpTimer.unref();
+        }
+    }
+    launch(entry) {
+        const index = this.queue.indexOf(entry);
+        if (index >= 0)
+            this.queue.splice(index, 1);
+        entry.removeAbortListener?.();
+        entry.removeAbortListener = undefined;
+        const { request } = entry;
+        this.activeIds.add(request.agentId);
+        if (request.category) {
+            this.activeByCategory.set(request.category, (this.activeByCategory.get(request.category) ?? 0) + 1);
+        }
+        entry.attempt += 1;
+        void request
+            .run({ attempt: entry.attempt })
+            .then((outcome) => this.settle(entry, outcome))
+            .catch(() => this.settle(entry, { kind: "final" }))
+            .finally(() => {
+            // Slot release lives here so every exit path — completion, failure,
+            // cancellation, thrown errors, early returns inside the runner —
+            // releases exactly once before the next pump.
+            this.releaseSlot(request);
+            this.pump();
+        });
+    }
+    releaseSlot(request) {
+        this.activeIds.delete(request.agentId);
+        if (request.category) {
+            const current = this.activeByCategory.get(request.category) ?? 0;
+            if (current <= 1)
+                this.activeByCategory.delete(request.category);
+            else
+                this.activeByCategory.set(request.category, current - 1);
+        }
+    }
+    settle(entry, outcome) {
+        if (outcome.kind === "final") {
+            entry.resolve();
+            return;
+        }
+        const now = this.now();
+        this.notifyRateLimited(now);
+        if (entry.attempt >= this.rateLimitMaxAttempts) {
+            entry.request.onRateLimitExhausted(entry.attempt);
+            entry.resolve();
+            return;
+        }
+        if (entry.request.signal?.aborted) {
+            entry.request.onCancelledWhileQueued(entry.request.signal.reason);
+            entry.resolve();
+            return;
+        }
+        const backoff = outcome.retryAfterMs
+            ?? this.rateLimitBackoffMs[Math.min(entry.attempt - 1, this.rateLimitBackoffMs.length - 1)]
+            ?? 0;
+        entry.notBefore = now + Math.max(0, backoff);
+        if (entry.request.signal) {
+            const onAbort = () => this.cancelQueuedEntry(entry, entry.request.signal?.reason);
+            entry.request.signal.addEventListener("abort", onAbort, { once: true });
+            entry.removeAbortListener = () => entry.request.signal?.removeEventListener("abort", onAbort);
+        }
+        this.queue.push(entry);
+        // Re-entries skip the burst accounting; spacing alone applies.
+    }
+}

package/dist/agent/subagent-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SubagentStore — single source of truth for child thread state.
+ *
+ * `list_agents`, the lifecycle reminder, TUI metadata, and persistence all
+ * read from this store; there is never a second copy of state (design §2).
+ *
+ * Persistence (design §7): final-state children are written to
+ * `<persistDir>/<agentId>.json` as snapshot + compacted message history, so a
+ * later process can resume them via send_input. The on-disk schema carries
+ * `finalReason` / `resumable` / `deliveredAt` / `tokenCap` — the fields the
+ * reply protocol and delivery dedup depend on. Child transcripts never mix
+ * into the parent transcript.
+ */
+import { type SubagentThreadRecord, type SubagentThreadStatus } from "./subagent-control.js";
+export declare class SubagentStore {
+    private readonly persistDir?;
+    private readonly threads;
+    constructor(persistDir?: string | undefined);
+    get(agentId: string): SubagentThreadRecord | undefined;
+    set(record: SubagentThreadRecord): void;
+    values(): SubagentThreadRecord[];
+    active(): SubagentThreadRecord[];
+    activeCount(): number;
+    byStatus(status: SubagentThreadStatus): SubagentThreadRecord[];
+    /**
+     * Marks the moment a child's full summary first reached parent context
+     * (via a wait_agent reply or an ingestion notice). Used to deduplicate the
+     * three delivery channels (design §3.3). Idempotent.
+     */
+    markDelivered(agentId: string, at?: number): void;
+    notifyWaiters(record: SubagentThreadRecord): void;
+    /** Writes a final-state child to disk so a later process can resume it. */
+    persist(record: SubagentThreadRecord): void;
+    /**
+     * Loads previously persisted children. Records come back in their final
+     * state with the child history staged on `record.messages`; the next
+     * dispatch rebuilds an Agent instance from it (cross-restart resume, §7).
+     * In-memory records always win over disk.
+     */
+    loadPersisted(): void;
+}