@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/agent/categories.d.ts

@@ -0,0 +1,100 @@
+import type { ModelTier } from "../model-catalog.js";
+import { type ThinkingLevel } from "../types.js";
+export interface AgentCategoryConfig {
+    model?: string;
+    /**
+     * Resolve the model by tier within the parent provider's catalog
+     * (docs/model-routing-design.md §3.1). Mutually exclusive with `model`;
+     * `model` wins if both are set.
+     */
+    tier?: ModelTier | "inherit";
+    thinkingLevel?: ThinkingLevel;
+    maxConcurrent?: number;
+}
+export type AgentCategoriesConfig = Record<string, AgentCategoryConfig>;
+/**
+ * Field-level provenance for the model-determining fields (§3.3): a value is
+ * "user" ONLY when the user's config object literally contained that key.
+ * thinkingLevel/maxConcurrent overrides carry no routing authority, so a
+ * partially-overridden builtin category keeps its builtin tier under the
+ * rank guard.
+ */
+export interface AgentCategoryProvenance {
+    tierSource?: "builtin" | "user";
+    modelSource?: "builtin" | "user";
+}
+export interface MergedAgentCategory {
+    config: AgentCategoryConfig;
+    provenance: AgentCategoryProvenance;
+}
+export interface ModelRoute {
+    providerId: string;
+    model: string;
+    thinkingLevel: ThinkingLevel;
+}
+/** Which precedence layer decided the model at the category level. */
+export type CategoryModelSource = "builtin-tier" | "user-category";
+/** Which precedence layer decided the FINAL model (§3.4, chain-tracked). */
+export type RouteModelSource = "inherit" | CategoryModelSource | "profile" | "callsite";
+export interface ResolvedSubagentRoute extends ModelRoute {
+    category?: string;
+    inherited: boolean;
+    /** Set when the category layer decided the model (undefined = inherit). */
+    categoryModelSource?: CategoryModelSource;
+    /** True iff providerId+model equal the parent's — regardless of effort (§3.4). */
+    modelInherited?: boolean;
+    /** Assigned while applying the precedence chain, never inferred from final values. */
+    modelSource?: RouteModelSource;
+}
+export type CategoryResolution = {
+    route: ResolvedSubagentRoute;
+} | {
+    error: string;
+};
+export interface ResolvedModelSelection {
+    providerId: string;
+    model: string | "inherit";
+}
+/** Catalog entry visible to tier resolution (built by routing-catalog.ts). */
+export interface TierCatalogEntry {
+    id: string;
+    tier?: ModelTier;
+    /** models.json user-authored ordering; wins over everything (§3.2). */
+    routingPriority?: number;
+    /** Index in the builtin catalog order, when the id is builtin. */
+    builtinIndex?: number;
+}
+/** Context for rank-guarded automatic tier routing (§3.2). */
+export interface TierRoutingContext {
+    /** Tier of the parent's own model, if annotated. */
+    parentTier?: ModelTier;
+    /** Same-provider catalog the tier is resolved against. */
+    models: TierCatalogEntry[];
+    /** agentRouting.autoTier kill switch (default true). */
+    autoTier: boolean;
+}
+export declare const TIER_RANK: Record<ModelTier, number>;
+export declare function builtinAgentCategories(): AgentCategoriesConfig;
+export declare function mergeAgentCategories(userCategories?: AgentCategoriesConfig): AgentCategoriesConfig;
+/**
+ * Field-level merge with provenance (§3.3). The merge itself is identical to
+ * mergeAgentCategories; provenance records whether the user literally wrote
+ * `tier` / `model`, so builtin tiers flowing through a partial override never
+ * masquerade as user intent.
+ */
+export declare function mergeAgentCategoriesWithProvenance(userCategories?: AgentCategoriesConfig): Record<string, MergedAgentCategory>;
+export declare function sanitizeAgentCategories(value: unknown): AgentCategoriesConfig;
+export declare function resolveSubagentRoute(category: string | undefined, parent: ModelRoute, categories?: AgentCategoriesConfig, tierContext?: TierRoutingContext): CategoryResolution;
+/**
+ * Deterministic within-tier ordering (§3.2): user routingPriority, then
+ * builtin catalog order, then normalized id — never a remote response's
+ * array order.
+ */
+export declare function selectTierCandidates(models: TierCatalogEntry[], tier: ModelTier): TierCatalogEntry[];
+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;
+/** Parses a call-site effort/thinking override, returning undefined when invalid. */
+export declare function parseThinkingLevel(value: unknown): ThinkingLevel | undefined;

