@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/agent/subtask-policy.js

@@ -0,0 +1,56 @@
+const POLICY_MAP = {
+    search: {
+        type: "search",
+        allowedTools: ["read", "ls", "grep", "web_search", "web_fetch", "skill"],
+        reminder: [
+            "Subtask policy: search",
+            "- Focus on locating relevant files, symbols, and evidence quickly.",
+            "- Use ls for directory contents and grep for content search.",
+            "- Return a concise summary of what you found and where.",
+        ].join("\n"),
+        resultStatus: "success",
+        taskBudget: { total: 180_000 },
+    },
+    security_investigation: {
+        type: "security_investigation",
+        allowedTools: ["read", "ls", "grep", "web_search", "web_fetch", "skill"],
+        reminder: [
+            "Subtask policy: security_investigation",
+            "- Investigate only in read-only mode.",
+            "- Collect evidence about config load paths, environment reads, persistence paths, masking, and exposure paths.",
+            "- Do not loop on broad keyword search; summarize evidence and uncertainty.",
+        ].join("\n"),
+        resultStatus: "success",
+        taskBudget: { total: 220_000 },
+    },
+    evidence_correlation: {
+        type: "evidence_correlation",
+        allowedTools: ["read", "skill"],
+        reminder: [
+            "Subtask policy: evidence_correlation",
+            "- Correlate evidence already discovered.",
+            "- Avoid new broad searches; read only the specific files that matter.",
+            "- Produce a reasoning-focused summary that states what the evidence supports.",
+        ].join("\n"),
+        resultStatus: "success",
+        taskBudget: { total: 120_000 },
+    },
+    general_readonly: {
+        type: "general_readonly",
+        allowedTools: ["read", "ls", "grep", "web_search", "web_fetch", "skill"],
+        reminder: [
+            "Subtask policy: general_readonly",
+            "- Stay in read-only mode.",
+            "- Keep the scope tightly bounded and summarize findings concisely.",
+        ].join("\n"),
+        resultStatus: "success",
+        taskBudget: { total: 180_000 },
+    },
+};
+export function getSubtaskPolicy(type) {
+    return POLICY_MAP[type ?? "general_readonly"];
+}
+export function filterToolsForSubtask(tools, type) {
+    const policy = getSubtaskPolicy(type);
+    return tools.filter((tool) => policy.allowedTools.includes(tool.name));
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Background-task lifecycle reminder (background-tasks design §2.3a).
+ *
+ * Emission is STATE-CHANGE gated, never per-model-call: the reminder channel
+ * is append-only (each injection is a persistent meta message that survives
+ * pruning and compaction), so the caller compares the manager's task state
+ * version and builds a reminder only when the owned task set changed since
+ * the last emission. This mirrors the subagent lifecycle reminder's activity
+ * gate rather than firing while tasks are merely alive.
+ *
+ * Because compaction preserves meta messages but drops session markers, this
+ * reminder is also how the model recovers task ids after /compact.
+ */
+import type { BackgroundTaskInfo } from "../tasks/manager.js";
+export interface TaskReminderInput {
+    tasks: BackgroundTaskInfo[];
+    outputTail: (id: string) => string | undefined;
+    /**
+     * The task tools are already unlocked (the spawn path calls
+     * unlockDeferredTools). When true the tool_search hint is dropped — field
+     * test 2026-07-19 showed the unconditional hint makes the model burn a
+     * tool_search call for tools it already has.
+     */
+    toolsAvailable?: boolean;
+}
+export declare function buildTaskLifecycleReminder({ tasks, outputTail, toolsAvailable }: TaskReminderInput): string | undefined;

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

@@ -0,0 +1,59 @@
+/**
+ * Background-task lifecycle reminder (background-tasks design §2.3a).
+ *
+ * Emission is STATE-CHANGE gated, never per-model-call: the reminder channel
+ * is append-only (each injection is a persistent meta message that survives
+ * pruning and compaction), so the caller compares the manager's task state
+ * version and builds a reminder only when the owned task set changed since
+ * the last emission. This mirrors the subagent lifecycle reminder's activity
+ * gate rather than firing while tasks are merely alive.
+ *
+ * Because compaction preserves meta messages but drops session markers, this
+ * reminder is also how the model recovers task ids after /compact.
+ */
+const OUTPUT_TAIL_CHARS = 2000;
+export function buildTaskLifecycleReminder({ tasks, outputTail, toolsAvailable }) {
+    if (tasks.length === 0)
+        return undefined;
+    const running = tasks.filter((task) => task.status === "running");
+    const finishedUndelivered = tasks.filter((task) => task.status !== "running" && task.deliveredAt === undefined);
+    const finishedDelivered = tasks.filter((task) => task.status !== "running" && task.deliveredAt !== undefined);
+    if (running.length === 0 && finishedUndelivered.length === 0 && finishedDelivered.length === 0) {
+        return undefined;
+    }
+    const lines = ["Background task truth:"];
+    for (const task of running) {
+        const elapsed = Math.round((Date.now() - task.startedAt) / 1000);
+        lines.push(`- running: ${task.id} (${label(task)}, ${elapsed}s elapsed)`);
+    }
+    for (const task of finishedUndelivered) {
+        const elapsed = Math.round(((task.endedAt ?? Date.now()) - task.startedAt) / 1000);
+        lines.push(`- finished since last update: ${task.id} (${label(task)}) ${task.status}${task.exitCode != null ? ` exit ${task.exitCode}` : ""} in ${elapsed}s`);
+        const tail = outputTail(task.id)?.trim();
+        if (tail) {
+            lines.push(`  output tail:`);
+            lines.push(...clampTail(tail).split("\n").map((line) => `    ${line}`));
+            lines.push("  Call task_output only if you need more of the output.");
+        }
+    }
+    // Delivered final results already reached the model in full — id + status
+    // only, never the output again (mirrors the subagent delivered demotion).
+    for (const task of finishedDelivered) {
+        lines.push(`- delivered: ${task.id} ${task.status}${task.exitCode != null ? ` (exit ${task.exitCode})` : ""}`);
+    }
+    lines.push(toolsAvailable
+        ? "- Check tasks with task_output; stop them with kill_task. Both are already in your tool list — do NOT call tool_search for them."
+        : "- Check tasks with task_output; stop them with kill_task (deferred: load via tool_search with query 'select:task_output,kill_task' if not yet available).");
+    lines.push("- Never re-run work a finished task already did; never poll with foreground sleep.");
+    return lines.join("\n");
+}
+function label(task) {
+    return task.description?.trim() || truncate(task.command, 60);
+}
+function clampTail(tail) {
+    return tail.length <= OUTPUT_TAIL_CHARS ? tail : `…${tail.slice(-OUTPUT_TAIL_CHARS)}`;
+}
+function truncate(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}

package/dist/agent/tool-intent.d.ts

@@ -0,0 +1,45 @@
+import type { ParsedToolCall } from "../types.js";
+export type ToolFamily = "search" | "read" | "write" | "edit" | "shell" | "web" | "other";
+export interface SearchIntent {
+    pattern: string;
+    path?: string;
+    include?: string;
+    signature: string;
+    familyKey: string;
+}
+export interface ReadIntent {
+    path: string;
+    offset?: number | string;
+    limit?: number | string;
+    signature: string;
+    familyKey: string;
+}
+export interface ToolIntent {
+    family: ToolFamily;
+    search?: SearchIntent;
+    read?: ReadIntent;
+}
+export declare function analyzeToolIntent(toolCall: Pick<ParsedToolCall, "name" | "parsedArgs">): ToolIntent;
+export interface ParsedSearchCommand {
+    pattern: string;
+    path?: string;
+    include?: string;
+    /**
+     * True only when a structured-grep rewrite would execute EXACTLY what the
+     * model asked for. False whenever anything was dropped or reinterpreted:
+     * unknown flags (-i, -A, -w, ...), --iglob (case-insensitivity lost),
+     * --include under rg (not an rg flag - a faithful run would error), more
+     * than one path, or the `grep` binary itself (BRE dialect vs the tool's
+     * rg engine). Observation (intent classification) tolerates lossy parses;
+     * execution rewriting must not (tool-arbiter).
+     */
+    lossless: boolean;
+}
+export interface ParsedReadCommand {
+    path: string;
+    offset?: number | string;
+    limit?: number | string;
+}
+export declare function parseSearchBashCommand(command: string): ParsedSearchCommand | undefined;
+export declare function parseReadBashCommand(command: string): ParsedReadCommand | undefined;
+export declare function shellSplit(command: string): string[];

package/dist/agent/tool-intent.js

@@ -0,0 +1,318 @@
+const SEARCH_TOKEN_CANONICAL = new Map([
+    ["api_key", "secret"],
+    ["apikey", "secret"],
+    ["api", "secret"],
+    ["key", "secret"],
+    ["keys", "secret"],
+    ["secret", "secret"],
+    ["secrets", "secret"],
+    ["token", "secret"],
+    ["tokens", "secret"],
+    ["credential", "secret"],
+    ["credentials", "secret"],
+    ["auth", "secret"],
+    ["password", "secret"],
+    ["passwd", "secret"],
+    ["bearer", "secret"],
+    ["env", "config"],
+    ["config", "config"],
+    ["dotenv", "config"],
+]);
+export function analyzeToolIntent(toolCall) {
+    switch (toolCall.name) {
+        case "glob":
+            return {
+                family: "search",
+                search: buildSearchIntent(stringArg(toolCall.parsedArgs.pattern), stringArg(toolCall.parsedArgs.path)),
+            };
+        case "grep":
+            return {
+                family: "search",
+                search: buildSearchIntent(stringArg(toolCall.parsedArgs.pattern), stringArg(toolCall.parsedArgs.path), stringArg(toolCall.parsedArgs.glob)),
+            };
+        case "bash": {
+            const parsed = parseSearchBashCommand(stringArg(toolCall.parsedArgs.command));
+            if (parsed) {
+                return {
+                    family: "search",
+                    search: buildSearchIntent(parsed.pattern, parsed.path, parsed.include),
+                };
+            }
+            const parsedRead = parseReadBashCommand(stringArg(toolCall.parsedArgs.command));
+            if (parsedRead) {
+                return {
+                    family: "read",
+                    read: buildReadIntent(parsedRead.path, parsedRead.offset, parsedRead.limit),
+                };
+            }
+            return { family: "shell" };
+        }
+        case "read":
+            return {
+                family: "read",
+                read: buildReadIntent(stringArg(toolCall.parsedArgs.path ?? toolCall.parsedArgs.file), numberOrStringArg(toolCall.parsedArgs.offset), numberOrStringArg(toolCall.parsedArgs.limit)),
+            };
+        case "write":
+            return { family: "write" };
+        case "edit":
+            return { family: "edit" };
+        case "web_search":
+        case "web_fetch":
+            return { family: "web" };
+        default:
+            return { family: "other" };
+    }
+}
+export function parseSearchBashCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (/[|;&><`]/.test(trimmed)) {
+        return undefined;
+    }
+    const tokens = shellSplit(trimmed);
+    if (tokens.length === 0) {
+        return undefined;
+    }
+    const binary = tokens[0];
+    if (!["grep", "rg", "ripgrep"].includes(binary)) {
+        return undefined;
+    }
+    // The structured grep tool shells out to rg, so only rg-origin commands
+    // can be dialect-identical; GNU grep patterns are BRE and must not be
+    // silently re-executed under rg's Rust regex engine.
+    let lossless = binary !== "grep";
+    const positional = [];
+    let include;
+    for (let index = 1; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (!token)
+            continue;
+        if (token === "--glob" || token === "--iglob" || token === "--include") {
+            include = tokens[index + 1];
+            // --iglob loses case-insensitivity in translation; --include is not an
+            // rg flag at all (a faithful run would error, and hiding that from the
+            // model masks its mistake). Only --glob maps 1:1 onto the tool.
+            if (token !== "--glob")
+                lossless = false;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--glob=") || token.startsWith("--iglob=") || token.startsWith("--include=")) {
+            include = token.slice(token.indexOf("=") + 1);
+            if (!token.startsWith("--glob="))
+                lossless = false;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            // Any other flag (-i, -A 3, -w, -l, ...) has no representation in the
+            // structured tool; dropping it would change the search's meaning.
+            lossless = false;
+            continue;
+        }
+        positional.push(token);
+    }
+    if (positional.length === 0) {
+        return undefined;
+    }
+    // A third positional (multiple search roots) cannot be expressed either.
+    if (positional.length > 2)
+        lossless = false;
+    const [pattern, maybePath] = positional;
+    return {
+        pattern,
+        path: maybePath,
+        include,
+        lossless,
+    };
+}
+export function parseReadBashCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (/[|;&><`]/.test(trimmed)) {
+        return undefined;
+    }
+    const tokens = shellSplit(trimmed);
+    if (tokens.length === 0) {
+        return undefined;
+    }
+    const binary = tokens[0];
+    if (binary === "cat" || binary === "nl") {
+        const path = lastPositional(tokens.slice(1));
+        return path ? { path } : undefined;
+    }
+    if (binary === "head") {
+        const { path, lineCount } = parseHeadTailArgs(tokens.slice(1));
+        return path ? { path, offset: 1, limit: lineCount ?? "head" } : undefined;
+    }
+    if (binary === "tail") {
+        const { path, lineCount } = parseHeadTailArgs(tokens.slice(1));
+        return path ? { path, offset: `tail:${lineCount ?? "default"}`, limit: lineCount ?? "tail" } : undefined;
+    }
+    if (binary === "sed") {
+        return parseSedReadCommand(tokens.slice(1));
+    }
+    return undefined;
+}
+function buildSearchIntent(pattern, path, include) {
+    const normalizedPath = normalizePath(path ?? ".");
+    const rawNormalizedPattern = normalizeRawPattern(pattern);
+    const normalizedTokens = canonicalizeSearchTokens(pattern);
+    const signature = `${normalizedPath}::${include ?? "*"}::${rawNormalizedPattern || normalizedTokens.join("|")}`;
+    const familyTokens = normalizedTokens.filter((token) => token === "secret" || token === "config");
+    const familyKey = `${normalizedPath}::${familyTokens.join("|") || normalizedTokens.slice(0, 3).join("|") || "generic-search"}`;
+    return {
+        pattern,
+        path,
+        include,
+        signature,
+        familyKey,
+    };
+}
+function buildReadIntent(path, offset, limit) {
+    const normalizedPath = normalizePath(path || ".");
+    const normalizedOffset = offset ?? 1;
+    const normalizedLimit = limit ?? "default";
+    return {
+        path,
+        offset,
+        limit,
+        signature: `${normalizedPath}::${normalizedOffset}::${normalizedLimit}`,
+        familyKey: normalizedPath,
+    };
+}
+function canonicalizeSearchTokens(pattern) {
+    const normalized = normalizeRawPattern(pattern);
+    const tokens = normalized.split(/[^a-z0-9_]+/).filter(Boolean);
+    const canonical = new Set();
+    for (const token of tokens) {
+        canonical.add(SEARCH_TOKEN_CANONICAL.get(token) ?? token);
+    }
+    return [...canonical].sort();
+}
+function normalizeRawPattern(pattern) {
+    return pattern.trim().toLowerCase().replace(/\\s\+/g, " ").replace(/\s+/g, " ");
+}
+function normalizePath(pathValue) {
+    return pathValue.trim().replace(/\\/g, "/").replace(/\/+/g, "/");
+}
+function stringArg(value) {
+    return typeof value === "string" ? value : "";
+}
+function numberOrStringArg(value) {
+    return typeof value === "number" || typeof value === "string" ? value : undefined;
+}
+function lastPositional(tokens) {
+    for (let index = tokens.length - 1; index >= 0; index--) {
+        const token = tokens[index];
+        if (!token.startsWith("-")) {
+            return token;
+        }
+    }
+    return undefined;
+}
+function parseHeadTailArgs(tokens) {
+    let lineCount;
+    const positional = [];
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === "-n" || token === "--lines") {
+            lineCount = parseLineCount(tokens[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("-n") && token.length > 2) {
+            lineCount = parseLineCount(token.slice(2));
+            continue;
+        }
+        if (token.startsWith("--lines=")) {
+            lineCount = parseLineCount(token.slice("--lines=".length));
+            continue;
+        }
+        if (token.startsWith("-")) {
+            continue;
+        }
+        positional.push(token);
+    }
+    return {
+        path: positional[positional.length - 1],
+        lineCount,
+    };
+}
+function parseSedReadCommand(tokens) {
+    const positional = [];
+    for (const token of tokens) {
+        if (token === "-n" || token.startsWith("-")) {
+            continue;
+        }
+        positional.push(token);
+    }
+    if (positional.length < 2) {
+        return undefined;
+    }
+    const expression = positional[0];
+    const path = positional[positional.length - 1];
+    const range = expression.match(/^(\d+)(?:,(\d+))?p$/);
+    if (!range) {
+        return { path, offset: expression };
+    }
+    const start = Number(range[1]);
+    const end = range[2] ? Number(range[2]) : start;
+    return {
+        path,
+        offset: start,
+        limit: Math.max(1, end - start + 1),
+    };
+}
+function parseLineCount(value) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number(value.replace(/^\+/, ""));
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+export function shellSplit(command) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let escaped = false;
+    for (const char of command) {
+        if (escaped) {
+            current += char;
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}

package/dist/agent/tool-visibility.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transcript visibility of tool results.
+ *
+ * `hiddenFromTranscript` is a general mechanism: a hook may block a tool call
+ * and mark the exchange hidden so it never reaches the model's transcript or
+ * the UI. These helpers are the canonical way to test for it.
+ */
+import type { ToolResult, ToolResultMetadata } from "../types.js";
+export declare function isHiddenToolResult(result: ToolResult | undefined): result is ToolResult;
+export declare function isHiddenToolMetadata(metadata: ToolResultMetadata | undefined): boolean;

package/dist/agent/tool-visibility.js

@@ -0,0 +1,6 @@
+export function isHiddenToolResult(result) {
+    return result?.metadata?.hiddenFromTranscript === true;
+}
+export function isHiddenToolMetadata(metadata) {
+    return metadata?.hiddenFromTranscript === true;
+}

package/dist/agent/transcript-helpers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Transcript-level helpers: interrupted-run boundaries, the cancelled-tool
+ * sentinel, required-arg validation and the subagent-lifecycle tool-name
+ * predicate used when forking context for children.
+ */
+import type { Message, ToolResult } from "../types.js";
+export declare function findMissingRequiredArgs(schema: {
+    required?: string[];
+} | undefined, args: Record<string, any> | undefined): string[];
+export declare function shouldAppendModelInterruptedBoundary(messages: Message[]): boolean;
+export declare function createModelInterruptedMessage(_error: unknown, metadata: {
+    model: string;
+    providerId: string;
+    modelId: string;
+}): Extract<Message, {
+    role: "assistant";
+}>;
+export declare function lastProviderMessage(messages: Message[]): Message | undefined;
+export declare function cancelledToolResult(toolName: string): ToolResult;
+export declare function isSubagentLifecycleTool(name: string): boolean;

package/dist/agent/transcript-helpers.js

@@ -0,0 +1,63 @@
+export function findMissingRequiredArgs(schema, args) {
+    const required = schema?.required;
+    if (!required || required.length === 0)
+        return [];
+    const missing = [];
+    for (const name of required) {
+        const value = args ? args[name] : undefined;
+        // Empty strings/arrays are intentionally allowed — writing an empty file
+        // or passing an empty list can be legitimate. Only undefined/null counts
+        // as "missing", because the observed failure mode is `finalArgs: "{}"`
+        // where the field is entirely absent.
+        if (value === undefined || value === null) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+export function shouldAppendModelInterruptedBoundary(messages) {
+    return messages.at(-1)?.role === "tool";
+}
+export function createModelInterruptedMessage(_error, metadata) {
+    return {
+        role: "assistant",
+        // This boundary is replayed to future providers and memory extraction.
+        // Never copy provider error text into conversational history.
+        content: "[model request interrupted before a final answer was produced]",
+        model: metadata.model,
+        providerId: metadata.providerId,
+        modelId: metadata.modelId,
+    };
+}
+export function lastProviderMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role === "system" || message.role === "meta")
+            continue;
+        return message;
+    }
+    return undefined;
+}
+export function cancelledToolResult(toolName) {
+    return {
+        content: `Tool "${toolName}" was cancelled.`,
+        isError: true,
+        status: "cancelled",
+        metadata: { reason: "cancelled" },
+    };
+}
+export function isSubagentLifecycleTool(name) {
+    return name === "subagent"
+        || name === "spawn_agent"
+        || name === "wait_agent"
+        || name === "send_input"
+        || name === "close_agent"
+        || name === "list_agents"
+        || name === "run_workflow"
+        || name === "wait_workflow"
+        // Legacy names: still present in transcripts recorded before the tools
+        // were removed (2026-07-06); forked children must not inherit their
+        // dangling tool_calls either.
+        || name === "agent_team"
+        || name === "agent_batch";
+}

package/dist/agent/update-queue.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wake-latched update queue shared by the agent run loop: tool updates,
+ * subagent deliveries and workflow completions all park here until the loop
+ * is ready to drain them.
+ */
+/** Exported for tests: the wake latch below is easiest to pin directly. */
+export declare function createUpdateQueue<T>(): {
+    push(item: T): void;
+    drain(): T[];
+    hasItems(): boolean;
+    wait(signal?: AbortSignal): Promise<"woken" | "aborted">;
+    wake(): void;
+};