@bubblebrain-ai/bubble 0.0.7 → 0.0.9

package/dist/agent/categories.d.ts

@@ -0,0 +1,34 @@
+import type { ThinkingLevel } from "../types.js";
+export interface AgentCategoryConfig {
+    model?: string;
+    thinkingLevel?: ThinkingLevel;
+    maxConcurrent?: number;
+}
+export type AgentCategoriesConfig = Record<string, AgentCategoryConfig>;
+export interface ModelRoute {
+    providerId: string;
+    model: string;
+    thinkingLevel: ThinkingLevel;
+}
+export interface ResolvedSubagentRoute extends ModelRoute {
+    category?: string;
+    inherited: boolean;
+}
+export type CategoryResolution = {
+    route: ResolvedSubagentRoute;
+} | {
+    error: string;
+};
+export interface ResolvedModelSelection {
+    providerId: string;
+    model: string | "inherit";
+}
+export declare function builtinAgentCategories(): AgentCategoriesConfig;
+export declare function mergeAgentCategories(userCategories?: AgentCategoriesConfig): AgentCategoriesConfig;
+export declare function sanitizeAgentCategories(value: unknown): AgentCategoriesConfig;
+export declare function resolveSubagentRoute(category: string | undefined, parent: ModelRoute, categories?: AgentCategoriesConfig): CategoryResolution;
+export declare function resolveModelRoute(model: string | undefined, parentProviderId: string): ResolvedModelSelection;
+export declare function resolveSameProviderModelRoute(model: string | undefined, parentProviderId: string): {
+    model: string | "inherit";
+};
+export declare function normalizeCategoryName(value: unknown): string | undefined;

package/dist/agent/categories.js

@@ -0,0 +1,98 @@
+const THINKING_LEVELS = new Set([
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+]);
+const BUILTIN_CATEGORIES = {
+    quick: { model: "inherit", thinkingLevel: "low", maxConcurrent: 3 },
+    deep: { model: "inherit", thinkingLevel: "high", maxConcurrent: 2 },
+    explore: { model: "inherit", thinkingLevel: "low", maxConcurrent: 3 },
+    review: { model: "inherit", thinkingLevel: "high", maxConcurrent: 2 },
+    frontend: { model: "inherit", thinkingLevel: "high", maxConcurrent: 1 },
+    writing: { model: "inherit", thinkingLevel: "medium", maxConcurrent: 2 },
+};
+export function builtinAgentCategories() {
+    return cloneCategories(BUILTIN_CATEGORIES);
+}
+export function mergeAgentCategories(userCategories) {
+    const merged = builtinAgentCategories();
+    for (const [name, config] of Object.entries(sanitizeAgentCategories(userCategories))) {
+        merged[name] = {
+            ...(merged[name] ?? {}),
+            ...config,
+        };
+    }
+    return merged;
+}
+export function sanitizeAgentCategories(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [name, raw] of Object.entries(value)) {
+        const normalizedName = normalizeCategoryName(name);
+        if (!normalizedName || !raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const record = raw;
+        const config = {};
+        if (typeof record.model === "string" && record.model.trim()) {
+            config.model = record.model.trim();
+        }
+        if (isThinkingLevel(record.thinkingLevel)) {
+            config.thinkingLevel = record.thinkingLevel;
+        }
+        if (typeof record.maxConcurrent === "number" && Number.isFinite(record.maxConcurrent)) {
+            config.maxConcurrent = Math.max(1, Math.floor(record.maxConcurrent));
+        }
+        out[normalizedName] = config;
+    }
+    return out;
+}
+export function resolveSubagentRoute(category, parent, categories) {
+    const normalizedCategory = normalizeCategoryName(category);
+    if (!normalizedCategory) {
+        return { route: { ...parent, inherited: true } };
+    }
+    const merged = mergeAgentCategories(categories);
+    const config = merged[normalizedCategory];
+    if (!config) {
+        return { error: `Unknown subagent category "${normalizedCategory}".` };
+    }
+    const modelSelection = parseModelSelection(config.model, parent.providerId);
+    return {
+        route: {
+            category: normalizedCategory,
+            providerId: modelSelection.providerId,
+            model: modelSelection.model === "inherit" ? parent.model : modelSelection.model,
+            thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
+            inherited: modelSelection.model === "inherit" && config.thinkingLevel === undefined,
+        },
+    };
+}
+export function resolveModelRoute(model, parentProviderId) {
+    return parseModelSelection(model, parentProviderId);
+}
+export function resolveSameProviderModelRoute(model, parentProviderId) {
+    return { model: parseModelSelection(model, parentProviderId).model };
+}
+export function normalizeCategoryName(value) {
+    return typeof value === "string" && value.trim() ? value.trim().toLowerCase() : undefined;
+}
+function parseModelSelection(model, parentProviderId) {
+    if (!model || model === "inherit")
+        return { providerId: parentProviderId, model: "inherit" };
+    if (model.includes(":")) {
+        const [providerId, ...rest] = model.split(":");
+        return { providerId: providerId || parentProviderId, model: rest.join(":") };
+    }
+    return { providerId: parentProviderId, model };
+}
+function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS.has(value);
+}
+function cloneCategories(categories) {
+    return Object.fromEntries(Object.entries(categories).map(([name, config]) => [name, { ...config }]));
+}