package/dist/agent/categories.js

@@ -0,0 +1,203 @@
+import { THINKING_LEVELS } from "../types.js";
+export const TIER_RANK = { fast: 0, balanced: 1, strong: 2 };
+const BUILTIN_CATEGORIES = {
+    quick: { model: "inherit", tier: "fast", thinkingLevel: "low", maxConcurrent: 3 },
+    explore: { model: "inherit", tier: "fast", thinkingLevel: "low", maxConcurrent: 3 },
+    deep: { model: "inherit", thinkingLevel: "high", maxConcurrent: 2 },
+    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;
+}
+/**
+ * Field-level merge with provenance (§3.3). The merge itself is identical to
+ * mergeAgentCategories; provenance records whether the user literally wrote
+ * `tier` / `model`, so builtin tiers flowing through a partial override never
+ * masquerade as user intent.
+ */
+export function mergeAgentCategoriesWithProvenance(userCategories) {
+    const sanitizedUser = sanitizeAgentCategories(userCategories);
+    const out = {};
+    for (const [name, config] of Object.entries(builtinAgentCategories())) {
+        out[name] = {
+            config: { ...config },
+            provenance: {
+                tierSource: config.tier !== undefined ? "builtin" : undefined,
+                modelSource: config.model !== undefined && config.model !== "inherit" ? "builtin" : undefined,
+            },
+        };
+    }
+    for (const [name, config] of Object.entries(sanitizedUser)) {
+        const existing = out[name] ?? { config: {}, provenance: {} };
+        out[name] = {
+            config: { ...existing.config, ...config },
+            provenance: {
+                tierSource: config.tier !== undefined ? "user" : existing.provenance.tierSource,
+                modelSource: config.model !== undefined ? "user" : existing.provenance.modelSource,
+            },
+        };
+    }
+    return out;
+}
+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 (isCategoryTier(record.tier)) {
+            config.tier = record.tier;
+        }
+        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, tierContext) {
+    const normalizedCategory = normalizeCategoryName(category);
+    if (!normalizedCategory) {
+        return { route: { ...parent, inherited: true } };
+    }
+    const merged = mergeAgentCategoriesWithProvenance(categories);
+    const entry = merged[normalizedCategory];
+    if (!entry) {
+        return { error: `Unknown subagent category "${normalizedCategory}".` };
+    }
+    const { config, provenance } = entry;
+    // Explicit model binding wins over tier (config surface contract §3.1).
+    const modelSelection = parseModelSelection(config.model, parent.providerId);
+    if (modelSelection.model !== "inherit") {
+        return {
+            route: {
+                category: normalizedCategory,
+                providerId: modelSelection.providerId,
+                model: modelSelection.model,
+                thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
+                inherited: false,
+                categoryModelSource: provenance.modelSource === "user" ? "user-category" : "builtin-tier",
+            },
+        };
+    }
+    // Tier binding: rank-guarded for builtin-sourced tiers, free for
+    // user-authored ones (§3.2).
+    const tierModel = resolveTierModel(config.tier, provenance.tierSource, tierContext);
+    if (tierModel) {
+        return {
+            route: {
+                category: normalizedCategory,
+                providerId: parent.providerId,
+                model: tierModel,
+                thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
+                inherited: false,
+                categoryModelSource: provenance.tierSource === "user" ? "user-category" : "builtin-tier",
+            },
+        };
+    }
+    return {
+        route: {
+            category: normalizedCategory,
+            providerId: parent.providerId,
+            model: parent.model,
+            thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
+            inherited: config.thinkingLevel === undefined,
+        },
+    };
+}
+/**
+ * Rank-guarded tier -> model resolution (§3.2). Returns undefined whenever
+ * the route must inherit: no tier context wired, kill switch off (builtin
+ * tiers only), unknown parent tier, missing target tier, or a target that is
+ * not strictly cheaper than the parent.
+ */
+function resolveTierModel(tier, tierSource, tierContext) {
+    if (!tier || tier === "inherit" || !tierContext)
+        return undefined;
+    const candidates = selectTierCandidates(tierContext.models, tier);
+    if (candidates.length === 0)
+        return undefined;
+    if (tierSource !== "user") {
+        // Builtin-sourced tier: downgrade-only, enforced by rank comparison.
+        if (!tierContext.autoTier)
+            return undefined;
+        if (!tierContext.parentTier)
+            return undefined;
+        if (TIER_RANK[tier] >= TIER_RANK[tierContext.parentTier])
+            return undefined;
+    }
+    return candidates[0].id;
+}
+/**
+ * Deterministic within-tier ordering (§3.2): user routingPriority, then
+ * builtin catalog order, then normalized id — never a remote response's
+ * array order.
+ */
+export function selectTierCandidates(models, tier) {
+    return models
+        .filter((entry) => entry.tier === tier)
+        .sort((a, b) => {
+        const priorityA = a.routingPriority ?? Number.POSITIVE_INFINITY;
+        const priorityB = b.routingPriority ?? Number.POSITIVE_INFINITY;
+        if (priorityA !== priorityB)
+            return priorityA - priorityB;
+        const builtinA = a.builtinIndex ?? Number.POSITIVE_INFINITY;
+        const builtinB = b.builtinIndex ?? Number.POSITIVE_INFINITY;
+        if (builtinA !== builtinB)
+            return builtinA - builtinB;
+        return a.id.localeCompare(b.id);
+    });
+}
+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;
+}
+/** Parses a call-site effort/thinking override, returning undefined when invalid. */
+export function parseThinkingLevel(value) {
+    return isThinkingLevel(value) ? value : 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.includes(value);
+}
+function isCategoryTier(value) {
+    return value === "fast" || value === "balanced" || value === "strong" || value === "inherit";
+}
+function cloneCategories(categories) {
+    return Object.fromEntries(Object.entries(categories).map(([name, config]) => [name, { ...config }]));
+}

