bs-agent 0.0.27 → 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",
@@ -416,9 +415,9 @@ raw delta → textDeltaModifier(delta) → accumulated text → fullTextModifier
 `textDeltaModifier` acts as a per-chunk preprocessor; `fullTextModifier` acts as
 a post-accumulation formatter on top of the already-modified text.
 
-> **Note:** `_rawText` stores the `textDeltaModifier`-processed accumulation,
-> not the original unmodified stream. If `textDeltaModifier` strips content,
-> `fullTextModifier` will never see it.
+> **Note:** If `textDeltaModifier` strips or transforms content,
+> `fullTextModifier` will only see the already-modified accumulation — the
+> original unmodified stream text is not preserved.
 
 ## `useAgentContext` Hook
 
@@ -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>
       ))}