@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/agent/subagent/runtime.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Subagent thread lifecycle + dynamic-workflow execution.
+ *
+ * Extracted from Agent: spawn/wait/send/close, the scheduler dispatch and its
+ * terminal callbacks, admission, ingestion, worktree-backed child construction
+ * and the QuickJS workflow driver all lived on the Agent class alongside the
+ * conversation loop, sharing its private fields.
+ *
+ * Two rules keep the boundary honest:
+ *  - Everything the runtime needs from the parent arrives through
+ *    `SubagentRuntimeParent` as a LIVE accessor, never a construction-time
+ *    snapshot: `/model` reassigns the parent's provider/model/thinking
+ *    mid-session and children must inherit the current values.
+ *  - Conversation state is never pushed back into the parent. Tool updates
+ *    and ingestion notices are PULLED (`drainToolUpdates` /
+ *    `drainIngestionNotices`). The only direct sink is a terminal,
+ *    fail-closed provider diagnostic that contains no child transcript.
+ *
+ * `new Agent(...)` stays on Agent, reached through `parent.createChild`. That
+ * is the only genuine call back into the parent, and keeping it there is what
+ * guarantees the child-construction argument set — including the fields that
+ * must stay ABSENT (onMessageAppend, sessionID, routing catalog) — has exactly
+ * one definition site.
+ */
+import type { SkillSummary } from "../../skills/types.js";
+import { type AgentProfile, type SubagentRunResult } from "../profiles.js";
+import { type SubagentThreadRecord, type SubagentThreadSnapshot } from "../subagent-control.js";
+import { SubagentStore } from "../subagent-store.js";
+import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "../categories.js";
+import type { SubagentRouter } from "./router.js";
+import type { AgentEvent, ContentPart, Message, PermissionMode, Provider, ThinkingLevel, ToolRegistryEntry, ToolUpdate } from "../../types.js";
+import type { ProviderErrorContext } from "../../provider-error-record.js";
+import type { AgentSubagentRuntimeConfig } from "../../agent.js";
+import type { HookCombinedResult } from "../../hooks/index.js";
+/** The child agent surface the runtime drives; structurally satisfied by Agent. */
+export type ChildAgentLike = NonNullable<SubagentThreadRecord["agent"]>;
+export interface ChildAgentSpec {
+    provider: Provider;
+    providerId: string;
+    model: string;
+    tools: ToolRegistryEntry[];
+    thinkingLevel: ThinkingLevel;
+    mode: PermissionMode;
+    maxTurns?: number;
+    budgetSource: {
+        runId: string;
+        subAgentId?: string;
+    };
+    systemPrompt: string;
+    subAgentId: string;
+    /** Cross-restart resume history (design §7); already detached from the record. */
+    resumeMessages?: Message[];
+    /** Seed the child with the parent's recent context under its own system prompt. */
+    forkContext?: boolean;
+}
+export interface SubagentRuntimeParent {
+    /** LIVE — /model reassigns these mid-session. */
+    readonly provider: Provider;
+    readonly providerId: string;
+    /** API-facing model id, already stripped of any "provider:" prefix. */
+    readonly apiModel: string;
+    readonly thinkingLevel: ThinkingLevel;
+    readonly memoryPrompt: string | undefined;
+    /** Optional so lightweight parents (tests, embedders) need not provide a catalog. */
+    getSkillSummaries?(): SkillSummary[];
+    getSkillCatalogChars?(): number | undefined;
+    readonly providerFactory: ((route: ResolvedSubagentRoute) => Provider | Promise<Provider>) | undefined;
+    /**
+     * The UNFILTERED tool map — deferred-but-unlocked entries included. Profile
+     * admission and child tool selection both depend on seeing every registered
+     * tool; handing them the active (deferred-filtered) list would block
+     * profiles that explicitly include an MCP or otherwise deferred tool.
+     */
+    allTools(): ToolRegistryEntry[];
+    createChild(spec: ChildAgentSpec): ChildAgentLike;
+    recordProviderError(error: unknown, context: ProviderErrorContext): void;
+    runExternalHook(input: {
+        eventName: string;
+        cwd: string;
+        runId?: string;
+        target?: string;
+        payload?: Record<string, unknown>;
+    }, abortSignal?: AbortSignal): Promise<{
+        result: HookCombinedResult;
+        events: AgentEvent[];
+    }>;
+}
+export interface SubagentRuntimeDeps {
+    parent: SubagentRuntimeParent;
+    router: SubagentRouter;
+    categories: AgentCategoriesConfig;
+    config: AgentSubagentRuntimeConfig;
+    /**
+     * Initial persist directory. Session switches repoint it through
+     * `repointPersistDir` (the TUI reuses one Agent across switches).
+     */
+    persistDir?: string;
+}
+export declare class SubagentRuntime {
+    private readonly parent;
+    private readonly router;
+    private readonly categories;
+    private readonly subagentsConfig;
+    /** Public so Agent can expose the same private-field access tests rely on. */
+    readonly store: SubagentStore;
+    private readonly scheduler;
+    private readonly childRunner;
+    private readonly resultIntegrator;
+    private pendingUpdates;
+    private readonly updateWakers;
+    constructor(deps: SubagentRuntimeDeps);
+    /** True when a background child has queued an update the loop should drain. */
+    hasPendingUpdates(): boolean;
+    /** Follows a session switch: evicts the old session's final children and loads the new one's. */
+    repointPersistDir(persistDir: string | undefined): void;
+    /**
+     * Inspects and cleans up a child's worktree at ANY terminal outcome:
+     * unchanged → removed; changed → kept for the parent to review, with a
+     * diff stat in the handoff (§8). Called from ChildRunner's onFinal and
+     * from all three scheduler-terminal callbacks — the scheduler paths used
+     * to skip reclamation entirely, leaking the directory and its git
+     * registration whenever a write child exhausted its retries
+     * (known-defects #1).
+     *
+     * When the directory was removed (= the child left no changes, so there
+     * is no file state to lose), the record's worktree reference is cleared:
+     * a kept reference would send a later resume into a deleted directory —
+     * clearing it makes the resume path rebuild a fresh worktree instead
+     * (see ChildRunner's reuse guard).
+     */
+    private reclaimWorktree;
+    /** Registers a waker so a blocked tool-execution loop learns about updates. */
+    subscribe(wake: () => void): () => void;
+    /**
+     * Completed background children whose summaries should reach parent context
+     * before the next inference turn (design §5). Pulled, not injected.
+     */
+    drainIngestionNotices(): string[];
+    runSubAgent(input: string | ContentPart[], cwd: string, options: {
+        profile: AgentProfile;
+        runId: string;
+        subAgentId: string;
+        parentToolCallId: string;
+        category?: string;
+        route?: ResolvedSubagentRoute;
+        approval?: "fail" | "disabled";
+        emitUpdate?: (update: ToolUpdate) => void;
+        description?: string;
+        abortSignal?: AbortSignal;
+        nickname?: string;
+        forkContext?: boolean;
+    }): Promise<SubagentRunResult>;
+    spawnSubAgent(input: string | ContentPart[], cwd: string, options: {
+        profile: AgentProfile;
+        parentToolCallId: string;
+        category?: string;
+        model?: string;
+        effort?: ThinkingLevel;
+        route?: ResolvedSubagentRoute;
+        approval?: "fail" | "disabled";
+        description?: string;
+        abortSignal?: AbortSignal;
+        forkContext?: boolean;
+    }): Promise<SubagentThreadSnapshot>;
+    waitSubAgents(options?: {
+        agentIds?: string[];
+        timeoutMs?: number;
+    }): Promise<SubagentThreadSnapshot[]>;
+    sendSubAgentInput(agentId: string, input: string | ContentPart[], cwd: string, options?: {
+        interrupt?: boolean;
+        parentToolCallId?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<SubagentThreadSnapshot>;
+    closeSubAgent(agentId: string): Promise<SubagentThreadSnapshot>;
+    /**
+     * Live (non-final) children only — the delegation-nudge gate
+     * (large-task-delegation design §2). listSubAgents() is a grows-only
+     * session history (finished + resumed children stay forever), so it must
+     * never be used to answer "am I currently delegating?".
+     */
+    activeSubAgentCount(): number;
+    listSubAgents(): SubagentThreadSnapshot[];
+    executeWorkflow(cwd: string, options: {
+        script: string;
+        args?: unknown;
+        parentToolCallId: string;
+        abortSignal?: AbortSignal;
+        directEmit?: (update: ToolUpdate) => void;
+        queueUpdates?: boolean;
+        ensureProfileTrusted?: (profile: AgentProfile) => Promise<{
+            content: string | unknown;
+        } | undefined>;
+        workflowRunId?: string;
+    }): Promise<{
+        result: {
+            ok: true;
+            value: unknown;
+        } | {
+            ok: false;
+            error: string;
+        };
+        agentCount: number;
+        logs: string[];
+        snapshots: SubagentThreadSnapshot[];
+    }>;
+    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 finalizeSubagentBlocked;
+    private dispatchSubagentRun;
+    private recordSubagentProviderError;
+    private emitSubagentLifecycle;
+    /** Lets a blocked tool-execution loop drain freshly queued subagent updates. */
+    private wakeSubagentUpdateWaiters;
+    private runSubagentLifecycleHookFor;
+    private createSubagentThreadRecord;
+    private runSubagentThread;
+    private createSubAgentInstance;
+    private resolveProviderForRoute;
+    private buildSubagentUpdate;
+    private queueSubagentUpdate;
+    /** Queued background-child updates for Agent.run() to emit. */
+    drainToolUpdates(): AgentEvent[];
+    private activeSubagentNicknames;
+    private resolveSubagentTargets;
+}
+export declare function isFinalSubagentStatus(status: SubagentThreadRecord["status"]): boolean;
+export declare function normalizeWaitTimeout(value: number | undefined): number;