package/dist/agent/change-tracker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Git-ground-truth change tracking for a single agent run.
+ *
+ * Tool-metadata bookkeeping (kind === "write" | "edit" | "patch") misses every
+ * other mutation channel: bash heredocs/sed -i, scripts, subagent worktree
+ * merges. Git sees them all. A baseline snapshot is taken at run start; the
+ * delta at completion time is the run's actual footprint.
+ *
+ * Everything here degrades to null outside a git repo or on any git error —
+ * callers fall back to metadata-based signals.
+ */
+export interface GitChangeBaseline {
+    /** Paths already dirty (or untracked) before the run started. */
+    dirtyAtStart: Set<string>;
+}
+export interface ModifiedExistingTest {
+    path: string;
+    deletedLines: number;
+}
+export interface RunChangeSummary {
+    /** Paths that became dirty during the run (not dirty at baseline). */
+    changedFiles: string[];
+    /**
+     * Pre-existing (tracked) test files that were modified during the run,
+     * with how many lines the working tree deletes from them vs HEAD. New test
+     * files created by the run are NOT listed — creating tests is not suspect.
+     */
+    modifiedExistingTests: ModifiedExistingTest[];
+}
+export declare function isTestFilePath(path: string): boolean;
+export declare function captureGitBaseline(cwd: string): Promise<GitChangeBaseline | null>;
+/**
+ * Diff the current working tree against the run-start baseline.
+ *
+ * Known honest limits: a file already dirty at baseline that the run edited
+ * further is not attributed to the run (indistinguishable without content
+ * snapshots), and deleted-line counts for such files would mix user and agent
+ * edits — so they are excluded entirely.
+ */
+export declare function detectRunChanges(cwd: string, baseline: GitChangeBaseline | null): Promise<RunChangeSummary | null>;

