@bubblebrain-ai/bubble 0.0.4 → 0.0.5

package/dist/provider.d.ts

@@ -3,9 +3,9 @@
  *
  * Works with OpenRouter, OpenAI, DeepSeek, Google, Groq, Together, and local OpenAI-compatible endpoints.
  */
-import type { Message, Provider, StreamChunk, ThinkingLevel } from "./types.js";
+import type { Provider, ProviderMessage, StreamChunk, ThinkingLevel } from "./types.js";
 type ReasoningContentEcho = "tool_calls" | "all";
-export declare function toChatCompletionsMessage(message: Message, options?: {
+export declare function toChatCompletionsMessage(message: ProviderMessage, options?: {
     reasoningContentEcho?: ReasoningContentEcho;
 }): Record<string, unknown>;
 export interface ProviderInstanceOptions {
@@ -21,11 +21,10 @@ export declare function normalizeToolArgs(raw: string): string;
 /**
  * Convert an OpenAI-compatible chat-completions stream into our internal StreamChunk events.
  *
- * Multi-tool-call streams are buffered by `index` and emitted in index order at
- * `finish_reason === "tool_calls"`, so the agent layer always sees a clean
- * (isStart -> args -> isEnd) sequence per call. This matters for providers like
- * Kimi K2.5 that emit several parallel tool calls per assistant turn -- the
- * previous single-slot implementation silently dropped every call but the last.
+ * Multi-tool-call streams are tracked by `index`, but tool-call starts and
+ * argument deltas are emitted as soon as they arrive so the TUI can render
+ * partial write previews before the tool executes. End events are still flushed
+ * in index order to keep multi-call turns deterministic.
  */
 export declare function translateOpenAIStream(stream: AsyncIterable<any>): AsyncIterable<StreamChunk>;
 export {};

package/dist/provider.js

@@ -5,6 +5,7 @@
  */
 import OpenAI from "openai";
 import { createOpenAICodexProvider, isOpenAICodexBaseUrl } from "./provider-openai-codex.js";
+import { createProviderProtocolArtifactFilter } from "./provider-artifacts.js";
 import { resolveProviderRequestConfig } from "./provider-transform.js";
 export function toChatCompletionsMessage(message, options = {}) {
     const reasoningContentEcho = options.reasoningContentEcho ?? "tool_calls";
@@ -189,14 +190,14 @@ function extractBalancedJson(s, start) {
 /**
  * Convert an OpenAI-compatible chat-completions stream into our internal StreamChunk events.
  *
- * Multi-tool-call streams are buffered by `index` and emitted in index order at
- * `finish_reason === "tool_calls"`, so the agent layer always sees a clean
- * (isStart -> args -> isEnd) sequence per call. This matters for providers like
- * Kimi K2.5 that emit several parallel tool calls per assistant turn -- the
- * previous single-slot implementation silently dropped every call but the last.
+ * Multi-tool-call streams are tracked by `index`, but tool-call starts and
+ * argument deltas are emitted as soon as they arrive so the TUI can render
+ * partial write previews before the tool executes. End events are still flushed
+ * in index order to keep multi-call turns deterministic.
  */
 export async function* translateOpenAIStream(stream) {
     const toolCalls = new Map();
+    const textFilter = createProviderProtocolArtifactFilter();
     function* flushToolCalls() {
         if (toolCalls.size === 0)
             return;
@@ -204,13 +205,34 @@ export async function* translateOpenAIStream(stream) {
         for (const [, entry] of sorted) {
             if (!entry.id || !entry.name)
                 continue;
-            const args = normalizeToolArgs(entry.args);
-            yield { type: "tool_call", id: entry.id, name: entry.name, arguments: "", isStart: true, isEnd: false };
-            yield { type: "tool_call", id: entry.id, name: entry.name, arguments: args, isStart: false, isEnd: false };
-            yield { type: "tool_call", id: entry.id, name: entry.name, arguments: "", isStart: false, isEnd: true };
+            if (!entry.started) {
+                yield { type: "tool_call", id: entry.id, name: entry.name, arguments: "", isStart: true, isEnd: false };
+                entry.started = true;
+                if (entry.args) {
+                    yield { type: "tool_call", id: entry.id, name: entry.name, arguments: entry.args, isStart: false, isEnd: false };
+                }
+            }
+            yield {
+                type: "tool_call",
+                id: entry.id,
+                name: entry.name,
+                arguments: "",
+                argumentsFull: normalizeToolArgs(entry.args),
+                isStart: false,
+                isEnd: true,
+            };
         }
         toolCalls.clear();
     }
+    function* startToolCallIfReady(entry) {
+        if (entry.started || !entry.id || !entry.name)
+            return;
+        entry.started = true;
+        yield { type: "tool_call", id: entry.id, name: entry.name, arguments: "", isStart: true, isEnd: false };
+        if (entry.args) {
+            yield { type: "tool_call", id: entry.id, name: entry.name, arguments: entry.args, isStart: false, isEnd: false };
+        }
+    }
     for await (const chunk of stream) {
         const delta = chunk.choices?.[0]?.delta;
         const usage = chunk.usage;
@@ -240,12 +262,16 @@ export async function* translateOpenAIStream(stream) {
                     yield { type: "reasoning_delta", content: thinkMatch[1] };
                 }
                 const remaining = delta.content.replace(/<think>[\s\S]*?<\/think>/, "");
-                if (remaining) {
-                    yield { type: "text", content: remaining };
+                const cleaned = textFilter.push(remaining);
+                if (cleaned) {
+                    yield { type: "text", content: cleaned };
                 }
             }
             else {
-                yield { type: "text", content: delta.content };
+                const cleaned = textFilter.push(delta.content);
+                if (cleaned) {
+                    yield { type: "text", content: cleaned };
+                }
             }
         }
         if (delta?.tool_calls) {
@@ -253,15 +279,28 @@ export async function* translateOpenAIStream(stream) {
                 const idx = typeof tc.index === "number" ? tc.index : 0;
                 let entry = toolCalls.get(idx);
                 if (!entry) {
-                    entry = { id: "", name: "", args: "" };
+                    entry = { id: "", name: "", args: "", started: false };
                     toolCalls.set(idx, entry);
                 }
                 if (tc.id)
                     entry.id = tc.id;
                 if (tc.function?.name)
                     entry.name = tc.function.name;
-                if (typeof tc.function?.arguments === "string")
-                    entry.args += tc.function.arguments;
+                yield* startToolCallIfReady(entry);
+                if (typeof tc.function?.arguments === "string" && tc.function.arguments) {
+                    const merged = mergeToolArgumentDelta(entry.args, tc.function.arguments);
+                    entry.args = merged.args;
+                    if (entry.started && merged.delta) {
+                        yield {
+                            type: "tool_call",
+                            id: entry.id,
+                            name: entry.name,
+                            arguments: merged.delta,
+                            isStart: false,
+                            isEnd: false,
+                        };
+                    }
+                }
             }
         }
         const finishReason = chunk.choices?.[0]?.finish_reason;
@@ -269,5 +308,28 @@ export async function* translateOpenAIStream(stream) {
             yield* flushToolCalls();
         }
     }
+    const remainingText = textFilter.flush();
+    if (remainingText) {
+        yield { type: "text", content: remainingText };
+    }
     yield* flushToolCalls();
 }
+function mergeToolArgumentDelta(current, incoming) {
+    if (!current)
+        return { args: incoming, delta: incoming };
+    if (!incoming)
+        return { args: current, delta: "" };
+    // Standard OpenAI-compatible streams send incremental argument deltas. Some
+    // providers send cumulative snapshots instead. If the incoming chunk already
+    // contains what we have, emit only the new suffix so downstream state remains
+    // append-only.
+    if (incoming.startsWith(current)) {
+        return { args: incoming, delta: incoming.slice(current.length) };
+    }
+    // Repeated identical snapshots should not duplicate the TUI preview or final
+    // JSON arguments.
+    if (incoming === current || current.endsWith(incoming)) {
+        return { args: current, delta: "" };
+    }
+    return { args: current + incoming, delta: incoming };
+}

package/dist/session-log.js

@@ -193,6 +193,8 @@ function normalizeMessageToEntries(message, id, timestamp) {
         }
         case "tool":
             return [{ id, type: "tool_result", message, timestamp }];
+        case "meta":
+            return [];
         case "system":
             return [{
                     id,
@@ -241,7 +243,7 @@ function pruneIncompleteTail(messages) {
     let sawNonUserInCurrentTurn = false;
     for (let i = 0; i < messages.length; i++) {
         const message = messages[i];
-        if (message.role === "system")
+        if (message.role === "system" || message.role === "meta")
             continue;
         if (message.role === "user") {
             currentTurnStart = i;

package/dist/system-prompt.d.ts

@@ -30,5 +30,7 @@ export interface SystemPromptOptions {
     skills?: SkillSummary[];
     /** Prompt-visible memory guidance and summaries */
     memoryPrompt?: string;
+    /** Durable child-agent profile prompt used for subagents. */
+    agentProfilePrompt?: string;
 }
 export declare function buildSystemPrompt(options?: SystemPromptOptions): string;

package/dist/tools/agent-lifecycle.d.ts

@@ -0,0 +1,6 @@
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createSpawnAgentTool(): ToolRegistryEntry;
+export declare function createWaitAgentTool(): ToolRegistryEntry;
+export declare function createSendInputTool(): ToolRegistryEntry;
+export declare function createCloseAgentTool(): ToolRegistryEntry;
+export declare function createAgentLifecycleTools(): ToolRegistryEntry[];

package/dist/tools/agent-lifecycle.js

@@ -0,0 +1,355 @@
+import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
+export function createSpawnAgentTool() {
+    return {
+        name: "spawn_agent",
+        readOnly: true,
+        effect: "read",
+        description: [
+            "Start a child subagent in the background and return its agent_id plus random nickname.",
+            "Use this for Codex-style delegation. The child has an independent thread; call wait_agent later to collect its result.",
+            "When the user asks to use a subagent, spawn first with a clear task instead of doing the delegated investigation yourself.",
+            "After spawning, do not duplicate the same delegated work locally; either wait for the child or do clearly non-overlapping work.",
+            "agent_type defaults to default. Built-in types include default, explorer, and worker.",
+        ].join(" "),
+        parameters: {
+            type: "object",
+            properties: {
+                agent_type: { type: "string", description: "Subagent profile or role name. Defaults to default." },
+                agent: { type: "string", description: "Alias for agent_type." },
+                message: { type: "string", description: "Initial task for the subagent." },
+                task: { type: "string", description: "Alias for message." },
+                fork_context: { type: "boolean", description: "When true, copy recent parent conversation into the child thread." },
+                agentScope: {
+                    type: "string",
+                    enum: ["user", "project", "both"],
+                    description: "Which profile locations to load. Defaults to user profiles plus built-ins.",
+                },
+                allowProjectAgents: {
+                    type: "boolean",
+                    description: "Required to run profiles loaded from project-local .bubble/agents.",
+                },
+                approval: {
+                    type: "string",
+                    enum: ["fail", "disabled"],
+                    description: "How this child handles tools that need interactive approval.",
+                },
+            },
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.spawnSubAgent) {
+                return toolRuntimeMissing("spawn_agent");
+            }
+            const message = stringArg(args.message) ?? stringArg(args.task);
+            if (!message) {
+                return { content: "Error: spawn_agent requires message or task.", isError: true };
+            }
+            const profileName = stringArg(args.agent_type) ?? stringArg(args.agent) ?? "default";
+            const resolved = resolveProfile(ctx.cwd, profileName, parseScope(args.agentScope), args.allowProjectAgents === true);
+            if ("error" in resolved)
+                return resolved.error;
+            if (resolved.profile.mode !== "readonly") {
+                return unsupportedProfile(resolved.profile);
+            }
+            try {
+                const snapshot = await ctx.agent.spawnSubAgent(message, ctx.cwd, {
+                    profile: resolved.profile,
+                    parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
+                    approval: parseApproval(args.approval),
+                    abortSignal: ctx.abortSignal,
+                    forkContext: args.fork_context === true,
+                });
+                return formatLifecycleResult("spawn_agent", [snapshot], [
+                    `Spawned ${snapshot.nickname} (${snapshot.agentName})`,
+                    `agent_id: ${snapshot.agentId}`,
+                    `status: ${snapshot.status}`,
+                    `next: call wait_agent for ${snapshot.agentId} to collect the delegated result`,
+                ]);
+            }
+            catch (error) {
+                return toolError("spawn_agent", error);
+            }
+        },
+    };
+}
+export function createWaitAgentTool() {
+    return {
+        name: "wait_agent",
+        readOnly: true,
+        effect: "read",
+        description: [
+            "Wait for one or more spawned subagents to reach a final status and return snapshots.",
+            "If the wait times out while children are still running, call wait_agent again with a longer timeout instead of redoing the same delegated work locally.",
+        ].join(" "),
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "A single agent id to wait for." },
+                agent_ids: {
+                    type: "array",
+                    description: "Agent ids to wait for. If omitted, waits for any active subagent.",
+                    items: { type: "string" },
+                },
+                timeout_ms: { type: "number", description: "Maximum wait time in milliseconds. Defaults to 30000." },
+            },
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.waitSubAgents) {
+                return toolRuntimeMissing("wait_agent");
+            }
+            const agentIds = normalizeAgentIds(args.agent_ids, args.agent_id);
+            try {
+                const snapshots = await ctx.agent.waitSubAgents({
+                    agentIds,
+                    timeoutMs: typeof args.timeout_ms === "number" ? args.timeout_ms : undefined,
+                });
+                if (snapshots.length === 0) {
+                    return {
+                        content: "No subagents reached a final status before the timeout.",
+                        status: "timeout",
+                        metadata: { kind: "subagent", mode: "lifecycle", subagents: [] },
+                    };
+                }
+                if (snapshots.some((snapshot) => !isFinalSnapshotStatus(snapshot.status))) {
+                    return formatLifecycleResult("wait_agent", snapshots, [
+                        "wait_agent timed out before a delegated result was ready.",
+                        "The subagent is still running; call wait_agent again with a longer timeout instead of duplicating the same work locally.",
+                        "",
+                        ...snapshots.flatMap((snapshot) => [...formatSnapshot(snapshot), ""]),
+                    ]);
+                }
+                return formatLifecycleResult("wait_agent", snapshots);
+            }
+            catch (error) {
+                return toolError("wait_agent", error);
+            }
+        },
+    };
+}
+export function createSendInputTool() {
+    return {
+        name: "send_input",
+        readOnly: true,
+        effect: "read",
+        description: "Send a follow-up message to an existing subagent thread. If it is still running, pass interrupt:true to cancel and redirect it.",
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "Target subagent id." },
+                message: { type: "string", description: "Follow-up message." },
+                task: { type: "string", description: "Alias for message." },
+                interrupt: { type: "boolean", description: "Cancel a running child before applying this input." },
+            },
+            required: ["agent_id"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.sendSubAgentInput) {
+                return toolRuntimeMissing("send_input");
+            }
+            const agentId = stringArg(args.agent_id);
+            const message = stringArg(args.message) ?? stringArg(args.task);
+            if (!agentId || !message) {
+                return { content: "Error: send_input requires agent_id and message.", isError: true };
+            }
+            try {
+                const snapshot = await ctx.agent.sendSubAgentInput(agentId, message, ctx.cwd, {
+                    interrupt: args.interrupt === true,
+                    parentToolCallId: ctx.toolCall?.id,
+                    abortSignal: ctx.abortSignal,
+                });
+                return formatLifecycleResult("send_input", [snapshot], [
+                    `Sent input to ${snapshot.nickname} (${snapshot.agentName})`,
+                    `agent_id: ${snapshot.agentId}`,
+                    `status: ${snapshot.status}`,
+                ]);
+            }
+            catch (error) {
+                return toolError("send_input", error);
+            }
+        },
+    };
+}
+export function createCloseAgentTool() {
+    return {
+        name: "close_agent",
+        readOnly: true,
+        effect: "read",
+        description: "Close a spawned subagent only when the delegated task is cancelled, stale, or no longer needed. Running children are cancelled before closing; do not close a child just because you started doing the same delegated work locally.",
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "Subagent id to close." },
+            },
+            required: ["agent_id"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.closeSubAgent) {
+                return toolRuntimeMissing("close_agent");
+            }
+            const agentId = stringArg(args.agent_id);
+            if (!agentId) {
+                return { content: "Error: close_agent requires agent_id.", isError: true };
+            }
+            try {
+                const snapshot = await ctx.agent.closeSubAgent(agentId);
+                return formatLifecycleResult("close_agent", [snapshot], [
+                    `Closed ${snapshot.nickname} (${snapshot.agentName})`,
+                    `agent_id: ${snapshot.agentId}`,
+                    `status: ${snapshot.status}`,
+                ]);
+            }
+            catch (error) {
+                return toolError("close_agent", error);
+            }
+        },
+    };
+}
+export function createAgentLifecycleTools() {
+    return [
+        createSpawnAgentTool(),
+        createWaitAgentTool(),
+        createSendInputTool(),
+        createCloseAgentTool(),
+    ];
+}
+function resolveProfile(cwd, name, scope, allowProjectAgents) {
+    const discovered = discoverAgentProfiles(cwd, scope);
+    const profile = findAgentProfile(discovered.profiles, name);
+    if (!profile) {
+        const available = discovered.profiles.map((item) => item.name).sort().join(", ") || "none";
+        return {
+            error: {
+                content: `Error: unknown subagent profile "${name}". Available profiles: ${available}`,
+                isError: true,
+            },
+        };
+    }
+    if (profile.source === "project" && !allowProjectAgents) {
+        return {
+            error: {
+                content: [
+                    `Blocked: subagent profile "${profile.name}" was loaded from project-local .bubble/agents.`,
+                    "Pass allowProjectAgents: true only when you trust this repository's agent profile prompts.",
+                ].join("\n"),
+                isError: true,
+                status: "blocked",
+            },
+        };
+    }
+    return { profile };
+}
+function formatLifecycleResult(toolName, snapshots, header) {
+    const lines = header ?? [`${toolName}: ${snapshots.length} subagent${snapshots.length === 1 ? "" : "s"}`];
+    if (!header)
+        lines.push("");
+    if (!header) {
+        for (const snapshot of snapshots) {
+            lines.push(...formatSnapshot(snapshot), "");
+        }
+    }
+    return {
+        content: lines.join("\n").trim(),
+        status: lifecycleStatus(toolName, snapshots),
+        isError: snapshots.length > 0 && snapshots.every((snapshot) => snapshot.status === "failed" || snapshot.status === "blocked"),
+        metadata: {
+            kind: "subagent",
+            mode: "lifecycle",
+            subagents: snapshots.map(snapshotToMetadata),
+        },
+    };
+}
+function lifecycleStatus(toolName, snapshots) {
+    if (toolName === "spawn_agent" || toolName === "send_input" || toolName === "close_agent") {
+        return "success";
+    }
+    if (snapshots.some((snapshot) => !isFinalSnapshotStatus(snapshot.status))) {
+        return "timeout";
+    }
+    return snapshots.every((snapshot) => snapshot.status === "completed" || snapshot.status === "closed") ? "success" : "partial";
+}
+function isFinalSnapshotStatus(status) {
+    return status === "completed"
+        || status === "failed"
+        || status === "blocked"
+        || status === "cancelled"
+        || status === "closed";
+}
+function formatSnapshot(snapshot) {
+    const label = `${snapshot.nickname} (${snapshot.agentName})`;
+    const lines = [
+        `## ${label}`,
+        `agent_id: ${snapshot.agentId}`,
+        `status: ${snapshot.status}`,
+        `task: ${snapshot.task}`,
+    ];
+    if (snapshot.summary) {
+        lines.push("", "Summary:", snapshot.summary);
+    }
+    else if (snapshot.status === "completed") {
+        lines.push("", "Summary: (no final text summary was produced)");
+    }
+    if (snapshot.toolNotes.length > 0) {
+        lines.push("", "Recent tool notes:", ...snapshot.toolNotes.slice(-8).map((note) => `- ${note}`));
+    }
+    if (snapshot.error) {
+        lines.push("", `Error: ${snapshot.error}`);
+    }
+    return lines;
+}
+function snapshotToMetadata(snapshot) {
+    return {
+        subAgentId: snapshot.agentId,
+        agentName: snapshot.agentName,
+        nickname: snapshot.nickname,
+        status: snapshot.status === "closed" ? "cancelled" : snapshot.status,
+        profileSource: snapshot.profileSource,
+        task: snapshot.task,
+        summary: snapshot.summary,
+        toolNotes: snapshot.toolNotes,
+        usage: snapshot.usage,
+        error: snapshot.error,
+    };
+}
+function unsupportedProfile(profile) {
+    return {
+        content: `Error: subagent profile "${profile.name}" uses mode "${profile.mode}", but this runtime only supports readonly lifecycle subagents.`,
+        isError: true,
+        status: "blocked",
+    };
+}
+function parseScope(value) {
+    return value === "project" || value === "both" ? value : "user";
+}
+function parseApproval(value) {
+    return value === "fail" || value === "disabled" ? value : undefined;
+}
+function normalizeAgentIds(value, single) {
+    const out = [];
+    if (typeof single === "string" && single.trim())
+        out.push(single.trim());
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (typeof item === "string" && item.trim())
+                out.push(item.trim());
+        }
+    }
+    return out.length > 0 ? [...new Set(out)] : undefined;
+}
+function stringArg(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function snapshotFallbackId() {
+    return `spawn_${Date.now().toString(36)}`;
+}
+function toolRuntimeMissing(name) {
+    return { content: `Error: ${name} requires an agent runtime`, isError: true };
+}
+function toolError(name, error) {
+    return {
+        content: `Error executing ${name}: ${error?.message || String(error)}`,
+        isError: true,
+    };
+}

package/dist/tools/bash.js

@@ -11,6 +11,8 @@ const MAX_OUTPUT = 50 * 1024;
 export function createBashTool(cwd, approval) {
     return {
         name: "bash",
+        effect: "unknown",
+        requiresApproval: true,
         description: "Execute a bash command in the working directory. Use timeout for long-running commands.",
         parameters: {
             type: "object",

package/dist/tools/edit-apply.d.ts

@@ -0,0 +1,25 @@
+export interface EditOperation {
+    oldText: string;
+    newText: string;
+}
+export type EditMatchMode = "exact" | "normalized-line";
+export interface EditMatchInfo {
+    editIndex: number;
+    mode: EditMatchMode;
+    start: number;
+    end: number;
+}
+export interface AppliedEditResult {
+    content: string;
+    normalizedOriginal: string;
+    normalizedNext: string;
+    bom: string;
+    lineEnding: "\n" | "\r\n";
+    matches: EditMatchInfo[];
+}
+export declare class EditApplyError extends Error {
+    readonly status: "no_match" | "blocked";
+    constructor(message: string, status?: "no_match" | "blocked");
+}
+export declare function applyEditsToContent(rawContent: string, edits: EditOperation[]): AppliedEditResult;
+export declare function formatEditMatchNotes(matches: EditMatchInfo[]): string;