@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/agent.d.ts

@@ -0,0 +1,460 @@
+import { type ContextCheckpoint } from "./context/checkpoint.js";
+import { type ContextUsageSnapshot } from "./context/usage.js";
+import type { AgentEvent, AgentInputController, ContentPart, PermissionMode, Message, Provider, ThinkingLevel, ToolResult, ToolRegistryEntry, ToolUpdate } from "./types.js";
+import { type TurnHooks } from "./orchestrator/hooks.js";
+import type { ExternalHookController } from "./hooks/controller.js";
+import type { AgentCategoriesConfig, ResolvedSubagentRoute } from "./agent/categories.js";
+import { type AgentRoutingConfig, type RoutableModelEntry, type RoutableModelIndex, type RoutingSnapshotAccessor } from "./agent/routing-catalog.js";
+import { SubagentRuntime } from "./agent/subagent/runtime.js";
+import { BudgetLedger } from "./agent/budget-ledger.js";
+import { type WorkflowRunSnapshot } from "./agent/workflow/control.js";
+import type { AgentProfile, SubagentRunResult } from "./agent/profiles.js";
+import type { SubagentThreadSnapshot } from "./agent/subagent-control.js";
+import { SubagentStore } from "./agent/subagent-store.js";
+export { createUpdateQueue } from "./agent/update-queue.js";
+import { type RateLimitPolicy } from "./network/errors.js";
+import type { SkillSummary } from "./skills/types.js";
+import type { FileStateTracker } from "./tools/file-state.js";
+import { type SanitizedProviderError } from "./provider-error-record.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.";
+/** Runtime tuning for the subagent scheduler. */
+export interface AgentSubagentRuntimeConfig {
+    maxActiveSubagents?: number;
+    launchBurst?: number;
+    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.
+     */
+    persistDir?: string;
+}
+export interface AgentOptions {
+    provider: Provider;
+    sessionID?: string;
+    providerId?: string;
+    model: string;
+    tools: ToolRegistryEntry[];
+    temperature?: number;
+    thinkingLevel?: ThinkingLevel;
+    mode?: PermissionMode;
+    steps?: number;
+    maxTurns?: number;
+    taskBudget?: {
+        total: number;
+    };
+    systemPrompt?: string;
+    onMessageAppend?: (message: Message) => void;
+    /** Persistable, allowlisted diagnostics for terminal provider failures. */
+    onProviderError?: (error: SanitizedProviderError) => void;
+    onToolResult?: (toolName: string, result: ToolResult) => void;
+    onModeUpdate?: (mode: PermissionMode) => void;
+    /**
+     * Fired when MULTI-TURN compaction rewrites resident history, with the
+     * summary text. Hosts persist it (SessionManager.applyLLMCompaction) so the
+     * compacted state — including the cumulative file blocks — survives resume;
+     * without this, meta summaries live only in memory (session-log drops meta).
+     * Sub-turn summaries never fire it: they cover only the current turn, and a
+     * session-level summary entry would make resume skip earlier history.
+     */
+    onCompactionApplied?: (summary: string) => void;
+    /** Required durable commit hook for hosts; exceptions abort the context switch. */
+    onContextCheckpoint?: (checkpoint: ContextCheckpoint) => void;
+    getContextRevision?: () => string;
+    hooks?: TurnHooks[];
+    externalHooks?: ExternalHookController;
+    agentRole?: "parent" | "subagent";
+    subAgentId?: string;
+    budgetLedger?: BudgetLedger;
+    budgetSource?: {
+        runId: string;
+        subAgentId?: string;
+    };
+    skills?: SkillSummary[];
+    /** Skill catalog budget in characters for rebuilt system prompts (0 = off). */
+    skillCatalogChars?: number;
+    memoryPrompt?: string;
+    fileStateTracker?: FileStateTracker;
+    agentCategories?: AgentCategoriesConfig;
+    /**
+     * Routing config held directly on the Agent, independent of any snapshot:
+     * the cross-provider lock must hold even in hosts that wire no routing
+     * data (design §7.0).
+     */
+    agentRouting?: Partial<AgentRoutingConfig>;
+    /**
+     * Live routing-snapshot accessor (design §1.5). Host-constructed; caches by
+     * registry revision. When absent, catalog-dependent features (tier routing,
+     * menu, unknown-model validation) are simply off.
+     */
+    routingSnapshot?: RoutingSnapshotAccessor;
+    /**
+     * Cross-provider routable model index (design v3.6): powers the user-named
+     * model reminder and near-match correction of mistyped provider:model ids.
+     */
+    routableModels?: RoutableModelIndex;
+    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;
+    /** Child follow-ups continue at a safe boundary, including a tool-free answer. */
+    continueOnPendingInput?: boolean;
+    /** Local-only presentation metadata persisted with the submitted user turn. */
+    userMessageUi?: Extract<Message, {
+        role: "user";
+    }>["ui"];
+    /**
+     * 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 {
+    /**
+     * Backing store for the public `messages` accessor. All whole-array
+     * rewrites (clear/compact/rewind/session switch/subagent fork) go through
+     * the setter, which notifies `onContextChanged` subscribers — that push
+     * channel is what keeps derived UI (e.g. the footer usage readout) in sync
+     * without per-path refresh calls that are easy to forget.
+     */
+    private _messages;
+    private contextChangedListeners;
+    private notifyingContextChange;
+    get messages(): Message[];
+    set messages(value: Message[]);
+    private provider;
+    private sessionID?;
+    /**
+     * Bridge to the unified process manager's background tasks, wired by the
+     * host (main.ts) when the host supports them (background-tasks design
+     * §2.3a). list() is pre-filtered to the agent's bound session.
+     */
+    backgroundTasks?: {
+        list: () => import("./tasks/manager.js").BackgroundTaskInfo[];
+        version: () => number;
+        outputTail: (id: string) => string | undefined;
+        kill?: (id: string) => Promise<import("./tasks/manager.js").BackgroundTaskInfo | undefined>;
+        subscribe?: (listener: () => void) => () => void;
+    };
+    private lastTaskReminderVersion;
+    /**
+     * Once-per-session latch for the large-task delegation nudge
+     * (large-task-delegation design §2): goal-loop continuations rebuild
+     * TurnHookState every run, so a per-turn latch would nag on every turn.
+     * If the model read the nudge once and chose not to delegate, repeating
+     * it is noise.
+     */
+    private _providerId;
+    private _model;
+    private tools;
+    private unlockedDeferred;
+    private temperature;
+    private thinkingLevel;
+    private _mode;
+    private _modeVersion;
+    private onModeUpdate?;
+    private onCompactionApplied?;
+    private onContextCheckpoint?;
+    private getContextRevision?;
+    private lastCompactionId?;
+    private onMessageAppend?;
+    private onProviderError?;
+    private onToolResult?;
+    private hookDefinitions;
+    private externalHooks?;
+    private agentRole;
+    private subAgentId?;
+    private maxTurns?;
+    private taskBudget?;
+    private budgetLedger?;
+    private budgetSource;
+    private skillSummaries;
+    private skillCatalogChars?;
+    private memoryPrompt?;
+    private fileStateTracker?;
+    private agentCategories;
+    private agentRouting;
+    /** Owns the routing decision chain, the §6 detector state and the §4 menu. */
+    private readonly router;
+    private providerFactory?;
+    /**
+     * Subagent thread lifecycle + workflow script execution: the store,
+     * scheduler, ChildRunner and their dispatch/ingestion plumbing.
+     */
+    private readonly subagents;
+    /**
+     * Background dynamic-workflow runs (option C Phase 4): run records, waiters,
+     * cancellation and the pending-delivery set. Execution stays on Agent.
+     */
+    private readonly workflowLedger;
+    private subagentsConfig;
+    private readonly rateLimitPolicy?;
+    private lastInputTokens;
+    private lastAnchorMessageCount;
+    private compactionStats;
+    private contextEvents;
+    constructor(options: AgentOptions);
+    /**
+     * Re-inject the deferred-tools advertisement. Hosts that reassign
+     * agent.messages (session resume, Feishu conversation rebuild) drop the
+     * constructor-injected meta reminder — without re-injection the model has
+     * no way to discover deferred tools, since they are also filtered out of
+     * the prompt's tool list.
+     */
+    injectDeferredToolsReminder(): void;
+    /**
+     * Rebinds the agent to a new session (TUI session switch). Keeps
+     * ownerSessionId on newly spawned background tasks and managed servers
+     * accurate (background-tasks design §2.2c).
+     */
+    setSessionID(sessionID: string | undefined): void;
+    /**
+     * Children persist next to the session file so a later process can resume
+     * them via send_input (design §7). An explicit subagents.persistDir config
+     * always wins over the sessionID derivation. Child agents themselves
+     * (agentRole "subagent") never persist children — no recursion exists.
+     */
+    private deriveSubagentPersistDir;
+    getSessionID(): string | undefined;
+    /**
+     * Background-task reminder, state-change gated (design §2.3a): returns a
+     * reminder only when the owned task set changed since the last emission
+     * (started/finished/killed). The reminder channel is append-only, so
+     * emitting on every model call while tasks are merely alive would stack
+     * persistent duplicates that neither pruning nor compaction removes.
+     */
+    consumeBackgroundTaskReminder(): string | undefined;
+    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). */
+    listDeferredTools(): ToolRegistryEntry[];
+    getSystemPromptToolOptions(): Pick<import("./system-prompt.js").SystemPromptOptions, "tools" | "toolSnippets" | "guidelines" | "modelRoutingPrompt" | "memoryPrompt" | "skills" | "skillCatalogChars">;
+    getSkillSummaries(): SkillSummary[];
+    getSkillCatalogChars(): number | undefined;
+    /** Refresh the live Skill catalog after /skills reloads or changes enablement; hosts then rebuild the system prompt. */
+    setSkillSummaries(skills: SkillSummary[]): void;
+    /** Current routing menu (design §4); undefined when no accessor is wired. */
+    buildModelRoutingPromptSection(): string | undefined;
+    /**
+     * Routing menu rendered for a prospective parent route — used by model-
+     * switch transactions to build the NEXT prompt before mutating the agent
+     * (design §1.5).
+     */
+    renderModelRoutingPromptFor(parent: {
+        providerId: string;
+        model: string;
+    }): string | undefined;
+    /**
+     * Push subscription for derived-context consumers (TUI footer, hosts).
+     * Fires whenever resident context mutates in a way that changes a
+     * `getContextUsageSnapshot()` reading: whole-array message rewrites,
+     * appended messages, system-prompt replacement, or model/provider switches
+     * (window size / estimation basis). Returns an unsubscribe function.
+     */
+    onContextChanged(listener: () => void): () => void;
+    private notifyContextChanged;
+    getContextUsageSnapshot(): ContextUsageSnapshot;
+    resetContextUsageAnchor(): void;
+    /** Whether a given tool is deferred and not yet unlocked. */
+    isDeferredAndLocked(name: string): boolean;
+    private getActiveToolEntries;
+    injectSystemReminder(content: string): void;
+    injectModeReminder(): void;
+    /**
+     * Mode reminders are enter-announcements with no cancel semantics, so a stale
+     * one keeps describing a mode the session left long ago. Shift+Tab cycles
+     * through plan on the way to bypassPermissions, which used to leave a live
+     * "Plan mode is now ACTIVE" (plus its "call exit_plan_mode" rule) in history
+     * for the rest of the session — the model then planned instead of building,
+     * and hunted for a tool that is filtered out outside plan mode.
+     *
+     * Hidden rather than spliced: keeping the array shape intact leaves message
+     * indices (usage anchors, compaction bookkeeping) valid, and the transcript
+     * still shows what happened. Cache cost is one invalidated prefix per real
+     * mode switch — the no-op path above keeps repeat injections free.
+     */
+    private retireStaleModeReminders;
+    get role(): "parent" | "subagent";
+    get model(): string;
+    set model(value: string);
+    get providerId(): string;
+    set providerId(value: string);
+    get apiModel(): string;
+    setProvider(provider: Provider): void;
+    complete(messages: Message[], options?: {
+        model?: string;
+        temperature?: number;
+        thinkingLevel?: ThinkingLevel;
+        abortSignal?: AbortSignal;
+    }): Promise<string>;
+    get thinking(): ThinkingLevel;
+    set thinking(value: ThinkingLevel);
+    get reasoning(): ThinkingLevel;
+    set reasoning(value: ThinkingLevel);
+    get mode(): PermissionMode;
+    set mode(value: PermissionMode);
+    setMode(value: PermissionMode): void;
+    /** Internal: snapshot counter that bumps on every mode change. Used by run loop. */
+    get modeVersion(): number;
+    setSystemPrompt(prompt: string): void;
+    run(userInput: string | ContentPart[], cwd: string, options?: AgentRunOptions): AsyncIterable<AgentEvent>;
+    private recoverFromOverflow;
+    compactResidentHistory(): void;
+    private maybeCompactWithLLM;
+    /** Snapshot of how often each compaction path rewrote history this run. */
+    getCompactionStats(): {
+        resident: number;
+        subturn: number;
+        llm: number;
+        heuristic: number;
+        overflow: number;
+        fired: number;
+        droppedMessages: number;
+    };
+    /**
+     * 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, userContext?: string): Promise<string>;
+    runSubAgent(input: string | ContentPart[], cwd: string, options: Parameters<SubagentRuntime["runSubAgent"]>[2]): Promise<SubagentRunResult>;
+    spawnSubAgent(input: string | ContentPart[], cwd: string, options: Parameters<SubagentRuntime["spawnSubAgent"]>[2]): 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[];
+    /** Read-only child transcript for the TUI inspector. */
+    getSubAgentMessages(agentId: string): Message[];
+    /** Marks a child's full summary as delivered to parent context (design §3.3). */
+    markSubagentDelivered(agentId: string): void;
+    /**
+     * The child store, still reachable at its old name. Several tests inspect a
+     * spawned child's record (and its live child Agent) through
+     * `(agent as any).subagentStore`; keeping this forward means the extraction
+     * changed no caller, test or otherwise.
+     */
+    get subagentStore(): SubagentStore;
+    /** run_workflow children are workflowInternal and invisible to listSubAgents. */
+    hasRunningWorkflow(): boolean;
+    /**
+     * 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;
+        ensureProfileTrusted?: (profile: AgentProfile) => Promise<{
+            content: string | unknown;
+        } | undefined>;
+    }): 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;
+        ensureProfileTrusted?: (profile: AgentProfile) => Promise<{
+            content: string | unknown;
+        } | undefined>;
+    }): {
+        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[];
+    /** Injects completed background-workflow results before the next turn (§5 analog). */
+    private flushWorkflowDeliveries;
+    /**
+     * 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.
+     */
+    /** Kept as a thin delegator: routing decisions now live in SubagentRouter. */
+    resolveRouteForSubagent(profile: AgentProfile, category: string | undefined, override?: {
+        model?: string;
+        effort?: ThinkingLevel;
+    }): ResolvedSubagentRoute;
+    /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
+    listRoutableModels(): RoutableModelEntry[] | undefined;
+    /**
+     * The ONE place a child Agent is constructed. The runtime hands over what it
+     * resolved (provider/route/tools/prompt); everything inherited from the
+     * parent is filled in here, which is also what keeps the deliberately
+     * ABSENT arguments absent — `onMessageAppend` (a child must not append to
+     * the parent's session log), `sessionID` (a child must not stop the
+     * parent's auto servers) and the routing catalog (children route by
+     * default, not from the parent's menu).
+     */
+    private createChildAgent;
+    private forkMessagesForSubagent;
+    private maybeCompactResidentHistory;
+    /** Persist conversational context first; keep live reminders outside the durable projection. */
+    private applyContextCheckpoint;
+    private appendMessage;
+    private persistProviderError;
+    private recordProviderError;
+    private appendInterruptedAssistantBoundary;
+    private executeTool;
+}