package/dist/agent/change-tracker.js

@@ -0,0 +1,89 @@
+/**
+ * Git-ground-truth change tracking for a single agent run.
+ *
+ * Tool-metadata bookkeeping (kind === "write" | "edit" | "patch") misses every
+ * other mutation channel: bash heredocs/sed -i, scripts, subagent worktree
+ * merges. Git sees them all. A baseline snapshot is taken at run start; the
+ * delta at completion time is the run's actual footprint.
+ *
+ * Everything here degrades to null outside a git repo or on any git error —
+ * callers fall back to metadata-based signals.
+ */
+import { execFile } from "node:child_process";
+const GIT_TIMEOUT_MS = 3_000;
+const TEST_PATH_PATTERN = /(^|\/)(tests?|__tests__|spec)(\/|$)|(\.|_|-)(test|tests|spec)\.[^/]+$|(^|\/)test_[^/]+$/i;
+export function isTestFilePath(path) {
+    return TEST_PATH_PATTERN.test(path);
+}
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, stdout) => {
+            resolve(error ? null : stdout);
+        });
+    });
+}
+/** `git status --porcelain -z` → set of paths with any dirty/untracked state. */
+async function dirtyPaths(cwd) {
+    const out = await git(cwd, ["status", "--porcelain", "-uall", "-z"]);
+    if (out === null)
+        return null;
+    const paths = new Set();
+    for (const entry of out.split("\0")) {
+        if (entry.length < 4)
+            continue;
+        // "XY path" (rename entries "XY new\0old" — the extra segment lacks the
+        // status prefix and is shorter than 4 chars only when degenerate; treat
+        // every segment with the status shape as an entry).
+        const path = entry.slice(3);
+        if (path)
+            paths.add(path);
+    }
+    return paths;
+}
+export async function captureGitBaseline(cwd) {
+    const dirty = await dirtyPaths(cwd);
+    if (dirty === null)
+        return null;
+    return { dirtyAtStart: dirty };
+}
+/**
+ * Diff the current working tree against the run-start baseline.
+ *
+ * Known honest limits: a file already dirty at baseline that the run edited
+ * further is not attributed to the run (indistinguishable without content
+ * snapshots), and deleted-line counts for such files would mix user and agent
+ * edits — so they are excluded entirely.
+ */
+export async function detectRunChanges(cwd, baseline) {
+    if (!baseline)
+        return null;
+    const dirtyNow = await dirtyPaths(cwd);
+    if (dirtyNow === null)
+        return null;
+    const changedFiles = [...dirtyNow].filter((path) => !baseline.dirtyAtStart.has(path)).sort();
+    if (changedFiles.length === 0) {
+        return { changedFiles, modifiedExistingTests: [] };
+    }
+    // Untracked paths are new files; only tracked files count as "existing".
+    const untrackedOut = await git(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
+    const untracked = new Set((untrackedOut ?? "").split("\0").filter(Boolean));
+    const modifiedExistingTests = [];
+    const candidates = changedFiles.filter((path) => isTestFilePath(path) && !untracked.has(path));
+    if (candidates.length > 0) {
+        const numstat = await git(cwd, ["diff", "HEAD", "--numstat", "-z", "--", ...candidates]);
+        if (numstat !== null) {
+            // -z numstat entries: "added\tdeleted\tpath\0" (renames add a segment).
+            for (const entry of numstat.split("\0")) {
+                const parts = entry.split("\t");
+                if (parts.length < 3)
+                    continue;
+                const deleted = Number(parts[1]);
+                const path = parts[2];
+                if (!path || Number.isNaN(deleted))
+                    continue;
+                modifiedExistingTests.push({ path, deletedLines: deleted });
+            }
+        }
+    }
+    return { changedFiles, modifiedExistingTests };
+}

package/dist/agent/child-runner.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ChildRunner — executes one logical run of a subagent thread and reports the
+ * outcome to the scheduler (design doc §2, extracted in Phase 3).
+ *
+ * A logical run spans dispatch → final state; a rate-limit re-entry is the
+ * same logical run (no second SubagentStart), while a send_input restart is a
+ * new one. The runner owns: tool validation defense, instance reuse,
+ * turn-boundary budget enforcement, the handoff completeness guard, and the
+ * mapping of failures to SubagentFinalReason.
+ */
+import type { SubagentRunOutcome } from "./subagent-scheduler.js";
+import type { SubagentFinalReason, SubagentThreadRecord } from "./subagent-control.js";
+import type { AgentEvent, Message, ToolRegistryEntry, ToolResult, ToolUpdate } from "../types.js";
+/** Bubble-authored configuration failure whose message contains no provider data. */
+export declare class SafeSubagentConfigurationError extends Error {
+}
+export interface ChildRunOptions {
+    approval: "fail" | "disabled";
+    abortSignal?: AbortSignal;
+    forkContext?: boolean;
+    directEmit?: (update: ToolUpdate) => void;
+    queueUpdates?: boolean;
+    reuseAgent?: boolean;
+    /** 1-based scheduler attempt; >1 means rate-limit re-entry of the same logical run. */
+    attempt?: number;
+}
+export interface ChildRunnerHost {
+    allTools(): ToolRegistryEntry[];
+    emit(record: SubagentThreadRecord, options: ChildRunOptions, status: ToolUpdate["status"], event?: AgentEvent, message?: string): void;
+    runLifecycleHook(record: SubagentThreadRecord, cwd: string, eventName: "SubagentStart" | "SubagentStop", status?: string, error?: string, abortSignal?: AbortSignal): Promise<void>;
+    finalizeBlocked(record: SubagentThreadRecord, error: string, options: ChildRunOptions): void;
+    createInstance(record: SubagentThreadRecord, tools: ToolRegistryEntry[], cwd: string, forkContext?: boolean): Promise<NonNullable<SubagentThreadRecord["agent"]>>;
+    recordProviderError(record: SubagentThreadRecord, error: unknown, request: {
+        messageCount: number;
+        toolCount: number;
+    }): void;
+    notifyWaiters(record: SubagentThreadRecord): void;
+    /** Called on every final state so background results can be ingested (§5). */
+    onFinal(record: SubagentThreadRecord, options: ChildRunOptions): void;
+}
+export declare class ChildRunner {
+    private readonly host;
+    constructor(host: ChildRunnerHost);
+    run(record: SubagentThreadRecord, input: string | import("../types.js").ContentPart[], cwd: string, options: ChildRunOptions): Promise<SubagentRunOutcome>;
+    private runFinalSummaryTurn;
+}
+export declare function sanitizeSubagentSummary(value: string): string;
+/**
+ * Handoff completeness guard (design §3.2): a deterministic CJK-aware token
+ * floor and a cheap intermediate-narration prefix check run in parallel.
+ * Both only apply after the child actually used tools — a short direct answer
+ * to a trivial question is a complete handoff.
+ */
+export declare function needsExplicitFinalSummary(record: SubagentThreadRecord, executedAnyTool: boolean): boolean;
+export declare function classifySubagentAbortReason(reason: unknown, parentSignal: AbortSignal | undefined): SubagentFinalReason;
+/**
+ * Drops trailing "[model request interrupted ...]" boundary messages so a
+ * rate-limit re-entry resumes from clean history (design §4.5).
+ */
+export declare function stripTrailingModelInterruptedBoundary(messages: Message[]): void;
+export declare function summarizeSubagentToolEnd(event: {
+    name: string;
+    result: ToolResult;
+}): string;