package/dist/agent/profiles.d.ts

@@ -1,4 +1,5 @@
 import type { ToolRegistryEntry, TokenUsage } from "../types.js";
+import type { ResolvedSubagentRoute } from "./categories.js";
 import { type SubtaskType } from "./subtask-policy.js";
 export type AgentProfileSource = "user" | "project" | "builtin";
 export type AgentProfileMode = "readonly" | "write_patch" | "write_worktree";
@@ -16,6 +17,7 @@ export interface AgentProfile {
     filePath?: string;
     mode: AgentProfileMode;
     model?: string | "inherit";
+    category?: string;
     tools: AgentProfileTools;
     maxTurns?: number;
     approval: AgentProfileApproval;
@@ -29,6 +31,8 @@ export interface SubagentRunResult {
     nickname?: string;
     status: "completed" | "failed" | "blocked" | "cancelled";
     profileSource: AgentProfileSource;
+    category?: string;
+    route?: ResolvedSubagentRoute;
     task: string;
     summary: string;
     toolNotes: string[];

package/dist/agent/profiles.js

@@ -85,7 +85,6 @@ export function builtinAgentProfiles() {
                 include: [...policy.allowedTools],
                 exclude: [],
             },
-            maxTurns: policy.maxTurns,
             approval: "fail",
             nicknameCandidates: DEFAULT_NICKNAME_CANDIDATES,
             prompt: policy.reminder,
@@ -103,7 +102,6 @@ export function builtinAgentProfiles() {
             include,
             exclude: [],
         },
-        maxTurns: 8,
         approval: "fail",
         nicknameCandidates: DEFAULT_NICKNAME_CANDIDATES,
         prompt,
@@ -119,7 +117,7 @@ export function builtinAgentProfiles() {
             "Answer the specific question by inspecting the repository directly. Prefer precise file paths and line-level evidence.",
             "Keep the answer compact and avoid broad refactors or implementation plans unless asked.",
         ].join("\n"), ["read", "glob", "grep", "lsp", "memory_search", "memory_read_summary", "skill", "todo_write"]),
-        roleProfile("worker", "Bounded implementation worker subagent", [
+        roleProfile("worker", "Implementation-planning worker subagent", [
             "You are a worker subagent. In this Phase 1 runtime you are read-only, so you must not modify files.",
             "Analyze the assigned implementation slice, identify exact files to change, and return a concrete patch plan or findings.",
             "If write-capable worker mode is needed, say so explicitly.",
@@ -298,6 +296,7 @@ function parseAgentProfileFile(raw, source, filePath) {
         filePath,
         mode: modeValue(frontmatter.mode),
         model: stringValue(frontmatter.model) || "inherit",
+        category: stringValue(frontmatter.category),
         tools: toolsValue(frontmatter.tools),
         maxTurns: numberValue(frontmatter.maxTurns),
         approval: approvalValue(frontmatter.approval),

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

@@ -1,4 +1,5 @@
 import type { AgentProfile, AgentProfileSource, SubagentRunResult } from "./profiles.js";
+import type { ResolvedSubagentRoute } from "./categories.js";
 import type { AgentEvent, ContentPart, Message, ToolUpdate } from "../types.js";
 export type SubagentThreadStatus = "queued" | "running" | "completed" | "failed" | "blocked" | "cancelled" | "closed";
 export interface SubagentThreadSnapshot {
@@ -7,6 +8,8 @@ export interface SubagentThreadSnapshot {
     nickname: string;
     agentName: string;
     profileSource: AgentProfileSource;
+    category?: string;
+    route?: ResolvedSubagentRoute;
     status: SubagentThreadStatus;
     task: string;
     summary: string;
@@ -21,6 +24,8 @@ export interface SubagentThreadRecord {
     runId: string;
     nickname: string;
     profile: AgentProfile;
+    category?: string;
+    route?: ResolvedSubagentRoute;
     parentToolCallId: string;
     parentToolName: string;
     status: SubagentThreadStatus;

package/dist/agent/subagent-control.js

@@ -5,6 +5,8 @@ export function snapshotSubagentThread(record) {
         nickname: record.nickname,
         agentName: record.profile.name,
         profileSource: record.profile.source,
+        category: record.category,
+        route: record.route,
         status: record.status,
         task: record.task,
         summary: record.summary,
@@ -29,6 +31,8 @@ export function subagentResultFromThread(record) {
         nickname: record.nickname,
         status,
         profileSource: record.profile.source,
+        category: record.category,
+        route: record.route,
         task: record.task,
         summary: record.summary,
         toolNotes: [...record.toolNotes],

package/dist/agent/subagent-lifecycle-reminder.d.ts

@@ -0,0 +1,3 @@
+import type { SubagentThreadSnapshot } from "./subagent-control.js";
+import type { ToolResult } from "../types.js";
+export declare function buildSubagentLifecycleReminder(snapshots: SubagentThreadSnapshot[], toolResults: ToolResult[]): string | undefined;

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

@@ -0,0 +1,102 @@
+const STATUS_ORDER = ["queued", "running", "completed", "blocked", "failed", "cancelled", "closed"];
+export function buildSubagentLifecycleReminder(snapshots, toolResults) {
+    const subagents = collectUniqueSubagents(snapshots, toolResults);
+    if (subagents.length === 0)
+        return undefined;
+    const counts = statusCounts(subagents);
+    const lines = [
+        "Subagent lifecycle truth:",
+        `- Unique subagents currently tracked: ${subagents.length}.`,
+        `- Status counts: ${formatStatusCounts(counts)}.`,
+        "- Agents:",
+        ...subagents.map(formatSubagentLine),
+        "- Count unique agent_id values only; do not count repeated spawn_agent/wait_agent tool calls or repeated UI Subagents blocks as additional subagents.",
+        "- Do not describe a subagent as running or still working if its status above is completed, failed, blocked, cancelled, or closed.",
+        "- After spawn_agent, call wait_agent before user-facing progress narration unless you are doing concrete non-overlapping local work.",
+        "- When writing a synthesis, use the exact unique subagent count and statuses above.",
+    ];
+    return lines.join("\n");
+}
+function collectUniqueSubagents(snapshots, toolResults) {
+    const byId = new Map();
+    for (const result of toolResults) {
+        for (const subagent of subagentsFromMetadata(result.metadata)) {
+            byId.set(subagent.agentId, {
+                ...byId.get(subagent.agentId),
+                ...subagent,
+            });
+        }
+    }
+    for (const snapshot of snapshots) {
+        byId.set(snapshot.agentId, {
+            ...byId.get(snapshot.agentId),
+            agentId: snapshot.agentId,
+            nickname: snapshot.nickname,
+            agentName: snapshot.agentName,
+            category: snapshot.category,
+            status: snapshot.status,
+            summary: snapshot.summary,
+            error: snapshot.error,
+        });
+    }
+    return [...byId.values()].sort((a, b) => a.agentId.localeCompare(b.agentId));
+}
+function subagentsFromMetadata(metadata) {
+    const raw = metadata?.subagents;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const record = item;
+        const agentId = stringField(record.subAgentId) ?? stringField(record.agentId);
+        if (!agentId)
+            continue;
+        out.push({
+            agentId,
+            nickname: stringField(record.nickname),
+            agentName: stringField(record.agentName),
+            category: stringField(record.category),
+            status: stringField(record.status),
+            summary: stringField(record.summary),
+            error: stringField(record.error),
+        });
+    }
+    return out;
+}
+function statusCounts(subagents) {
+    const counts = new Map();
+    for (const subagent of subagents) {
+        const status = subagent.status || "unknown";
+        counts.set(status, (counts.get(status) ?? 0) + 1);
+    }
+    return counts;
+}
+function formatStatusCounts(counts) {
+    const known = STATUS_ORDER
+        .filter((status) => counts.has(status))
+        .map((status) => `${status}=${counts.get(status)}`);
+    const extra = [...counts.keys()]
+        .filter((status) => !STATUS_ORDER.includes(status))
+        .sort()
+        .map((status) => `${status}=${counts.get(status)}`);
+    return [...known, ...extra].join(", ") || "none";
+}
+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;
+    const suffix = note ? `; note=${truncateForReminder(oneLine(note))}` : "";
+    return `  - ${label} (${role}) agent_id=${subagent.agentId} status=${status}${suffix}`;
+}
+function stringField(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function oneLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function truncateForReminder(value, max = 180) {
+    return value.length <= max ? value : `${value.slice(0, max - 3)}...`;
+}

package/dist/agent/subagent-route-format.d.ts

@@ -0,0 +1,8 @@
+export interface SubagentRouteLike {
+    providerId?: unknown;
+    model?: unknown;
+    thinkingLevel?: unknown;
+}
+export declare function formatSubagentRoute(route: SubagentRouteLike | undefined, options?: {
+    includeThinking?: boolean;
+}): string | undefined;

package/dist/agent/subagent-route-format.js

@@ -0,0 +1,18 @@
+export function formatSubagentRoute(route, options = {}) {
+    if (!route || typeof route !== "object")
+        return undefined;
+    const providerId = stringField(route.providerId);
+    const model = stringField(route.model);
+    if (!providerId && !model)
+        return undefined;
+    const modelLabel = providerId && model
+        ? `${providerId}:${model}`
+        : providerId || model;
+    if (!options.includeThinking)
+        return modelLabel;
+    const thinkingLevel = stringField(route.thinkingLevel);
+    return thinkingLevel ? `${modelLabel} (thinking: ${thinkingLevel})` : modelLabel;
+}
+function stringField(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/agent/subtask-policy.d.ts

@@ -5,7 +5,6 @@ export interface SubtaskPolicy {
     allowedTools: string[];
     reminder: string;
     resultStatus: ToolResultStatus;
-    maxTurns?: number;
     taskBudget?: {
         total: number;
     };

package/dist/agent/subtask-policy.js

@@ -9,7 +9,6 @@ const POLICY_MAP = {
             "- Return a concise summary of what you found and where.",
         ].join("\n"),
         resultStatus: "success",
-        maxTurns: 6,
         taskBudget: { total: 180_000 },
     },
     security_investigation: {
@@ -22,7 +21,6 @@ const POLICY_MAP = {
             "- Do not loop on broad keyword search; summarize evidence and uncertainty.",
         ].join("\n"),
         resultStatus: "success",
-        maxTurns: 8,
         taskBudget: { total: 220_000 },
     },
     evidence_correlation: {
@@ -35,7 +33,6 @@ const POLICY_MAP = {
             "- Produce a reasoning-focused summary that states what the evidence supports.",
         ].join("\n"),
         resultStatus: "success",
-        maxTurns: 4,
         taskBudget: { total: 120_000 },
     },
     general_readonly: {
@@ -47,7 +44,6 @@ const POLICY_MAP = {
             "- Keep the scope tightly bounded and summarize findings concisely.",
         ].join("\n"),
         resultStatus: "success",
-        maxTurns: 6,
         taskBudget: { total: 180_000 },
     },
 };

package/dist/agent.d.ts

@@ -2,12 +2,15 @@
  * Agent - The core decision loop.
  * It maintains message state, calls the LLM, executes tools, and auto-continues.
  */
+import { type ContextUsageSnapshot } from "./context/usage.js";
 import type { AgentEvent, ContentPart, PermissionMode, Message, Provider, ThinkingLevel, Todo, ToolResult, ToolRegistryEntry, ToolUpdate } from "./types.js";
 import { type TurnHooks } from "./orchestrator/hooks.js";
+import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "./agent/categories.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";
 import type { SkillSummary } from "./skills/types.js";
+import type { FileStateTracker } from "./tools/file-state.js";
 export declare class AgentAbortError extends Error {
     constructor(message?: string);
 }
@@ -39,6 +42,9 @@ export interface AgentOptions {
     };
     skills?: SkillSummary[];
     memoryPrompt?: string;
+    fileStateTracker?: FileStateTracker;
+    agentCategories?: AgentCategoriesConfig;
+    providerFactory?: (route: ResolvedSubagentRoute) => Provider | Promise<Provider>;
 }
 export declare class Agent {
     messages: Message[];
@@ -65,6 +71,9 @@ export declare class Agent {
     private budgetSource;
     private skillSummaries;
     private memoryPrompt?;
+    private fileStateTracker?;
+    private agentCategories;
+    private providerFactory?;
     private subagentThreads;
     private pendingSubagentUpdates;
     private lastInputTokens;
@@ -74,8 +83,10 @@ export declare class Agent {
     unlockDeferredTools(names: string[]): void;
     /** All deferred tools in this session (for tool_search to inspect). */
     listDeferredTools(): ToolRegistryEntry[];
+    getContextUsageSnapshot(): ContextUsageSnapshot;
     /** Whether a given tool is deferred and not yet unlocked. */
     isDeferredAndLocked(name: string): boolean;
+    private getActiveToolEntries;
     injectSystemReminder(content: string): void;
     injectModeReminder(): void;
     get model(): string;
@@ -109,6 +120,7 @@ export declare class Agent {
     }): AsyncIterable<AgentEvent>;
     private recoverFromOverflow;
     compactResidentHistory(): void;
+    private maybeCompactWithLLM;
     runSubtask(input: string | ContentPart[], cwd: string, options?: {
         subtaskType?: string;
         description?: string;
@@ -118,6 +130,8 @@ export declare class Agent {
         runId: string;
         subAgentId: string;
         parentToolCallId: string;
+        category?: string;
+        route?: ResolvedSubagentRoute;
         approval?: "fail" | "disabled";
         emitUpdate?: (update: ToolUpdate) => void;
         description?: string;
@@ -128,6 +142,8 @@ export declare class Agent {
     spawnSubAgent(input: string | ContentPart[], cwd: string, options: {
         profile: AgentProfile;
         parentToolCallId: string;
+        category?: string;
+        route?: ResolvedSubagentRoute;
         approval?: "fail" | "disabled";
         description?: string;
         abortSignal?: AbortSignal;
@@ -144,10 +160,12 @@ export declare class Agent {
     }): Promise<SubagentThreadSnapshot>;
     closeSubAgent(agentId: string): Promise<SubagentThreadSnapshot>;
     listSubAgents(): SubagentThreadSnapshot[];
+    private resolveRouteForSubagent;
     private createSubagentThreadRecord;
     private runSubagentThread;
     private runSubagentFinalSummaryTurn;
     private createSubAgentInstance;
+    private resolveProviderForRoute;
     private forkMessagesForSubagent;
     private buildSubagentUpdate;
     private queueSubagentUpdate;