bs-agent 0.0.28 → 0.0.29

package/README.md

@@ -10,8 +10,8 @@ streaming support.
 - ⚛️ **React bindings** — hooks & context for chat UIs with session management
 - 💬 **Multi-turn** — session-based conversations with persistent history
 - 🛑 **Abort** — cancel any streaming request mid-flight
-- 🐛 **Debug data** — structured debug entries for every tool call, reasoning
-  step & handoff
+- 🐛 **Inline debug info** — tool calls, reasoning, handoffs & errors as
+  message parts
 - 📦 **Zero extra deps** — native `fetch` + `ReadableStream`, only `zod` as a
   dependency
 
@@ -318,7 +318,7 @@ function App() {
 ## `useAgent` Hook
 
 The main hook for interacting with an agent. Manages messages, streaming,
-sessions, and debug data.
+and sessions.
 
 ```tsx
 import { useAgent } from "@buildship/agent/react";
@@ -335,7 +335,6 @@ function ChatPage() {
     switchSession, // (sessionId?) => void — switch to a session (or create new)
     deleteSession, // (sessionId) => void — delete a session
     addOptimisticMessage, // (input) => void — add a user message immediately
-    debugData, // Record<string, DebugDataType> — debug entries by execution ID
   } = useAgent(
     "agent-id",
     "https://your-project.buildship.run/executeAgent/AGENT_ID",
@@ -564,8 +563,8 @@ Messages can contain rich, interleaved content via `parts`:
 type Message = {
   role: "user" | "agent";
   content: string; // Full text content
-  parts?: MessagePart[]; // Rich content (text + widgets)
-  executionId?: string; // Links to debug data
+  parts?: MessagePart[]; // Rich content (text, widgets, tool calls, reasoning, etc.)
+  executionId?: string; // Execution ID for this turn
   attachments?: Array<ImagePart | FilePart>; // Multimodal user message attachments
 };
 
@@ -579,11 +578,26 @@ type MessagePart =
       paused?: boolean;
       status?: "pending" | "submitted";
       result?: any;
-    };
+    }
+  | {
+      type: "tool_call";
+      toolName: string;
+      callId: string;
+      toolType: ToolType;
+      status: "progress" | "complete" | "error";
+      inputs?: unknown;
+      output?: unknown;
+      error?: string;
+      serverName?: string; // MCP server name
+    }
+  | { type: "reasoning"; reasoning: string; index?: number }
+  | { type: "handoff"; agentName: string }
+  | { type: "run_error"; message: string; code?: string };
 ```
 
 > **Tip:** When rendering messages, iterate over `msg.parts` instead of
-> `msg.content` to get both text and widgets interleaved in the correct order.
+> `msg.content` to get text, widgets, tool calls, reasoning, handoffs, and
+> errors interleaved in chronological order.
 
 ## Sessions
 
@@ -618,48 +632,27 @@ type Session = {
 };
 ```
 
-## Debug Data
+## Inline Debug Info
 
-Debug data captures structured information about every tool call, reasoning
-step, and agent handoff during execution. It's stored by `executionId` (matching
-the user message it belongs to).
+Tool calls, reasoning, agent handoffs, and errors are all embedded directly in
+the agent message's `parts` array — no separate debug state. Filter by `type`
+to render them:
 
 ```tsx
-const { debugData, messages } = useAgent(...);
-
-// Get debug data for a specific message
-const messageDebug = debugData[message.executionId];
-
-// Each entry is one of:
-type DebugDataType = Array<ToolExecutionItem | ReasoningItem | HandoffItem>;
+const { messages } = useAgent(...);
+
+// Get debug parts from an agent message
+const debugParts = message.parts?.filter(
+  (p) =>
+    p.type === "tool_call" ||
+    p.type === "reasoning" ||
+    p.type === "handoff" ||
+    p.type === "run_error",
+);
 ```
 
-### Debug Entry Types
-
-```ts
-type ToolExecutionItem = {
-  itemType: "tool_call";
-  toolName: string;
-  callId: string;
-  toolType: ToolType; // "flow" | "node" | "mcp" | "client" | "builtin" | "agent"
-  status: "progress" | "complete" | "error";
-  inputs?: unknown;
-  output?: unknown;
-  error?: string;
-  serverName?: string; // For MCP tools
-};
-
-type ReasoningItem = {
-  itemType: "reasoning";
-  reasoning: string;
-  index?: number;
-};
-
-type HandoffItem = {
-  itemType: "handoff";
-  agentName: string;
-};
-```
+See the [Message Parts](#message-parts) section above for the full type
+definitions of each part.
 
 ## React API Reference
 
@@ -667,7 +660,7 @@ type HandoffItem = {
 
 | Hook                                       | Description                                      |
 | ------------------------------------------ | ------------------------------------------------ |
-| `useAgent(agentId, agentUrl, accessKey?)`  | Main hook — messages, streaming, sessions, debug |
+| `useAgent(agentId, agentUrl, accessKey?)`  | Main hook — messages, streaming, sessions        |
 | `useAgentContext(agentId, agentUrl, key?)` | Context-based alternative for multi-agent setups |
 | `useClientTool(agentId, config)`           | Register a client tool (headless or widget)      |
 
@@ -675,7 +668,7 @@ type HandoffItem = {
 
 | Component                                   | Description                                        |
 | ------------------------------------------- | -------------------------------------------------- |
-| `<AgentContextProvider>`                    | Provides shared agent state (sessions, debug data) |
+| `<AgentContextProvider>`                    | Provides shared agent state (sessions)             |
 | `<ToolRenderer agentId={id} part={part} />` | Renders a widget tool from a message part          |
 
 ### Utilities
@@ -708,7 +701,7 @@ function App() {
 }
 
 function Chat() {
-  const { messages, handleSend, inProgress, resumeTool, abort, debugData } =
+  const { messages, handleSend, inProgress, resumeTool, abort } =
     useAgent(AGENT_ID, AGENT_URL);
   const [input, setInput] = useState("");
 
@@ -748,13 +741,46 @@ function Chat() {
       {messages.map((msg, i) => (
         <div key={i}>
           <strong>{msg.role}:</strong>
-          {msg.parts?.map((part) =>
-            part.type === "text" ? (
-              <span key={part.firstSequence}>{part.text}</span>
-            ) : (
-              <ToolRenderer key={part.callId} agentId={AGENT_ID} part={part} />
-            ),
-          ) ?? msg.content}
+          {msg.parts?.map((part, j) => {
+            if (part.type === "text") {
+              return <span key={j}>{part.text}</span>;
+            }
+            if (part.type === "widget") {
+              return <ToolRenderer key={j} agentId={AGENT_ID} part={part} />;
+            }
+            if (part.type === "tool_call") {
+              return (
+                <div key={j} style={{ opacity: 0.7, fontSize: "0.85em" }}>
+                  🔧 {part.toolName}{" "}
+                  {part.status === "progress"
+                    ? "running..."
+                    : part.status === "error"
+                      ? `failed: ${part.error}`
+                      : "✓"}
+                </div>
+              );
+            }
+            if (part.type === "reasoning") {
+              return (
+                <div key={j} style={{ fontStyle: "italic", opacity: 0.6 }}>
+                  💭 {part.reasoning}
+                </div>
+              );
+            }
+            if (part.type === "handoff") {
+              return (
+                <div key={j}>→ Handed off to {part.agentName}</div>
+              );
+            }
+            if (part.type === "run_error") {
+              return (
+                <div key={j} style={{ color: "red" }}>
+                  ⚠️ {part.message}
+                </div>
+              );
+            }
+            return null;
+          }) ?? msg.content}
         </div>
       ))}
 

package/dist/react/index.cjs

@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/react/index.ts
 var react_exports = {};
 __export(react_exports, {
-  AGENT_DEBUG_DATA_KEY: () => AGENT_DEBUG_DATA_KEY,
   AGENT_SESSIONS_KEY: () => AGENT_SESSIONS_KEY,
   AgentContextProvider: () => AgentContextProvider,
   AgentToolContext: () => AgentToolContext,
@@ -45,7 +44,6 @@ var import_react3 = require("react");
 
 // src/react/constants.ts
 var AGENT_SESSIONS_KEY = "buildship:agent:conversations";
-var AGENT_DEBUG_DATA_KEY = "buildship:agent:debug";
 var DEFAULT_SESSION_NAME = "New Chat";
 var TEMPORARY_SESSION_ID = "sess_temp";
 
@@ -151,122 +149,6 @@ var useSessionUtils = (agentId, allSessions, setAllSessions, currentSessionId, s
   };
 };
 
-// src/react/debug-handlers.ts
-var createDebugHandlers = (setDebugData) => {
-  const handleStreamEvent = (event) => {
-    const executionId = event.meta.executionId;
-    switch (event.type) {
-      case "tool_call_start": {
-        const { callId, toolName, toolType, inputs, serverName } = event.data;
-        setDebugData((prev) => ({
-          ...prev,
-          [executionId]: [
-            ...prev[executionId] || [],
-            {
-              itemType: "tool_call",
-              toolName,
-              callId,
-              toolType,
-              status: "progress",
-              inputs,
-              serverName
-            }
-          ]
-        }));
-        break;
-      }
-      case "tool_call_end": {
-        const { callId, result, error } = event.data;
-        setDebugData((prev) => {
-          const currentData = [...prev[executionId] || []];
-          for (let i = currentData.length - 1; i >= 0; i--) {
-            if (currentData[i].itemType === "tool_call") {
-              const toolItem = currentData[i];
-              if (toolItem.callId === callId) {
-                currentData[i] = {
-                  ...toolItem,
-                  status: error ? "error" : "complete",
-                  output: result,
-                  error
-                };
-                break;
-              }
-            }
-          }
-          return {
-            ...prev,
-            [executionId]: currentData
-          };
-        });
-        break;
-      }
-      case "reasoning_delta": {
-        const { delta, index } = event.data;
-        setDebugData((prev) => {
-          const currentData = [...prev[executionId] || []];
-          let existingItemIndex = -1;
-          for (let i = currentData.length - 1; i >= 0; i--) {
-            const item = currentData[i];
-            if (item.itemType === "reasoning" && item.index === index) {
-              existingItemIndex = i;
-              break;
-            }
-          }
-          if (existingItemIndex === -1) {
-            currentData.push({ itemType: "reasoning", reasoning: delta, index });
-          } else {
-            const hasInterleavedItems = currentData.slice(existingItemIndex + 1).some((item) => item.itemType !== "reasoning");
-            if (hasInterleavedItems) {
-              currentData.push({ itemType: "reasoning", reasoning: delta, index });
-            } else {
-              currentData[existingItemIndex] = {
-                itemType: "reasoning",
-                reasoning: currentData[existingItemIndex].reasoning + delta,
-                index
-              };
-            }
-          }
-          return {
-            ...prev,
-            [executionId]: currentData
-          };
-        });
-        break;
-      }
-      case "agent_handoff": {
-        setDebugData((prev) => ({
-          ...prev,
-          [executionId]: [
-            ...prev[executionId] || [],
-            {
-              itemType: "handoff",
-              agentName: event.data.agentName
-            }
-          ]
-        }));
-        break;
-      }
-      case "run_error": {
-        setDebugData((prev) => ({
-          ...prev,
-          [executionId]: [
-            ...prev[executionId] || [],
-            {
-              itemType: "run_error",
-              message: event.data.message,
-              code: event.data.code
-            }
-          ]
-        }));
-        break;
-      }
-    }
-  };
-  return {
-    handleStreamEvent
-  };
-};
-
 // src/react/client-tools.ts
 var import_react2 = require("react");
 var import_zod = require("zod");
@@ -371,7 +253,7 @@ function updateAgentMessageParts(parts, newPart) {
 }
 
 // src/react/stream-callbacks.ts
-function buildStreamCallbacks(deps, debugKey) {
+function buildStreamCallbacks(deps) {
   const {
     setMessages,
     setInProgress,
@@ -386,16 +268,10 @@ function buildStreamCallbacks(deps, debugKey) {
     onComplete: () => {
       console.log("Agent closed");
       setInProgress(false);
-      if (syncSessionRef.current) {
-        syncSessionRef.current(messagesRef.current);
-      }
     },
     onError: (error) => {
       console.log("Agent error", error);
       setInProgress(false);
-      if (syncSessionRef.current) {
-        syncSessionRef.current(messagesRef.current);
-      }
     },
     onEvent: (event) => {
       if (event.type === "text_delta") {
@@ -409,33 +285,36 @@ function buildStreamCallbacks(deps, debugKey) {
         );
       } else if (event.type === "tool_call_start" && event.data.toolType === "client") {
         handleClientToolCall(event, setMessages, syncSessionRef, toolContext, agentId);
-        if (debugKey) {
-          const debugMeta = { ...event.meta, executionId: debugKey };
-          deps.debugHandlers.handleStreamEvent({
-            ...event,
-            meta: debugMeta
-          });
-          if (!event.data.paused) {
-            deps.debugHandlers.handleStreamEvent({
-              type: "tool_call_end",
-              data: {
-                callId: event.data.callId,
-                toolName: event.data.toolName,
-                toolType: event.data.toolType
-              },
-              meta: debugMeta
-            });
-          }
-        }
-      } else if (debugKey) {
-        deps.debugHandlers.handleStreamEvent({
-          ...event,
-          meta: { ...event.meta, executionId: debugKey }
-        });
+      } else if (event.type === "tool_call_start") {
+        handleToolCallStart(event, setMessages, syncSessionRef);
+      } else if (event.type === "tool_call_end") {
+        handleToolCallEnd(event, setMessages, syncSessionRef);
+      } else if (event.type === "reasoning_delta") {
+        handleReasoningDelta(event, setMessages, syncSessionRef);
+      } else if (event.type === "agent_handoff") {
+        handleAgentHandoff(event, setMessages, syncSessionRef);
+      } else if (event.type === "run_error") {
+        handleRunError(event, setMessages, syncSessionRef);
       }
     }
   };
 }
+function ensureAgentMessage(prev, executionId) {
+  const last = prev[prev.length - 1];
+  if (last?.role === "agent") {
+    return [prev, last];
+  }
+  const newMsg = {
+    role: "agent",
+    content: "",
+    parts: [],
+    executionId
+  };
+  return [[...prev, newMsg], newMsg];
+}
+function replaceLastAgent(prev, updated) {
+  return [...prev.slice(0, -1), updated];
+}
 function handleTextDelta(event, setMessages, syncSessionRef, modifier, fullTextModifier, agentId) {
   const sequence = event.meta.sequence;
   const originalText = event.data;
@@ -556,11 +435,126 @@ function handleClientToolCall(event, setMessages, syncSessionRef, toolContext, a
     return updatedMessages;
   });
 }
+function handleToolCallStart(event, setMessages, syncSessionRef) {
+  const { callId, toolName, toolType, inputs, serverName } = event.data;
+  setMessages((prev) => {
+    const [msgs, agentMsg] = ensureAgentMessage(prev, event.meta.executionId);
+    const newPart = {
+      type: "tool_call",
+      toolName,
+      callId,
+      toolType,
+      status: "progress",
+      inputs,
+      serverName,
+      sequence: event.meta.sequence
+    };
+    const updated = {
+      ...agentMsg,
+      parts: [...agentMsg.parts || [], newPart]
+    };
+    const updatedMessages = replaceLastAgent(msgs, updated);
+    if (syncSessionRef.current) syncSessionRef.current(updatedMessages);
+    return updatedMessages;
+  });
+}
+function handleToolCallEnd(event, setMessages, syncSessionRef) {
+  const { callId, result, error } = event.data;
+  setMessages((prev) => {
+    const last = prev[prev.length - 1];
+    if (last?.role !== "agent" || !last.parts) return prev;
+    const updatedParts = [...last.parts];
+    for (let i = updatedParts.length - 1; i >= 0; i--) {
+      const part = updatedParts[i];
+      if (part.type === "tool_call" && part.callId === callId) {
+        updatedParts[i] = {
+          ...part,
+          status: error ? "error" : "complete",
+          output: result,
+          error
+        };
+        break;
+      }
+    }
+    const updated = { ...last, parts: updatedParts };
+    const updatedMessages = replaceLastAgent(prev, updated);
+    if (syncSessionRef.current) syncSessionRef.current(updatedMessages);
+    return updatedMessages;
+  });
+}
+function handleReasoningDelta(event, setMessages, syncSessionRef) {
+  const { delta, index } = event.data;
+  setMessages((prev) => {
+    const [msgs, agentMsg] = ensureAgentMessage(prev, event.meta.executionId);
+    const parts = [...agentMsg.parts || []];
+    let existingIdx = -1;
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const p = parts[i];
+      if (p.type === "reasoning" && p.index === index) {
+        existingIdx = i;
+        break;
+      }
+    }
+    if (existingIdx === -1) {
+      parts.push({ type: "reasoning", reasoning: delta, index, sequence: event.meta.sequence });
+    } else {
+      const hasInterleavedItems = parts.slice(existingIdx + 1).some((p) => p.type !== "reasoning");
+      if (hasInterleavedItems) {
+        parts.push({ type: "reasoning", reasoning: delta, index, sequence: event.meta.sequence });
+      } else {
+        const existing = parts[existingIdx];
+        parts[existingIdx] = {
+          ...existing,
+          reasoning: existing.reasoning + delta
+        };
+      }
+    }
+    const updated = { ...agentMsg, parts };
+    const updatedMessages = replaceLastAgent(msgs, updated);
+    if (syncSessionRef.current) syncSessionRef.current(updatedMessages);
+    return updatedMessages;
+  });
+}
+function handleAgentHandoff(event, setMessages, syncSessionRef) {
+  setMessages((prev) => {
+    const [msgs, agentMsg] = ensureAgentMessage(prev, event.meta.executionId);
+    const newPart = {
+      type: "handoff",
+      agentName: event.data.agentName,
+      sequence: event.meta.sequence
+    };
+    const updated = {
+      ...agentMsg,
+      parts: [...agentMsg.parts || [], newPart]
+    };
+    const updatedMessages = replaceLastAgent(msgs, updated);
+    if (syncSessionRef.current) syncSessionRef.current(updatedMessages);
+    return updatedMessages;
+  });
+}
+function handleRunError(event, setMessages, syncSessionRef) {
+  setMessages((prev) => {
+    const [msgs, agentMsg] = ensureAgentMessage(prev, event.meta.executionId);
+    const newPart = {
+      type: "run_error",
+      message: event.data.message,
+      code: event.data.code,
+      sequence: event.meta.sequence
+    };
+    const updated = {
+      ...agentMsg,
+      parts: [...agentMsg.parts || [], newPart]
+    };
+    const updatedMessages = replaceLastAgent(msgs, updated);
+    if (syncSessionRef.current) syncSessionRef.current(updatedMessages);
+    return updatedMessages;
+  });
+}
 
 // src/react/use-agent.ts
 function useAgent(agent, options) {
   const agentId = agent._agentId;
-  const { allSessions, setAllSessions, debugData, setDebugData } = useAgentGlobalState();
+  const { allSessions, setAllSessions } = useAgentGlobalState();
   const toolContext = (0, import_react3.useContext)(AgentToolContext);
   const [inProgress, setInProgress] = (0, import_react3.useState)(false);
   const [messages, setMessages] = (0, import_react3.useState)([]);
@@ -578,7 +572,6 @@ function useAgent(agent, options) {
     const initialSessionId = sessionUtils.getInitialSessionId();
     setCurrentSessionId(initialSessionId);
   }, [agentId]);
-  const debugHandlers = (0, import_react3.useMemo)(() => createDebugHandlers(setDebugData), [setDebugData]);
   (0, import_react3.useEffect)(() => {
     messagesRef.current = messages;
   }, [messages]);
@@ -611,7 +604,6 @@ function useAgent(agent, options) {
     async (input, runOptions) => {
       const isNewSession = !currentSessionId || currentSessionId === TEMPORARY_SESSION_ID;
       setInProgress(true);
-      const debugKey = runOptions?.optimisticExecutionId || messagesRef.current.findLast((m) => m.role === "user")?.executionId;
       const deps = {
         agentId,
         currentSessionId,
@@ -619,12 +611,11 @@ function useAgent(agent, options) {
         setMessages,
         setInProgress,
         syncSessionRef: sessionUtils.syncSessionRef,
-        debugHandlers,
         toolContext,
         textDeltaModifier: optionsRef.current?.textDeltaModifier,
         fullTextModifier: optionsRef.current?.fullTextModifier
       };
-      const callbacks = buildStreamCallbacks(deps, debugKey);
+      const callbacks = buildStreamCallbacks(deps);
       const executeOptions = {
         context: runOptions?.context,
         headers: runOptions?.additionalHeaders,
@@ -686,7 +677,7 @@ function useAgent(agent, options) {
         activeSessionRef.current = null;
       }
     },
-    [currentSessionId, sessionUtils, debugHandlers, agentId, toolContext, agent, getClientToolsMap]
+    [currentSessionId, sessionUtils, agentId, toolContext, agent, getClientToolsMap]
   );
   const handleSend = (0, import_react3.useCallback)(
     async (input, options2) => {
@@ -785,14 +776,6 @@ function useAgent(agent, options) {
         return updatedMessages;
       });
       const lastUserMessage = messagesRef.current.findLast((m) => m.role === "user");
-      const debugKey = lastUserMessage?.executionId;
-      if (debugKey) {
-        debugHandlers.handleStreamEvent({
-          type: "tool_call_end",
-          data: { callId, toolName: "", toolType: "client", result },
-          meta: { executionId: debugKey, sequence: 0 }
-        });
-      }
       await runAgent(void 0, {
         resumeToolCallId: callId,
         resumeToolResult: result,
@@ -801,7 +784,7 @@ function useAgent(agent, options) {
         context: lastUserMessage?.context ?? lastRunOptionsRef.current.context
       });
     },
-    [runAgent, sessionUtils.syncSessionRef, debugHandlers]
+    [runAgent, sessionUtils.syncSessionRef]
   );
   const addOptimisticMessage = (0, import_react3.useCallback)(
     (input) => {
@@ -857,8 +840,7 @@ function useAgent(agent, options) {
     sessionId: currentSessionId,
     switchSession: sessionUtils.switchSession,
     deleteSession: sessionUtils.deleteSession,
-    sessions: sessionUtils.sessionsList,
-    debugData
+    sessions: sessionUtils.sessionsList
   };
 }
 
@@ -1466,10 +1448,6 @@ function AgentContextProvider({ children }) {
   const toolRegistryRef = (0, import_react5.useRef)(/* @__PURE__ */ new Map());
   const [, forceUpdate] = (0, import_react5.useState)({});
   const [allSessions, setAllSessions] = useSyncedLocalStorage(AGENT_SESSIONS_KEY, {});
-  const [debugData, setDebugData] = useSyncedLocalStorage(
-    AGENT_DEBUG_DATA_KEY,
-    {}
-  );
   const initializeAgent = (0, import_react5.useCallback)(
     (agentId, agentUrl, accessKey, options) => {
       const existing = activeAgentsRef.current.get(agentId);
@@ -1526,8 +1504,6 @@ function AgentContextProvider({ children }) {
       getRunner,
       allSessions,
       setAllSessions,
-      debugData,
-      setDebugData,
       runnersRef,
       listenersRef
     }),
@@ -1536,9 +1512,7 @@ function AgentContextProvider({ children }) {
       registerRunner,
       getRunner,
       allSessions,
-      setAllSessions,
-      debugData,
-      setDebugData
+      setAllSessions
     ]
   );
   const toolContextValue = (0, import_react5.useMemo)(
@@ -1623,7 +1597,6 @@ function useAgentContext(agentId, agentUrl, accessKey, options) {
       inProgress: false,
       sessionId: "",
       sessions: [],
-      debugData: {},
       handleSend: async () => {
       },
       resumeTool: async () => {
@@ -1648,9 +1621,7 @@ function useAgentGlobalState() {
   }
   return {
     allSessions: context.allSessions,
-    setAllSessions: context.setAllSessions,
-    debugData: context.debugData,
-    setDebugData: context.setDebugData
+    setAllSessions: context.setAllSessions
   };
 }
 
@@ -1699,7 +1670,6 @@ function ToolRenderer({ agentId, part }) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AGENT_DEBUG_DATA_KEY,
   AGENT_SESSIONS_KEY,
   AgentContextProvider,
   AgentToolContext,